flym 34c2b436f0 docs: Phase 5 acceptance, deployment, operations and phase report

Record the task/quota exception matrix (isolated fault injection) results,
the admin quota concurrency fix, the isolated restore drill (business/CMS/audio,
with the pre-existing missing-audio finding), upstream security launch blocker,
and remaining minor items. Each item marked pass / fail / awaiting-external with
test version and evidence. Do not mark reliability/launch-blocking items complete.

2026-09-10 05:01:27 +08:00

4.0 KiB

Raw Blame History

部署说明（DEPLOYMENT）

日期：2026-09-10 · 测试机 192.168.199.22（Ubuntu 24.04，LAN）当前上线版本：8657f44（API 修复）；Web/CMS 代码内容与 p4 相同，随发布一并指向 8657f44。

1. 部署模型

发布目录：/home/flym/releases/<发布名>/，是仓库的完整拷贝（含 app/、apps/cms、services/api、.next、node_modules）。
运行通过软链指向当前发布：
- kaotings-api → releases/<发布>/services/api
- kaotings-cms → releases/<发布>/apps/cms
- kaotings-www → releases/<发布>
虚拟环境独立：/home/flym/kaotings-api-venv（不随发布拷贝）。
systemd 服务：kaotings-api（uvicorn 127.0.0.1:8000）、kaotings-cms（127.0.0.1:3001）、kaotings-web（127.0.0.1:3000）；Restart=always。
反代：Caddy 提供 :80/:443，/api→8000、/cms→3001、其余→3000；回环端口不对 LAN 开放。
秘密：/etc/kaotings/api.env、cms.env、cms-admin.secrets、p4-*.secrets（root-only 0600），不进 Git/前端/日志。
数据库：PostgreSQL 127.0.0.1:5432（业务 kaotings、CMS kaotings_cms，独立账号）。
音频：私有本地目录 /home/flym/kaotings-audio。

2. 发布一个新版本（本次 `8657f44` 的做法）

本地提交修复，得到提交号 <sha>。
服务器：cp -a releases/p4 releases/<sha>（完整拷贝当前发布）。
将变更文件更新到 releases/<sha>（本次仅 services/api/app/main.py 及 tests/）。
应用数据库迁移（如有）：/home/flym/kaotings-api-venv/bin/python -m app.migrate（DATABASE_URL 走 api.env）。
重新指向软链（三个服务一致指向 <sha>）。
只重启发生代码变更的服务（本次仅 systemctl restart kaotings-api），避免无谓中断。
版本核对：比对线上关键文件 SHA256 与提交一致；systemctl is-active；GET /healthz。

本次核对：线上 services/api/app/main.py SHA256 571037f4… = 本地 8657f44；kaotings-api active；/healthz ok。

3. 回滚

软链指回上一发布（本次为 p4）：kaotings-api→releases/p4/services/api（如需回滚 web/cms 一并指回）。
systemctl restart kaotings-api（及被回滚的服务）。
p4 保持完好，可随时回滚。回滚前若已应用新迁移，需评估迁移是否可逆。

4. 上线阻断：上游安全改造（必须解除后方可正式上线）

现状：TTS 上游为公网 HTTP（TTS_UPSTREAM_URL），Bearer Key 明文传输。此为正式上线阻断项，未解除前不得判定“可正式上线”。

4.1 具体实施条件

条件	说明
传输加密	上游提供 HTTPS（受信任或可内部校验的证书），或受控加密通道（内网 VPN/专线、mTLS）。
来源限制	上游侧限制仅本站服务器出口 IP/网段可访问（防火墙/安全组/WAF 白名单）；业务侧保留 Bearer Key。
外部网络复测	加密与来源限制生效后，重跑：成功生成、音频校验、私有回放/下载、超时/失败矩阵；并核查 TTS/DB/Redis/裸端口对外不可达。

4.2 需上游负责人提供

HTTPS 端点与证书（或 mTLS/专线接入方式、CA）。
允许访问的来源机器/IP 段与网络方式（用于双方配置来源限制）。
凭据注入名称、有效期、轮换方式（密钥仍只进 /etc/kaotings/api.env）。
加密/来源限制生效时间窗口，便于安排外部复测。

边界：不擅自修改上游服务；本轮仅记录条件与所需输入，未改动任何上游配置。

5. 上线前外部核查清单

外部不可达：PostgreSQL 5432、API 8000、Web 3000、CMS 3001、Redis（如有）均仅回环，不对外。
上游：仅允许本站出口访问，且为加密通道（§4）。
备份/恢复、Worker 重启、额度对账、音频恢复、回滚：见 OPERATIONS.md。
旧 Big-TTS Web 退役：仍需旧系统负责人提供源端备份证明与替代验收确认。

4.0 KiB Raw Blame History Unescape Escape