更新readme

Author: inliver233

README.md

@@ -1,113 +1,147 @@
 # Random Mage (new-pixiv-api)
 
-一个自托管的随机图片 API：把 Pixiv 原图链接导入到本地数据库后，即可通过 `/random` 按 **标签 / 热度 / 分辨率 / R18 / AI / 作品类型** 等条件组合筛选并随机出图；同时提供管理后台（Web UI）+ 后台 Worker，用于导入、补全元数据、代理探测等任务。
-
-官方 Demo（公开站点）：
+自托管的 Pixiv 随机图片服务：将原图链接导入本地数据库后，通过 `GET /random` 按标签、热度、分辨率、R18、AI、作品类型等条件组合筛选并随机出图。项目同时提供管理后台（Web UI）与后台 Worker（导入/补全/代理探测等任务）。
 
+官方演示站：
 - `https://i.mukyu.ru/random`
 - `https://i.mukyu.ru/docs`
 - `https://i.mukyu.ru/api/docs`
 
-> 免责声明：本项目为非官方实现；请遵守 Pixiv ToS/版权与当地法律法规，自行承担使用风险。不要将任何 refresh_token / 密钥 / 代理密码提交到仓库。
-
-## 功能概览
-
-- 公共 API
-  - `GET /random`：默认直接返回图片流；也可 `format=json|simple_json` 返回 JSON；支持大量筛选参数
-  - `GET /images` / `GET /images/{id}`：按条件分页查看已入库图片
-  - `GET /i/{image_id}.{ext}`：本地代理/缓存路径（`/random?redirect=1` 会跳转到这里）
-  - `GET /tags`、`GET /authors`、`GET /healthz`、`GET /version`、`GET /docs`（人类可读文档页）
-  - Swagger / OpenAPI：`GET /api/docs`、`GET /openapi.json`
-- 管理后台（`/admin`）
-  - 登录后可管理：Pixiv refresh_token、代理池、导入、任务队列、运行时开关、审计/统计等
-- Worker（后台任务）
-  - 导入图片 URL、补全元数据（tags/宽高/浏览收藏等）、修复失效 URL、代理探测等
-- 可选能力
-  - 公网访问保护：启用 Public API Key + 限流
-  - `imgproxy`：对外提供签名处理 URL（可隐藏 origin URL）
-  - 代理路由：为上游图片/接口选择代理
-
-## 快速体验（使用官方 Demo）
-
-```bash
-curl -L "https://i.mukyu.ru/random?redirect=1"
-curl "https://i.mukyu.ru/random?format=simple_json"
-```
-
-## 一键部署（Docker Compose，推荐）
-
-前置：安装 Docker + Docker Compose。
-
-1) 准备环境变量
+> 免责声明：本项目为非官方实现。请遵守 Pixiv ToS、版权与当地法律法规；不要将 `refresh_token`、密钥、代理密码提交到仓库。
+
+## 近期功能更新（基于最近提交）
+
+- `ec9d373`：增强 `/wtf` 顶部筛选布局，支持标签排除筛选、`proxy` 参数自定义反代、选中反馈与单击放大。
+- `ef66583`：支持导入 PixivBatchDownloader 导出的 `.json`，并默认关闭该格式的导入后补全。
+- `9e437d8` + `80cd41f` + `5159d82` + `53e0890`：持续优化瀑布流页，新增标准/小格子两种展示模式。
+- `6a843ce`：新增公开状态页 `/status` 与 JSON 版本 `/status.json`，并持久化随机请求总量。
+- `638a285` + `ee0549b`：增强 pximg 反代能力（含 pixiv.cat / 镜像），改进 docs/status 页面与并发场景稳定性。
+- `810b2da`：修复大量导入下的数据库冲突问题。
+
+## 项目能力总览
+
+### 1) 公开 API
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /random` | 随机取图（默认图片流），支持 `format=json/simple_json` 与复杂过滤条件 |
+| `GET /images` | 分页查询入库图片，支持标签、尺寸、时间等筛选 |
+| `GET /images/{image_id}` | 查询单张图片及标签 |
+| `GET /i/{image_id}.{ext}` | 本地代理/缓存路径（`/random?redirect=1` 跳转到这里） |
+| `GET /{illust_id}.{ext}` / `GET /{illust_id}-{page}.{ext}` | 兼容旧式直链路径 |
+| `GET /tags` / `GET /authors` | 标签与作者检索 |
+| `GET /healthz` | 健康检查（DB、Worker 心跳、队列状态） |
+| `GET /version` | 版本、构建时间、commit |
+| `GET /docs` | 人类可读文档页 |
+| `GET /status` / `GET /status.json` | 公开运行状态（图库统计 + 随机请求统计） |
+| `GET /wtf` | 瀑布流浏览页（标准/小格子视图） |
+| `GET /api/docs` / `GET /openapi.json` | Swagger/OpenAPI |
+
+`/random` 的常用能力：
+- 输出模式：`format=image|json|simple_json`，`redirect=1`。
+- 策略：`strategy=quality|random`，`quality_samples`，可配置 recommendation 权重与倍率。
+- 过滤：`r18`、`r18_strict`、`ai_type`、`illust_type`、`orientation/layout`。
+- 阈值：`min_width`、`min_height`、`min_pixels`、`min_bookmarks`、`min_views`、`min_comments`。
+- 标签：`included_tags`、`excluded_tags`（支持 `|` 表示组内 OR）。
+- 其他：`user_id`、`illust_id`、`created_from`、`created_to`、`seed`、`attempts`、`adaptive=1`。
+
+标签语义说明：
+- 组间是 AND：`included_tags=a&included_tags=b`
+- 组内是 OR：`included_tags=a|b`
+
+### 2) 管理后台（`/admin` + `/admin/api/*`）
+
+核心模块：
+- 登录鉴权：JWT 登录/登出。
+- 导入中心：支持文本粘贴、`.txt` 上传、PixivBatchDownloader `.json` 上传、预检查（dry-run）、回滚。
+- 图片管理：分页筛选、删除、批量删除、清库。
+- 补全管理：创建/手动触发补全任务、暂停/恢复/取消。
+- 任务队列：查看任务、重试、取消、转入 DLQ。
+- 令牌管理：Pixiv refresh_token 增删改查、测试刷新、失败重置。
+- 代理体系：代理节点导入/编辑/清理/探测，代理池维护。
+- 绑定关系：Token 与代理池绑定重算、覆盖、清除覆盖。
+- 系统设置：随机默认策略、代理路由模式、图片反代行为、安全开关等。
+- 审计日志、汇总统计、公共 API Key 管理、请求日志清理。
+
+### 3) Worker（后台任务执行）
+
+内置任务类型包括：
+- `import_images`
+- `hydrate_metadata`
+- `heal_url`
+- `proxy_probe`
+- `easy_proxies_import`
+
+关键特性：
+- 按 `enabled token` 数自动调整并发（可关闭）。
+- 写入 `worker.last_seen_at` 心跳到运行时设置。
+- SQLite busy 重试与并发参数调优，降低高并发导入冲突概率。
+
+## 快速部署（Docker Compose，推荐）
+
+前置：`Docker` + `Docker Compose`。
+
+1. 准备环境变量
 
 ```bash
 cp deploy/.env.example deploy/.env
 ```
 
-然后编辑 `deploy/.env`，至少建议修改：
-
-- `SECRET_KEY`：JWT/API Key 哈希用（生产环境必须修改）
-- `ADMIN_PASSWORD`：后台密码（生产环境必须修改）
-- `FIELD_ENCRYPTION_KEY`：用于加密保存 refresh_token（生产环境必须提供；建议用 secret 挂载或文件方式）
+2. 编辑 `deploy/.env`（至少修改以下项）
+- `SECRET_KEY`
+- `ADMIN_PASSWORD`
+- `FIELD_ENCRYPTION_KEY`（生产环境必须提供）
 
-2) 启动
+3. 启动
 
 ```bash
 docker compose -f deploy/docker-compose.yml up -d --build
 ```
 
-3) 访问
-
-- API 基址：`http://localhost:23222`
-- 健康检查：`GET http://localhost:23222/healthz`
-- 文档页：`GET http://localhost:23222/docs`
-- 后台 UI：`http://localhost:23222/admin`
+4. 访问
+- API：`http://localhost:23222`
+- 文档页：`http://localhost:23222/docs`
+- 状态页：`http://localhost:23222/status`
 - Swagger：`http://localhost:23222/api/docs`
-
-## 首次使用（导入数据 + 补全元数据）
-
-这个项目不会“自动替你抓全站图片”，你需要先把图片记录导入数据库。
-
-1) 登录后台
-
-- 打开 `http://localhost:23222/admin`
-- 使用 `deploy/.env` 中的 `ADMIN_USERNAME` / `ADMIN_PASSWORD` 登录
-
-2) 导入图片原图 URL
-
-后台提供“导入”入口，支持：
-
-- 直接粘贴多行文本（每行一个 URL）
-- 上传 `.txt` 文件（同样每行一个 URL）
-
-导入内容应为 Pixiv 原图链接（例如 `i.pximg.net/.../img-original/...` 这类）。导入时会自动去重（按 illust_id + page）。
-
-3) 配置 Pixiv refresh_token（可选，但强烈建议）
-
-若你希望 Worker 自动补全/刷新元数据（tags、宽高、浏览/收藏/评论、R18 标记、AI 类型等），需要：
-
-- 在后台添加一个或多个 refresh_token
-- 配置 `PIXIV_OAUTH_CLIENT_ID` / `PIXIV_OAUTH_CLIENT_SECRET`（以及可选的 `PIXIV_OAUTH_HASH_SECRET`）
-
-> 安全提示：refresh_token 属于敏感凭据；请只放在运行环境里（`deploy/.env` / secret 管理），不要写进代码/仓库。
-
-4) 确认 Worker 正常
-
-`/healthz` 会同时检查 DB、队列、以及 Worker 心跳；如果 `worker_ok=false`，通常意味着 Worker 没启动或无法连接数据库卷。
-
-## 配置说明（节选）
-
-所有配置均通过环境变量注入（见 `deploy/.env.example`）：
-
-- `APP_ENV`：`dev` / `prod`（`prod` 会启用更严格的必填校验）
-- `DATABASE_URL`：默认 SQLite（容器内 `/app/data/app.db`，通过 `../data:/app/data` 挂载）
-- `PUBLIC_API_KEY_REQUIRED` / `PUBLIC_API_KEY_RPM` / `PUBLIC_API_KEY_BURST`：公网访问保护（可选）
-- `WORKER_*`、`IMPORT_*`、`SQLITE_BUSY_TIMEOUT_MS`：Worker/导入/SQLite 运行参数
-- `IMGPROXY_*`：imgproxy 集成（可选）
-
-## 本地开发（可选）
-
-后端（Python 3.11）：
+- 管理后台：`http://localhost:23222/admin`
+
+## 首次使用建议流程
+
+1. 登录管理后台：使用 `ADMIN_USERNAME` / `ADMIN_PASSWORD`。
+2. 导入图片链接（导入页）：
+   - 方式 A：粘贴多行原图 URL。
+   - 方式 B：上传 `.txt`（每行一个 URL）。
+   - 方式 C：上传 PixivBatchDownloader `.json`（会尽量提取并写入元数据/标签，默认不再额外补全）。
+3. （可选但建议）配置 Pixiv refresh_token：用于后续补全/刷新元数据。
+4. 观察状态：
+   - `GET /healthz`：看 `worker_ok` 与队列状态。
+   - 管理后台任务页：看导入与补全进度。
+
+## 关键配置项（节选）
+
+以 `deploy/.env.example` 为准，常用项如下：
+
+| 变量 | 作用 |
+| --- | --- |
+| `APP_ENV` | 运行环境（`dev` / `prod`） |
+| `DATABASE_URL` | 数据库连接（默认 SQLite） |
+| `SECRET_KEY` | JWT / API Key 哈希密钥 |
+| `FIELD_ENCRYPTION_KEY` / `FIELD_ENCRYPTION_KEY_FILE` | 敏感字段加密密钥 |
+| `ADMIN_USERNAME` / `ADMIN_PASSWORD` | 后台账号密码 |
+| `PIXIV_OAUTH_CLIENT_ID` / `PIXIV_OAUTH_CLIENT_SECRET` / `PIXIV_OAUTH_HASH_SECRET` | Pixiv OAuth 参数 |
+| `WORKER_AUTO_CONCURRENCY` / `WORKER_MAX_CONCURRENCY` | Worker 并发策略 |
+| `IMGPROXY_*` | imgproxy 签名 URL 能力 |
+| `PUBLIC_API_KEY_REQUIRED` / `PUBLIC_API_KEY_RPM` / `PUBLIC_API_KEY_BURST` | 公开接口 API Key 与限流 |
+
+高级运行参数（按需）：
+- `SQLITE_BUSY_TIMEOUT_MS`、`SQLITE_POOL_SIZE`、`SQLITE_MAX_OVERFLOW`、`SQLITE_POOL_TIMEOUT_S`
+- `IMPORT_MAX_BYTES`、`IMPORT_INLINE_MAX_ACCEPTED`
+- `RANDOM_TOTALS_PERSIST_INTERVAL_SECONDS`
+- `WORKER_HEARTBEAT_INTERVAL_SECONDS`、`WORKER_HEARTBEAT_STALE_SECONDS`
+
+## 本地开发
+
+### 后端（Python 3.11）
 
 ```bash
 cd backend
@@ -118,17 +152,53 @@ alembic upgrade head
 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 ```
 
-前端管理台（Node 20）：
+另开一个终端运行 Worker：
+
+```bash
+cd backend
+.\.venv\Scripts\activate
+python -m app.worker
+```
+
+### 前端（Node 20）
 
 ```bash
 cd frontend
 npm ci
 npm run dev
 ```
 
-如需让前端直连本地后端，设置 `VITE_API_BASE_URL`（例如 `http://localhost:8000`）。
+如需前端直连本地后端，可设置 `VITE_API_BASE_URL=http://localhost:8000`。
 
-## 运行测试
+## 测试与检查
 
 - 后端：`python -m pytest -q backend/tests`
 - 前端：`cd frontend && npm test`
+- 一键脚本：
+  - `scripts/test_backend.ps1`
+  - `scripts/test_frontend.ps1`
+  - `scripts/test_all.ps1`
+
+## 目录结构（简版）
+
+```text
+.
+├─ backend/
+│  ├─ app/
+│  │  ├─ api/          # public + admin 路由
+│  │  ├─ core/         # 配置、安全、代理路由、指标
+│  │  ├─ db/           # 模型与查询
+│  │  ├─ jobs/         # 队列、调度、任务处理器
+│  │  └─ worker.py
+│  └─ tests/
+├─ frontend/           # React + Vite 管理后台
+├─ deploy/             # compose 与环境变量示例
+└─ scripts/            # 测试与辅助脚本
+```
+
+## 合规与安全建议
+
+- 切勿将任何真实令牌或密钥提交到仓库。
+- 公网部署建议开启 `PUBLIC_API_KEY_REQUIRED` 并配置限流。
+- 生产环境务必设置强密码与独立密钥。
+