flym
34c2b436f0
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.
65 lines
4.0 KiB
Markdown
65 lines
4.0 KiB
Markdown
# 部署说明（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` 的做法）
|
||
|
||
1. 本地提交修复，得到提交号 `<sha>`。
|
||
2. 服务器：`cp -a releases/p4 releases/<sha>`（完整拷贝当前发布）。
|
||
3. 将变更文件更新到 `releases/<sha>`（本次仅 `services/api/app/main.py` 及 `tests/`）。
|
||
4. 应用数据库迁移（如有）：`/home/flym/kaotings-api-venv/bin/python -m app.migrate`（`DATABASE_URL` 走 `api.env`）。
|
||
5. 重新指向软链（三个服务一致指向 `<sha>`）。
|
||
6. **只重启发生代码变更的服务**（本次仅 `systemctl restart kaotings-api`），避免无谓中断。
|
||
7. 版本核对：比对线上关键文件 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 需上游负责人提供
|
||
|
||
1. HTTPS 端点与证书（或 mTLS/专线接入方式、CA）。
|
||
2. 允许访问的**来源机器/IP 段**与网络方式（用于双方配置来源限制）。
|
||
3. 凭据注入名称、有效期、轮换方式（密钥仍只进 `/etc/kaotings/api.env`）。
|
||
4. 加密/来源限制生效时间窗口，便于安排外部复测。
|
||
|
||
边界：**不擅自修改上游服务**；本轮仅记录条件与所需输入，未改动任何上游配置。
|
||
|
||
## 5. 上线前外部核查清单
|
||
|
||
- 外部不可达：PostgreSQL 5432、API 8000、Web 3000、CMS 3001、Redis（如有）均仅回环，不对外。
|
||
- 上游：仅允许本站出口访问，且为加密通道（§4）。
|
||
- 备份/恢复、Worker 重启、额度对账、音频恢复、回滚：见 `OPERATIONS.md`。
|
||
- 旧 Big-TTS Web 退役：仍需旧系统负责人提供源端备份证明与替代验收确认。
|