Jesse_Chen
f62977f2c0
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LVapmh2oGNyr6ECHKjPJY8
51 lines
4.3 KiB
Markdown
51 lines
4.3 KiB
Markdown
# 任务书 · Python 引擎运行时治理（2026-09-01）
|
||
|
||
基线：`origin/staging` 最新。本轮**不碰 `frontend/src/app/page.tsx`**，可与拆页第三批并行。改动面：`deploy/`、`scripts/`、`tests/`、`AGENTS.md`、`docs/`。
|
||
|
||
## 为什么要做（事故实证）
|
||
|
||
1. **api 容器没有任何持久卷。** `deploy/docker-compose.server.yml` 里只有 caddy 挂了卷（`caddy_data` / `caddy_config`），api 服务一个卷都没有。而 `scripts/jyotish_api_server.py` 的异步任务态默认落 `scratch/local/async_jobs`（file 后端，`JYOTISH_ASYNC_JOB_BACKEND` 可选 sqlite，同样在 `scratch/local/async_jobs.sqlite3`），chart 缓存落 `scratch/local/api_chart_cache`。**每次部署/重启，进行中的异步任务状态直接蒸发**；chart 缓存全冷（可接受，但同因同治）。
|
||
2. **`scripts/jyotish_api_server.py` 已 11,035 行**，单文件承载全部端点。三轮前端治理的经验：巨石只会继续膨胀，除非有测试锁住。
|
||
3. **重计算端点没有并发上限。** ThreadingHTTPServer 每请求一线程，2 vCPU 生产机上多个校正扫描/高严谨排盘并发时互相挤压，最坏拖垮健康检查。
|
||
|
||
## 决策记录（产品授权，2026-09-01）
|
||
|
||
1. api 服务加命名卷持久化 `scratch/local`（任务 1）。这是 `deploy/` 拓扑变更，`deploy/README.md` 是运维真相源，必须同步更新。
|
||
2. `jyotish_api_server.py` **冻结增长**：新端点/新功能必须落独立模块由主文件薄注册，锁文件行数的合同测试入 quick gate（任务 2）。
|
||
3. 重计算端点加有界并发（任务 3）。饱和时快速失败（429 + Retry-After）优于排长队——前端各调用方已有错误/重试路径。
|
||
4. **迁移 squash 本轮明确不做**：需要 staging/production 双环境维护窗口与备份演练配合，收益（新环境重放耗时）目前不痛。延后条件：出现新环境搭建需求或迁移重放实际出错时再立项。
|
||
|
||
## 硬红线
|
||
|
||
1. 不改 `.gitea/workflows/**`。deploy 脚本（`run-staging-deploy.sh` 等）如需感知新卷，改动最小化并在 PROGRESS 说明。
|
||
2. 生产 compose（`docker-compose.server.yml` 为 staging/production 共用基座）改动必须向后兼容：卷不存在时首次创建、已有容器内数据无需迁移（本来就是易失的）。
|
||
3. 并发上限必须可配置（环境变量，含默认值），默认值保守（建议 2，与 vCPU 对齐）；健康检查端点绝不能被并发闸门挡住。
|
||
4. Python 测试：`tests/test_api_server_security.py` 等既有套件不得回归；新增锁测试入 `CORE_PYTEST_TARGETS`。行数锁的基线取现值上浮小余量（建议 +300 行，容 bugfix），注释写明"新功能请开模块"。
|
||
5. 前端不动；`npm test` 基线照常逐条比对。tsc 不适用本轮 Python 侧，但若碰 `frontend/` 则照旧全套。
|
||
6. 不在脏工作树切分支；不自行提升 main。
|
||
|
||
让步顺序：生产不中断 > 数据不损坏 > 功能与测试不回归 > 代码整洁。
|
||
|
||
## 任务分解
|
||
|
||
### 任务 1（P0）· api 持久卷
|
||
|
||
- `docker-compose.server.yml` 的 api 服务加命名卷挂到容器内 `scratch/local` 的实际路径（先读 `deploy/railway-api.Dockerfile` 确认工作目录，不要猜）。
|
||
- `deploy/README.md` 架构段与备份说明同步；staging 备份脚本是否需要覆盖该卷，评估后写结论（chart 缓存不值得备份；异步任务态短生命周期，说明白即可）。
|
||
- 验收：staging 部署后 `docker volume ls` 见新卷；重启 api 容器后 `scratch/local` 内容存活；`/api/health` 正常。
|
||
|
||
### 任务 2（P1）· 冻结巨石
|
||
|
||
- `AGENTS.md`（根目录）加规矩：`scripts/jyotish_api_server.py` 只减不增，新端点开模块注册。
|
||
- 新合同测试锁行数上限（红线 4），入 quick gate。
|
||
|
||
### 任务 3（P1）· 重计算并发闸
|
||
|
||
- 盘点主文件里最重的计算端点（校正扫描、高严谨排盘类；按实际 handler 认定，PROGRESS 列清单），加共享有界信号量：获取失败立即 429 + `Retry-After`。
|
||
- 健康检查与轻量端点不经过闸门。
|
||
- 测试：并发占满时第 N+1 个请求得到 429；释放后恢复。
|
||
|
||
## 总验收
|
||
|
||
quick gate 全绿（含新锁测试）；staging 部署实测任务 1 的三条；PROGRESS 附并发闸端点清单与压测/并发测试输出；`deploy/README.md` 更新可读。
|