From 2b6eafc082ad7fcaed86c7ab6666fade35b46f11 Mon Sep 17 00:00:00 2001 From: fxbin Date: Sun, 27 Sep 2026 21:27:24 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=99=BB=E8=AE=B0=20#6=20=E5=AE=A1?= =?UTF-8?q?=E8=AE=A1=E7=BC=BA=E9=99=B7=20D-8~D-10=20=E5=B9=B6=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=8C=96=E8=BF=9B=E7=A8=8B=E6=8B=93=E6=89=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DEPLOYMENT.md | 9 +++++++++ docs/quality/regression-matrix.md | 14 ++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 7091de0e..3463a433 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -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. 环境变量 diff --git a/docs/quality/regression-matrix.md b/docs/quality/regression-matrix.md index c9bdeb2f..73c06872 100644 --- a/docs/quality/regression-matrix.md +++ b/docs/quality/regression-matrix.md @@ -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 新鲜复跑通过；📋 = 现有套件覆盖、未逐项复跑（跑全量即覆盖）。