整理代码并提交

Author: inliver233

.dockerignore

@@ -0,0 +1,24 @@
+.git
+.github
+.codex
+.venv
+.pytest_cache
+**/__pycache__/
+
+# Env / secrets
+.env
+.env.*
+!deploy/.env.example
+
+data/
+issues/
+plan/
+docs/
+参考资料/
+
+frontend/node_modules/
+frontend/dist/
+
+backend/.pytest_cache/
+
+_tmp_append_test.md

.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+      - test
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  backend-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
+
+      - name: Install dependencies
+        run: python -m pip install -r requirements-dev.txt
+
+      - name: Compile
+        run: python -m compileall -q backend
+
+      - name: Tests
+        run: python -m pytest -q backend/tests
+
+  frontend-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: frontend
+
+      - name: Lint
+        run: npm run lint
+        working-directory: frontend
+
+      - name: Typecheck
+        run: npm run typecheck
+        working-directory: frontend
+
+      - name: Tests
+        run: npm test
+        working-directory: frontend
+
+  compose-config:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Prepare deploy env file
+        run: |
+          if [ ! -f deploy/.env ]; then
+            cp deploy/.env.example deploy/.env
+          fi
+
+      - name: Validate docker compose config
+        run: docker compose -f deploy/docker-compose.yml config > /dev/null

.gitignore

@@ -0,0 +1,68 @@
+## Python
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+## Virtualenv
+.venv/
+venv/
+ENV/
+env/
+
+## Node
+node_modules/
+dist/
+.vite/
+
+## Runtime data / local state (never commit)
+data/
+backend/data/
+deploy/.env
+.env
+.env.*
+!.env.example
+!deploy/.env.example
+*.db
+*.sqlite
+*.sqlite3
+
+## Codex / AI tooling (repo-local)
+.codex/
+plan/
+issues/
+docs/
+参考资料/
+
+## Data exports / plans
+*.csv
+*.tsv
+*.plan.md
+
+## OS / IDE
+.DS_Store
+Thumbs.db
+desktop.ini
+.idea/
+.vscode/
+*.iml
+
+## Local temp / scratch
+*.log
+*.tmp
+要求.txt
+_tmp_easy_export.txt
+_tmp_*.md
+_tmp_*.txt
+
+## Keep public-facing docs at repo root
+/*.md
+!README.md
+!LICENSE*

README.md

@@ -0,0 +1,122 @@
+# Random Mage (new-pixiv-api)
+
+一个自托管的随机图片 API：把 Pixiv 原图链接导入到本地数据库后，即可通过 `/random` 按 **标签 / 热度 / 分辨率 / R18 / AI / 作品类型** 等条件组合筛选并随机出图；同时提供管理后台（Web UI）+ 后台 Worker，用于导入、补全元数据、代理探测等任务。
+
+> 免责声明：本项目为非官方实现；请遵守 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）
+  - 代理路由：为上游图片/接口选择代理
+
+## 一键部署（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) 启动
+
+```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`
+- 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）：
+
+```bash
+cd backend
+python -m venv .venv
+.\.venv\Scripts\activate
+python -m pip install -r ..\requirements-dev.txt
+alembic upgrade head
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+前端管理台（Node 20）：
+
+```bash
+cd frontend
+npm ci
+npm run dev
+```
+
+如需让前端直连本地后端，设置 `VITE_API_BASE_URL`（例如 `http://localhost:8000`）。
+
+## 运行测试
+
+- 后端：`python -m pytest -q backend/tests`
+- 前端：`cd frontend && npm test`
+

backend/Dockerfile

@@ -0,0 +1,33 @@
+FROM node:20-slim AS frontend-build
+
+WORKDIR /frontend
+
+COPY frontend/package.json frontend/package-lock.json /frontend/
+RUN npm ci --no-audit --no-fund
+
+COPY frontend/ /frontend/
+RUN npm run build
+
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+RUN python -m pip install --no-cache-dir --upgrade pip
+
+COPY requirements.txt /app/requirements.txt
+RUN python -m pip install --no-cache-dir -r /app/requirements.txt
+
+RUN mkdir -p /app/data /app/web
+
+COPY backend/app /app/app
+COPY backend/alembic.ini /app/alembic.ini
+COPY backend/alembic /app/alembic
+COPY --from=frontend-build /frontend/dist /app/web/dist
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/alembic.ini

@@ -0,0 +1,38 @@
+[alembic]
+script_location = %(here)s/alembic
+prepend_sys_path = %(here)s
+sqlalchemy.url = sqlite:///./data/app.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S
+