Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,15 @@ sudo ./deploy/deploy.sh --external-pg --domain 你的域名 --email 你@邮箱.c
生产运行进程。对外部署时请在项目根目录 `.env` 中显式设置
`APP_ENV=production`、`APP_SECRET_KEY` 和 `CORS_ORIGINS`;生产模式会拒绝默认密钥。

### 1.4 支持的进程与 worker 拓扑(重要约束)

**当前唯一受支持的拓扑:单 backend 进程**(`backend/Dockerfile` 的 CMD 为单 uvicorn 进程,无 `--workers`)。

- APScheduler 使用内存 jobstore(非持久化、无 leader election)。多实例部署时**所有实例都会各自调度**,仅靠 DB 层租约兜底:cron/interval job 由 `@track_job` 的 `scheduled_jobs` 表行锁互斥,源同步由 `claim_sync` 租约互斥,分析内容由 fencing token 保证正确性。但**启动恢复会把其它健康实例正在执行的 RUNNING 分析 job 重置为 QUEUED**——正确性有 fencing 保证,代价是重复 LLM 消耗。
- 多实例 HA 的前置条件:init container 单次执行 alembic(见 §6.3)+ 调度器 leader lease / fencing token(未实现,规划见 `docs/plan/llm-model-pool-roadmap.md`)。在那之前请保持单实例或用 `SCHEDULER_ENABLED=false` 拆分无调度器实例。
- **`SCHEDULER_ENABLED=false` 是受支持部署形态**(纯 API / worker 拆分实例):调度器不启动,`/health/ready` 不因此判定 not_ready(响应中 `scheduler.running=false`)。
- **DuckDB 降级是受支持形态**(生产默认 `DUCKDB_STARTUP_INIT_ENABLED=false`,启动即降级走 OLTP):today_picks 与 webnovel 周报有 OLTP 回退,stats / trends / skill 分析端点按设计直接 503(不回退)。健康端点语义见 §3.1。

---

## 2. 环境变量
Expand Down
14 changes: 14 additions & 0 deletions docs/quality/regression-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,20 @@
- PR #62 已禁止向管理员自动关联,service 层 docstring 明确要求显式绑定流程但未实现。
- 回归测试候选:绑定端点四场景(正常 / 未 step-up / 绑定冲突 / 未验证邮箱)。owner:#64。

### D-8 /health/ready 判定门恒真 — #71 🔴 待修复(P1)
- 症状:ready 的 oltp 判定读自纯元数据 dict(`database_diagnostics` 不做连通性探测),恒为 True,`not_ready` 分支不可达;OLTP 不可达仍返回 ready。
- 边界:health 路由 / 部署路由层;复现性 always。
- 回归测试候选:路由级四态(正常 / SCHEDULER_ENABLED=False / DuckDB 降级 / OLTP 不可达)。owner:#71(Parent #6)。

### D-9 三处无主 create_task — #72 🔴 待修复(P1)
- 症状:`scheduler.py:1204/1205` 启动 rescan/恢复任务与 `daily_reports.py:294` 日报后台——无引用、无异常收集、不受停机管理;日报 `mark_error` 失败被裸 `except: pass` 吞掉可永卡 GENERATING。
- 边界:scheduler 启动路径 / daily_reports / lifespan 停机序。
- 回归测试候选:异常捕获记日志、任务注册可 drain、mark_error 失败不吞。owner:#72(Parent #6)。

### D-10 优雅停机链中断点 — #73 🔴 待修复(P2)
- 症状:`_cache_warmup_task` 非 CancelledError 异常会中断后续全部清理步骤;jieba 预热 await 无超时且 `to_thread` 不可取消,可挂死停机;整体停机无 deadline。
- 回归测试候选:停机各步异常隔离、jieba 超时路径。owner:#73(Parent #6)。

## 三、关键流程基线(9 项)

状态标记:✅ = 2026-09-27 在 main @ 7203847 新鲜复跑通过;📋 = 现有套件覆盖、未逐项复跑(跑全量即覆盖)。
Expand Down
Loading