部署说明（DEPLOYMENT）

日期：2026-09-10 · 测试机 192.168.199.22（Ubuntu 24.04，LAN）当前上线版本：49a916b（www + CMS，详见 production-deployment-2026-09-12.md）；API 仍为 ad87a71。

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。

本地提交修复，得到提交号 <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。

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

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

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

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