Jesse_Chen
f62977f2c0
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LVapmh2oGNyr6ECHKjPJY8
4.3 KiB
4.3 KiB
任务书 · Python 引擎运行时治理（2026-09-01）
基线：origin/staging 最新。本轮不碰 frontend/src/app/page.tsx，可与拆页第三批并行。改动面：deploy/、scripts/、tests/、AGENTS.md、docs/。
为什么要做（事故实证）
- 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 缓存全冷（可接受，但同因同治）。 scripts/jyotish_api_server.py已 11,035 行，单文件承载全部端点。三轮前端治理的经验：巨石只会继续膨胀，除非有测试锁住。- 重计算端点没有并发上限。 ThreadingHTTPServer 每请求一线程，2 vCPU 生产机上多个校正扫描/高严谨排盘并发时互相挤压，最坏拖垮健康检查。
决策记录（产品授权，2026-09-01）
- api 服务加命名卷持久化
scratch/local（任务 1）。这是deploy/拓扑变更，deploy/README.md是运维真相源，必须同步更新。 jyotish_api_server.py冻结增长：新端点/新功能必须落独立模块由主文件薄注册，锁文件行数的合同测试入 quick gate（任务 2）。- 重计算端点加有界并发（任务 3）。饱和时快速失败（429 + Retry-After）优于排长队——前端各调用方已有错误/重试路径。
- 迁移 squash 本轮明确不做：需要 staging/production 双环境维护窗口与备份演练配合，收益（新环境重放耗时）目前不痛。延后条件：出现新环境搭建需求或迁移重放实际出错时再立项。
硬红线
- 不改
.gitea/workflows/**。deploy 脚本（run-staging-deploy.sh等）如需感知新卷，改动最小化并在 PROGRESS 说明。 - 生产 compose（
docker-compose.server.yml为 staging/production 共用基座）改动必须向后兼容：卷不存在时首次创建、已有容器内数据无需迁移（本来就是易失的）。 - 并发上限必须可配置（环境变量，含默认值），默认值保守（建议 2，与 vCPU 对齐）；健康检查端点绝不能被并发闸门挡住。
- Python 测试：
tests/test_api_server_security.py等既有套件不得回归；新增锁测试入CORE_PYTEST_TARGETS。行数锁的基线取现值上浮小余量（建议 +300 行，容 bugfix），注释写明"新功能请开模块"。 - 前端不动；
npm test基线照常逐条比对。tsc 不适用本轮 Python 侧，但若碰frontend/则照旧全套。 - 不在脏工作树切分支；不自行提升 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 更新可读。