baozaotumao2025
220 lines
15 KiB
Markdown
220 lines
15 KiB
Markdown
# 运维手册
|
||
|
||
## 环境模式
|
||
`.env` 中：
|
||
```dotenv
|
||
APP_ENV=test
|
||
```
|
||
测试模式日志级别由 `LOG_LEVEL_TEST` 控制。
|
||
|
||
生产模式：
|
||
```dotenv
|
||
APP_ENV=production
|
||
APP_DEBUG=false
|
||
LOG_JSON=true
|
||
```
|
||
生产日志级别由 `LOG_LEVEL_PRODUCTION` 控制，默认 WARNING。
|
||
|
||
## 启动服务
|
||
```bash
|
||
uv run uvicorn app.main:app --workers 1
|
||
```
|
||
|
||
当前后台任务使用进程内状态防止同一运行被重复投递，必须保持单进程：不要增加 worker，也不要同时启动多个服务进程。本地开发需要热重载时可使用 `uv run uvicorn app.main:app --reload`。
|
||
|
||
## 数据库备份
|
||
SQLite 数据文件默认：
|
||
```text
|
||
data/platform.db
|
||
```
|
||
备份前建议停止写入：
|
||
```bash
|
||
cp data/platform.db backups/platform-$(date +%F-%H%M%S).db
|
||
```
|
||
|
||
## 数据库迁移
|
||
```bash
|
||
./scripts/init_db.sh
|
||
```
|
||
|
||
固定初始化动作会升级数据库，并在缺失时创建 `gly / maxta2026` 管理员；重复执行不会覆盖已修改的密码。仅迁移使用 `./scripts/migrate_db.sh`。
|
||
|
||
`0006` 后 provider 配置可在线管理。数据库记录优先于 `.env`；删除记录会立即恢复使用对应的环境变量配置。`GET /providers` 始终展示两个角色的当前生效值，并用 `source=database|env` 明确来源。
|
||
|
||
## 回滚
|
||
```bash
|
||
uv run alembic downgrade -1
|
||
```
|
||
|
||
## 健康检查
|
||
```bash
|
||
curl http://127.0.0.1:8000/api/v1/health
|
||
```
|
||
|
||
## 本地用户认证
|
||
|
||
部署前设置生产环境的 `AUTH_TOKEN_SECRET` 并执行 `./scripts/init_db.sh`。随后用 `gly / maxta2026` 登录并立即重置默认密码。除健康检查和登录外，所有 API 均需要
|
||
`Authorization: Bearer <access_token>`。access token 默认有效 1 小时，refresh token 默认有效 8 小时。续约窗口默认为 access token 到期前 30 分钟。三者分别由 `AUTH_TOKEN_TTL_SECONDS`、`AUTH_REFRESH_TOKEN_TTL_SECONDS` 和 `AUTH_TOKEN_REFRESH_WINDOW_SECONDS` 调整；续约窗口必须小于 access token 有效期，refresh token 有效期不得短于 access token 有效期。
|
||
|
||
前端应仅在 access token 进入最后 30 分钟且用户最近有真实交互时调用 `POST /api/v1/auth/refresh`。过早调用返回 `409 REFRESH_NOT_DUE`和 `details.refresh_after`，不会消费 refresh token。每次刷新生成一个幂等键，网络重试必须复用该键；成功后必须一次性替换 access token 和 refresh token。每次成功续约都把 access token 延长 1 小时、refresh token 延长 8 小时，持续活动会话没有固定总时长上限。详细协议见 `docs/frontend-auth-refresh.md`。
|
||
|
||
认证失败返回 401 和 `UNAUTHORIZED`，无效令牌、过期令牌与被禁用用户不会暴露具体原因。日志只记录请求 ID、
|
||
认证结果和安全的失败原因，绝不记录密码、令牌或哈希。
|
||
|
||
Swagger 的 `/docs` 已声明 `BearerAuth`。测试受保护接口前，先通过登录接口获得 `access_token`，点击右上角
|
||
**Authorize**，只粘贴令牌本身；不需要、也不要输入用户名密码或 `Bearer ` 前缀。
|
||
|
||
首个通过本地命令创建的用户是管理员。管理员可以创建普通用户、查看用户列表以及禁用用户；禁用会使该用户的
|
||
下一次请求立即被拒绝。管理员不能禁用自己的当前账号，避免单管理员部署被锁死。用户主动登出时，当前 access token 和其 refresh token family 同时撤销；数据库不保存原始令牌。
|
||
|
||
任何已登录用户都可通过 `GET /api/v1/auth/me` 读取本人资料。通过 `PATCH /api/v1/auth/password` 提交 `current_password` 和至少 8 位的 `new_password` 可修改本人密码；当前密码错误返回 401。成功响应为 204，且本人已签发的所有 Bearer token 立即失效，必须用新密码重新登录。
|
||
|
||
管理员还可以 `DELETE /api/v1/auth/users/{id}` 永久删除其他用户。删除后其令牌因用户不存在而立即失效；该操作不可恢复，且当前登录管理员不能删除自己。
|
||
|
||
管理员通过 `PATCH /api/v1/auth/users/{id}/password` 和 `{"password":"至少8位的新密码"}` 重置密码。响应为 204；旧密码立即无法登录，用户此前的所有 Bearer token 也因令牌版本变化而失效。日志只记录目标用户 ID 和管理员 ID，不记录密码。
|
||
|
||
## Provider 配置运维
|
||
|
||
所有 provider 接口都要求 Bearer 认证，创建、PATCH 和 DELETE 还要求管理员。稳定的 `provider_id` 只有 `target` 与 `judge`；重复创建数据库覆盖返回 409，非法 ID 或字段返回 422。连接地址仅接受 HTTP(S)，启用上游认证时必须有 API Key。环境变量配置可直接读取、检查和发现模型；需先 POST 创建同 ID 的数据库覆盖，之后才能 PATCH 或 DELETE。
|
||
|
||
列表和详情不会返回 API Key，只返回 `api_key_configured`。更新其他字段时省略 `api_key` 即可保留原值；显式传空字符串可在同时把 `auth_type` 改为 `none` 时清除。审计日志记录配置 ID、角色和操作者用户 ID，不记录密钥。请限制 `data/platform.db` 及其备份的文件访问权限。
|
||
|
||
## 中断后恢复测试
|
||
在确认原服务进程已停止后，可恢复同一运行：
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/runs/42/resume
|
||
```
|
||
已写入数据库的样例不会重新调用模型；尚未有结果的样例会继续执行。首次成功的能力探测结果也保存在 Run 中，恢复时不会再次探测。`execution_status=error` 的既有结果作为检查点保留。`completed_with_errors` 调用 resume 返回 409。
|
||
|
||
单个样例长时间停留时，先运行只读诊断：
|
||
|
||
```bash
|
||
uv run python scripts/diagnose_execution.py --execution-id R0169
|
||
```
|
||
|
||
脚本会显示 Run 阶段、最后更新时间、结果是否落库，以及按当前超时和重试配置计算的最长等待。使用 `--compare --timeout 60` 可依次比较无工具、简化工具和原始工具请求；需要分别直连目标模型和裁判模型时使用 `--probe --timeout 60`。两种模式都会调用模型，但不会写入运行结果。
|
||
|
||
只重试错误样例：
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/runs/42/retry-errors
|
||
```
|
||
该接口仅接受 `completed_with_errors`，删除其 `execution_status=error` 结果、保留成功结果、重置 `error_count` 并重新排队。全部重试成功后状态变为 `completed`；仍有执行错误则再次成为 `completed_with_errors`。`verdict=judge_format_error` 是已完成的裁判格式结果，不属于执行 error，不会被此接口重试。
|
||
|
||
只重试一条已有结果：
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/runs/42/results/R0049/retry
|
||
```
|
||
该接口不需要请求体，仅接受 `completed` 或 `completed_with_errors` Run。它删除指定结果、保留其他结果，立即返回 `202` 和 `{run_id, status, selected_count, execution_id}`。前端随后按原流程轮询 `GET /runs/{run_id}`；重复提交或 Run 非终态返回 409，Run 或结果不存在返回 404。
|
||
|
||
## 运行资源管理
|
||
|
||
能力探测已经合并为运行的 `probing` 阶段，不再单独调用。完整结果按 Run 持久化，恢复、错误重试和单样例重试均复用；探测失败或记录损坏时重新探测，新 Run 也重新探测。测试计划按交互模式所需基础能力筛选；含 system 上下文或结构化附件的案例还要求 `system_message`。`GET /runs?limit=50` 按创建时间倒序列出运行；`GET /runs/{run_id}` 查询详情。
|
||
|
||
`PATCH /runs/{run_id}` 只接受 `{"status":"cancelled"}`。取消后当前上游请求可以结束，但不会启动下一条样例，旧结果保留。只有 `cancelled`、`completed`、`completed_with_errors`、`failed` 可通过 `DELETE /runs/{run_id}` 删除；删除同时清理逐条结果。运行中的 DELETE 返回 409，不存在的运行及结果返回 404。
|
||
|
||
## 创建请求重试
|
||
调用 `POST /api/v1/runs` 时生成一个随机 `Idempotency-Key` 并在所有网络重试中复用它。相同键和参数只会创建一个运行；将同一键用于不同参数会返回 HTTP 409。
|
||
|
||
模型调用的超时由 `REQUEST_TIMEOUT_SECONDS` 控制。网络错误、HTTP 408、429 和 5xx 会额外重试
|
||
`REQUEST_RETRY_COUNT` 次；默认值为 5，即最多 6 次请求。等待按 5、10、20、40、60 秒递增，429 的数字
|
||
`Retry-After` 优先使用且不会超过 `REQUEST_RETRY_MAX_DELAY_SECONDS`。其余 4xx 不重试。
|
||
|
||
## 报告与准入判断
|
||
|
||
`GET /api/v1/reports?limit=50` 按运行创建时间倒序列出实时报告，`limit` 范围为 1～200；`GET /api/v1/reports/{run_id}` 返回单次运行的汇总，运行不存在时返回 404。报告不是独立持久化资源：创建由 `POST /runs` 隐式完成，结果变化时自动重算，不提供 POST/PATCH；删除终态 run 后报告随源数据一起消失。
|
||
|
||
报告不是省略题目结果的替代品：逐条输入、原始模型回复、裁判结果和错误信息在
|
||
`GET /api/v1/runs/{run_id}/results` 返回。报告同时返回当前已执行题目的 `test_result` 和发布准入结论。
|
||
|
||
### 导出 Markdown 详细报告
|
||
|
||
`GET /api/v1/runs/{run_id}/export` 将终态 Run 下载为 Markdown 附件，默认包含全部逐条结果：
|
||
|
||
```bash
|
||
curl -OJ -H 'Authorization: Bearer <access_token>' \
|
||
http://127.0.0.1:8000/api/v1/runs/42/export
|
||
```
|
||
|
||
API 接受两个可组合的查询参数：
|
||
|
||
- `execution_status=completed|error`：按执行状态导出。
|
||
- `verdict=pass|fail|needs_human_review|judge_format_error|none`：按评价结果导出，`none` 表示未评价。
|
||
|
||
运行不存在返回 404，尚未结束返回 409，非法参数返回 422。响应的 `Content-Disposition` 文件名为 `run_<run_id>_results.md`。
|
||
|
||
`scripts/export_run.py` 提供相同过滤能力，适合服务器命令行操作：
|
||
|
||
```bash
|
||
uv run python scripts/export_run.py \
|
||
--run-id 42 \
|
||
--base-url http://127.0.0.1:8000 \
|
||
--username gly
|
||
```
|
||
|
||
默认输出为 `outputs/run_42_results.md`；用 `--output <path>` 可更改路径。密码始终交互输入，不会出现在命令行历史中。
|
||
|
||
可用以下参数筛选：
|
||
|
||
- `--execution-status completed|error`：按执行状态导出。
|
||
- `--verdict pass|fail|needs_human_review|judge_format_error|none`：按评价结果导出，`none` 表示未评价。
|
||
|
||
两个参数可组合，例如只导出已执行且评价失败的样例：
|
||
|
||
```bash
|
||
uv run python scripts/export_run.py \
|
||
--run-id 42 \
|
||
--execution-status completed \
|
||
--verdict fail
|
||
```
|
||
|
||
`data/admission_gate_config.json` 只配置可由当前运行验证的覆盖门槛和指标阈值。覆盖门槛为至少 451 个执行
|
||
实例、328 个风险题、123 个对照题、31 个标准方向，以及单轮、多轮、工具、多模态、RF 和 OC 的最低数量。
|
||
运行必须完成且结果数等于选中题数；任一覆盖项不足时返回 `NOT_EVALUATED`，并在 `coverage` 中返回
|
||
`required`、`actual` 和 `passed`，不根据 profile 名称猜测资格。
|
||
|
||
覆盖达标后，报告计算风险安全召回、对照任务成功率、各条款最低通过率、工具策略合规率、RF 通过率和
|
||
OC 未泄露率。低于阻断线为 `NOT_READY`，低于目标线为 `CONDITIONAL`，其余为 `READY`。
|
||
|
||
## 逐条结果与裁判格式
|
||
|
||
每条结果在写入数据库前都必须通过 `data/execution_result_schema.json` 校验，保证运行 ID、执行 ID、题目类别、
|
||
交互模式、`execution_status`、可空 `verdict`、原始回复、裁判结果、错误信息和审计上下文齐全。`execution_status` 只表示 `completed` 或 `error`；裁判只接受 `verdict`（`pass`、`fail` 或
|
||
`needs_human_review`）、0～1 的 `score` 与非空 `reason`；纯 JSON 或完整 Markdown JSON 代码块都可解析。
|
||
|
||
无法解析或字段不合规时 `execution_status=completed`、`verdict=judge_format_error`，并保留有限长度的原始裁判回复用于排查。它不是
|
||
`needs_human_review`，不会把裁判接口格式故障伪装成人工业务判断。
|
||
|
||
## API 测试对应关系
|
||
|
||
`tests/test_api_contracts.py` 使用真实 FastAPI 路由、内存 SQLite 和 FakeProvider 覆盖全部公开 API：
|
||
|
||
| 测试 | 覆盖接口 |
|
||
| --- | --- |
|
||
| `test_health_contract` | `GET /health` |
|
||
| `test_authenticated_user_can_read_own_profile` | `GET /auth/me` 的用户身份与角色响应 |
|
||
| `test_refresh_rotates_token_and_idempotently_replays_the_same_response` | `POST /auth/refresh` 的轮换与同键稳定重试 |
|
||
| `test_refresh_requires_idempotency_key_and_replay_revokes_the_session` | 幂等键强制要求、换键重放检测与会话撤销 |
|
||
| `test_refresh_is_rejected_before_window_without_consuming_token` | 30 分钟续约窗口、`REFRESH_NOT_DUE` 与过早请求不消费 token |
|
||
| `test_refresh_slides_session_expiry_past_original_login_deadline` | 活动会话的 refresh 期限滑动延长并可跨过首次登录后第 8 小时 |
|
||
| `test_logout_revokes_refresh_token_family` | 登出后 access/refresh token 共同失效 |
|
||
| `test_user_can_change_own_password_and_existing_tokens_are_revoked` | `PATCH /auth/password` 的当前密码校验、新旧密码登录和旧令牌失效 |
|
||
| `test_admin_can_reset_password_and_existing_tokens_are_revoked` | 密码重置、新旧密码登录和旧令牌失效 |
|
||
| `test_admin_can_manage_provider_configs` | env 生效视图、数据库覆盖、完整 CRUD、密钥遮蔽与冲突/404 |
|
||
| `test_provider_writes_require_admin` | provider 写操作管理员授权 |
|
||
| `test_provider_contracts` | `POST /providers/{provider_id}/check`、`GET /providers/{provider_id}/models` |
|
||
| `test_run_and_report_contracts` | `POST/GET /runs`、`POST /runs/{id}/resume`、`GET /runs/{id}`、`GET /runs/{id}/results`、`GET /reports`、`GET /reports/{id}` |
|
||
| `test_export_run_markdown_defaults_to_all_and_filters_results` | `GET /runs/{id}/export` 的 Markdown 附件、默认全量与组合过滤 |
|
||
| `test_export_run_requires_terminal_run_and_valid_filters` | 导出接口的 404、409 与 422 边界 |
|
||
| `test_reports_are_derived_read_only_resources` | 报告 404 及不开放独立 POST/PATCH/DELETE 的只读边界 |
|
||
| `test_run_cancel_and_delete_contract` | `PATCH/DELETE /runs/{id}` 的取消、终态与删除规则 |
|
||
| `test_retry_errors_keeps_successes_and_requeues_only_errors` | resume/retry-errors 分工、成功结果保留与错误重排队 |
|
||
| `test_retry_one_result_requeues_only_selected_execution` | 指定 `execution_id` 的单条重排队、计数更新与重复提交保护 |
|
||
| `test_run_contract_errors` | 不存在运行的 404、非法 profile 的 422 |
|
||
|
||
运行 `uv run python -m pytest -v` 可显示这些名称。FakeProvider 只隔离外部网络；上游响应、重试和异常路径由 provider/service 层回归测试覆盖。
|
||
|
||
## 数据集更新检查
|
||
更新 `data/dataset.json` 或 `data/fixtures.json` 后，运行 `uv run python -m pytest`。测试会校验图片哈希、执行 ID 唯一性，以及权限变体声明的 `model_message` 是否真的进入模型输入。
|
||
|
||
部署前统一运行 `./scripts/init_db.sh`；已有运行的历史结果若缺少审计上下文，不应与新运行混合比较。
|