From 7dd4b158042b77b080ad1bc7f026d7539560eb93 Mon Sep 17 00:00:00 2001 From: jianghaifeng Date: Fri, 16 Oct 2026 13:20:31 +0800 Subject: [PATCH] =?UTF-8?q?docs(deploy):=20=E6=8C=89=20specs=20=E7=BA=A6?= =?UTF-8?q?=E6=9D=9F=E8=A1=A5=E5=85=A8=E9=83=A8=E7=BD=B2=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=88=E6=96=B0=E5=A2=9E=20DEPLOY-CHECKLIST.md=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为什么：用户要求"写好文档，一定要根据 specs 文档约束好"。把 specs 里与部署相关的 硬约束逐条对照现状后发现 9 条里有 6 条未覆盖或只写了一半，需要一次补齐并如实标注工程缺口。 - 新增 DEPLOY-CHECKLIST.md：环境映射（办公室主机 = test）、域名/HTTPS/反代（含 nginx 与证书建议）、 网络分区、发布与回滚规范（语义化 tag / release→main / 回滚演练）、备份与恢复（specs 目标 vs 现状差距）、 监控与告警现状、密钥托管与轮换、**上线检查清单对照表（docs/12 逐条 ✅⚠️❌ + 责任方）**、 风险/待确认（R1–R10）、上线前必补清单（P0–P2） - DEPLOY.md 增加"本机属于 test 环境"与交叉引用，并单列"上线前必须补的四条"提示 - 对照表里的 ✅ 都带证据（如分区生效先实测 playback_ticket_202610 落分区、_default = 0） - 只写文档，未改任何实现；mvn test 83 条全过、两入口 package 通过 --- DEPLOY-CHECKLIST.md | 256 ++++++++++++++++++++++++++++++++++++++++++++ DEPLOY.md | 19 ++++ 2 files changed, 275 insertions(+) create mode 100644 DEPLOY-CHECKLIST.md diff --git a/DEPLOY-CHECKLIST.md b/DEPLOY-CHECKLIST.md new file mode 100644 index 0000000..f21aafb --- /dev/null +++ b/DEPLOY-CHECKLIST.md @@ -0,0 +1,256 @@ +# Author: fruit.com.cn +# +# DEPLOY-CHECKLIST —— 部署合规视角（specs 约束逐条结论 + 上线检查清单对照 + 风险/待确认） +# +# 这份文档回答两个问题： +# 1) `docs/04-部署架构`、`docs/08-备份恢复方案`、`docs/10-安全方案`、`docs/11-发布与回滚方案`、 +# `docs/12-上线检查清单`、`docs/07-监控告警方案`、`GIT_WORKFLOW.md`、`CODING_STANDARDS.md` +# 这些 specs 里跟部署有关的要求，**我们现在满足到哪一步**； +# 2) 上线前**必须补什么**、谁来补。 +# +# 操作层面的"怎么部署/怎么回滚命令"在 `DEPLOY.md`（本文件只做结论与对照，避免两份口径分叉）。 +# 结论用三态：✅ 已满足 ｜ ⚠️ 部分满足（能用但有差距）｜ ❌ 未满足（上线前必补） + +## 一、环境映射（对应 `04-部署架构`§一） + +`04-部署架构`§一把环境分成四级： + +| 环境 | 用途 | 数据 | 访问 | +| --- | --- | --- | --- | +| dev | 本地开发 | 本地 PostgreSQL | 内网 | +| test | 测试/联调 | 独立测试库 | 内网/VPN | +| pre | 预发（生产镜像演练） | 接近生产 | 受限 | +| prod | 生产 | 生产库 | 公网 | + +**当前这台办公室主机 = `test` 环境**，依据三条： + +1. 用途是"给前端联调 + 内部验收"，不是对外生产（`04-部署架构`§一 test = 测试/联调）； +2. 访问方式计划是内网/办公网（`admin-api` 只绑 `127.0.0.1`），而不是公网； +3. 用的是独立的开发库（`fruitshorts`，含种子数据），不是生产库。 + +规范要求与我们的对应： + +- `docker-compose.yml` 用 **Docker Compose 单机编排** → 对应 §五「第一阶段（dev/test）：Docker Compose 单机编排」，✅。 +- 一台机器上合并 app/api/DB/Redis + worker 独立容器 → 对应 §三「精简方案：test 环境可将 app/api/DB/Redis 合并到 1 台 8C32G，转码 worker 独立 1 台」，✅（worker 是独立容器，但**与在线服务同机**：资源隔离靠容器限额，真正的分机留到生产）。 +- **差距**：`pre` 环境（生产镜像演练）**尚未建立** —— 上线前建议在目标机用同一份 compose 跑一次"预发演练"，即用生产镜像 + 接近生产的数据走一遍发布流程。状态：❌（流程未建立，不阻塞 test 联调）。 + +## 二、域名 / HTTPS / 反向代理（对应 `04-部署架构`§四 + `10-安全方案`§二） + +**specs 原文**：`04-部署架构`§四「域名/SSL：管理端、客户端 API、媒资**分别域名**；**HTTPS 强制**」； +`10-安全方案`§二「传输安全：HTTPS 强制；密钥环境变量注入」。 + +**当前状态：❌ 未满足**。现在的形态是 `IP:端口 + HTTP`： + +| 需要的域名 | 现状 | 上线前必须做 | +| --- | --- | --- | +| 管理端（后台 Web + `/admin/**`） | 无域名；`admin-api` 绑 `127.0.0.1:8080`，靠内网/SSH 隧道访问 | 申请域名（如 `admin.`）+ 证书；nginx 反代 → `127.0.0.1:8080`；**并保持只允许内网/VPN 来源**（见 §三） | +| 客户端 API（`/app/**`） | 无域名；`app-api` 监听 `8081`（HTTP） | 申请域名（如 `api.`）+ 证书；nginx 反代 → `8081`，只暴露 `/app/**`；**强制 HTTP→HTTPS 跳转** | +| 媒资（`/files/**`） | 无域名；与 app-api 同一端口 | 申请域名（如 `media.`）或直接走 CDN 域名；**播放地址已带签名参数**，CDN 需按签名做缓存策略（`04-部署架构`§四） | + +**测试环境（本机）可以先用内网 HTTP 联调**（`04-部署架构`§一 test 是内网/VPN 访问）， +但**上线（pre/prod）前必须满足上述三条 HTTPS + 独立域名**，否则不满足 `12-上线检查清单`§三「传输安全」。 + +### nginx + 证书的建议做法（上线前照做） + +```nginx +# /etc/nginx/conf.d/fruitshorts.conf（示意；域名与证书路径按实际替换） +server { # 客户端 API + listen 443 ssl http2; + server_name api.example.com; + ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem; + client_max_body_size 20m; # 分片上传，与 admin-api 的 multipart 上限一致 + location / { proxy_pass http://127.0.0.1:8081; proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; } +} +server { # 管理端：只允许内网/VPN 网段 + listen 443 ssl http2; + server_name admin.example.com; + allow 10.0.0.0/8; allow 192.168.0.0/16; deny all; # 按实际内网段调整 + location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; } +} +server { # HTTP 强制跳 HTTPS + listen 80; + server_name api.example.com admin.example.com; + return 301 https://$host$request_uri; +} +``` + +证书建议用 **Let's Encrypt（certbot）** 自动续期（`certbot --nginx -d api.example.com -d admin.example.com`）， +或公司自有证书；无论哪种，**到期前必须能自动续**，否则接口会整体不可用。 +反代配置文件需与本仓库一起纳入版本管理（放目标机的 `/etc/nginx/conf.d/`，另存一份到运维仓库）。 + +## 三、网络分区（对应 `04-部署架构`§四） + +**specs 原文**：「网络分区：管理后台仅内网/VPN 可访问；客户端 API 公网。」 + +| 要求 | 现状 | 上线前必须做 | +| --- | --- | --- | +| 管理后台仅内网/VPN | ✅ 已满足：`docker-compose.yml` 里 admin-api 端口映射为 `127.0.0.1:8080:8080`（只绑本机，公网访问不到） | 上公网后仍要保证：只经 nginx + `allow/deny` 内网段暴露（见 §二示例） | +| 客户端 API 公网 | ⚠️ 部分满足：`app-api` 监听 `0.0.0.0:8081`，同网段可访问；**但还没有反代/域名，也没限制只暴露 `/app/**`** | 反代只放行 `/app/**`（`/files/**` 走媒资域名/CDN）；不要把 `/v3/api-docs`、`/healthz` 直接暴露到公网（`/healthz` 可留给内网监控） | + +**注意**：`/doc.html` 与 `/v3/api-docs` 由 `SWAGGER_ENABLED` 控制（见 `DEPLOY.md`）。 +**联调环境建议 `true`**（前端要看），**公网生产建议 `false`**（不暴露接口清单）。 + +## 四、发布与回滚规范（对应 `11-发布与回滚方案`§一/§四 + `GIT_WORKFLOW.md`§四） + +**specs 原文**： + +- `11-发布与回滚方案`§一：「语义化版本 `v..`；分支 `main`（生产）← `release/*` ← `develop` ← `feature/*`；每次 `release`/`hotfix` 合并 `main` 必须打 tag，tag 不可移动/删除。」 +- `GIT_WORKFLOW.md`§四：「`major` 破坏性变更、`minor` 新功能、`patch` 修复；发布后 tag 不可移动、不可删除（错误版本发新 tag 修正，不覆盖旧 tag）。」 +- `11-发布与回滚方案`§四：「回滚演练：**上线前演练回滚**，确保可执行。」「数据库迁移脚本必须可回滚（向前兼容，避免破坏性变更）。」 + +| 要求 | 现状 | 上线前必须做 | +| --- | --- | --- | +| 语义化 tag `v` | ⚠️ 部分满足：`DEPLOY.md` 里只是示例式地提到"每次发版打 tag"，**没有命名规范** | 按 §四 规则打：首个上线版本 `v1.0.0`；之后功能 `v1.1.0`、修复 `v1.0.1`；**错误版本发新 tag，绝不移动/删除旧 tag** | +| release/hotfix 合并 main | ⚠️ 流程未走过：目前工作都在 `develop`，`main` 未动 | 上线时：`develop` → 建 `release/v1.0.0` → 在 test 环境验证 → 合并 `main` + 打 tag `v1.0.0`（**由用户操作，Codex 不碰 main**） | +| 回滚可执行 | ✅ 技术路径已写全（`DEPLOY.md`§七：切回上一个镜像 tag / git 回上一个 release tag + `up -d --build` + 重跑冒烟） | **上线前演练一次**（在 test 环境故意回滚到上一版本并跑 `tools/smoke.sh`），把演练记录留档 | +| 数据库迁移可回滚 | ⚠️ 部分满足：`sql/*.sql` 全是幂等增量（`ADD COLUMN IF NOT EXISTS`、`CREATE TABLE IF NOT EXISTS`），**没有破坏性变更**；`upsert` 语义的种子脚本也在 | 上线前确认：本次发布**不包含** `DROP/ALTER TYPE` 类破坏性语句（当前没有）；如将来有，必须先写"回滚脚本 + 备份"再发 | +| 灰度/放量 | ❌ 未满足（单机 Compose 无灰度能力） | 上线首日按"先内测 → 再小流量（如有网关可切）"；正式灰度需要 K8s/网关，属后续阶段（`04-部署架构`§五：生产上 K8s） | + +## 五、备份与恢复（对应 `08-备份恢复方案`§二/§三） + +**specs 目标**：全量每日 × 保持 30 天；**WAL 归档（实时）**；可选增量；**备份加密 + 异地存储**； +**RPO ≤ 5 分钟、RTO ≤ 30 分钟**；**每季度至少一次恢复演练**。 + +| 项 | specs 要求 | 现状 | 差距 / 上线前必须补 | +| --- | --- | --- | --- | +| 全量备份 | 每日 1 次，保留 30 天 | ⚠️ `DEPLOY.md`§七 给了**手动** `pg_dump` 命令；**没有定时任务、没有保留策略** | 目标机加 cron（或 compose 侧容器）每日 `pg_dump`，按日期命名保留 30 天；脚本可放 `tools/backup.sh`（本轮未写，属运维脚本） | +| WAL 归档 | 实时，用于 PITR | ❌ 未配置（PG 默认 `archive_mode=off`） | `postgresql.conf`：`wal_level=replica`、`archive_mode=on`、`archive_command` 推到异地；这是达成 **RPO≤5min** 的唯一途径 | +| 增量 | 可选 | ❌ 未做 | 有了 WAL 归档即可满足 RPO，增量备份可后补 | +| 加密 | 备份加密 | ❌ 未做 | `pg_dump` 管道给 `age`/`gpg`，或落到加密卷；密钥单独保管（与备份分开） | +| 异地 | 与生产不同可用区/账号 | ❌ 未做（本机 dump 还在同一台机器上） | 推到对象存储（另一账号/另一区）；**"备份和数据库在同一台机器上"等于没备份** | +| 恢复演练 | 每季度 ≥ 1 次，记录归档 | ❌ 从未做过 | 首次上线前做一次"恢复到新库 + 起服务 + 冒烟"，记录耗时（验 RTO）与丢失窗口（验 RPO） | + +**结论：备份恢复这一项与 specs 差距最大，是上线前必须补的硬缺口（❌）。** +当前只有"能手动 dump"，距离「RPO≤5min / RTO≤30min / 加密 / 异地 / 季度演练」还差整套机制。 +建议排期：**上线前**至少做到「每日全量 + 异机保存 + 一次恢复演练」；**上线后两周内**补 WAL 归档与加密。 + +## 六、监控与告警现状（对应 `07-监控告警方案`§七） + +**specs 原文**：`07-监控告警`§七「Prometheus/Loki/Grafana 尚未部署，**第一阶段先用日志 + `SlowRequestLogger` 兜底**」； +§六「告警渠道：飞书/钉钉/邮件 + 值班轮转」；§六「值班表与 Runbook 见 `docs/plans/`（上线前补）」。 + +| 项 | 现状 | 上线前必须补 | +| --- | --- | --- | +| 指标（Prometheus） | ❌ 未部署；**项目也没引 actuator**（`/actuator/health` 一直是未映射，见 `DEPLOY.md`§五说明） | 按 §七 的既定路线部署；要暴露指标需先给两个入口加 `spring-boot-starter-actuator` + `micrometer-registry-prometheus`（**属代码改动，需立项**） | +| 日志聚合（Loki） | ❌ 未部署；现在日志在容器 stdout（`docker compose logs`） | 部署 Loki + Promtail 采集容器日志 | +| 大盘（Grafana） | ❌ 未部署 | 按 §五 大盘定义建面板 | +| 第一阶段兜底 | ✅ 已具备：应用结构化日志（转码耗时/失败原因、业务异常、`SlowRequestLogger` 慢请求告警都在代码里）+ 容器级 `healthcheck`（`/healthz`） | 至少把"容器 unhealthy"接到人的手机上（可用 `docker compose events` + 简单脚本/飞书机器人） | +| 告警渠道 + 值班 + Runbook | ❌ 未定 | 定渠道（飞书/钉钉/邮件）、排值班表、把 `DEPLOY.md`§九「故障速查」扩成 Runbook | + +**结论：监控告警 ❌ 未满足**，但按 specs §七 的既定节奏，**第一阶段允许先用日志兜底** —— +前提是"告警能到达人"。上线前最低要求：**容器 unhealthy / 冒烟失败能被发现**（哪怕先是人工每天跑一次 `tools/smoke.sh`）。 + +## 七、密钥托管与轮换（对应 `10-安全方案`§五） + +**specs 原文**：§五「密钥托管：生产密钥**集中托管**，**最小权限**」；`12-上线检查清单`§三「JWT/签名密钥走环境变量，未硬编码/入库」「生产密钥集中托管」。 + +| 要求 | 现状 | 上线前必须补 | +| --- | --- | --- | +| 密钥走环境变量、未硬编码/入库 | ✅ 已满足：三个可运行件的密钥全部 `${ENV:...}` 注入；`.env` 已 gitignore；`.env.example` 只有占位；镜像里不含密钥 | 继续保持；**代码审查时禁止把密钥写回 yml** | +| 缺失即启动失败 | ✅ 已满足：`ProdSecretGuard` 在 `prod` profile 下校验三个密钥 + 签名开关 + DB_URL + CORS，缺失/仍是 dev 默认值/不足 32 位 → 退出码 1 | — | +| **集中托管** | ⚠️ 部分满足：现在是"目标机的 `.env` 文件"（文件权限 600），**没有密钥管理系统** | 短期：`.env` 权限 600、只有运维账号可读、**不进任何 git 仓库**、单独备份（加密）；中期：迁到 K8s Secret / 云 KMS / Vault（`04-部署架构`§五 生产路线也是 K8s Secret） | +| 最小权限 | ⚠️ 部分满足：DB 用单一 `fruitshorts` 账号（读写全库） | 拆账号：应用用 `fruitshorts_app`（DML 权限、无 DDL）；备份用只读账号；DDL 只留给运维 | +| 轮换 | ❌ 未做（也没有流程） | 定义轮换周期（建议 90 天或按事件）：**先加新密钥 → 双密钥并行验证期 → 再下线旧密钥**；JWT 轮换会导致存量 token 失效，需选低峰并公告（`10-安全方案`§一 token 有效期 120min，影响窗口可控） | + +## 八、上线检查清单对照表（逐条映射 `docs/12-上线检查清单.md`） + +> 三态：✅ 已满足 ｜ ⚠️ 部分满足 / 有条件满足 ｜ ❌ 未满足（上线前必补） +> 「责任方」列区分：**Codex**（我能做的）/ **用户或运维**（需要账号、域名、外部资源）。 + +### 一、代码与门禁 + +| 检查项 | 状态 | 依据 / 缺口 | 责任方 | +| --- | --- | --- | --- | +| 三端门禁全绿 | ⚠️ | **后端 ✅**：`mvn test` 83 条全过；**前端（Flutter/Web）不在本工程范围**，由另一同事的 AI 负责，需其提供门禁结果 | 用户/前端 | +| 接口契约 `api-phase1.md` 已同步 | ✅ | 本轮 B1-1/B1-2 的 verify / reconcile 改动都已同步进契约 | Codex | +| 作者标识齐全 | ✅ | 远端已做全量补齐（`35be37c`），本轮新增文件也都带 `// Author: fruit.com.cn` | Codex | +| 代码规模红线、无关键路径 TODO | ⚠️ | 未做静态检查工具（后端无 checkstyle/pmd），**存量未逐文件核对**；无 TODO 扫描证据 | Codex（需立项） | + +### 二、功能与测试 + +| 检查项 | 状态 | 依据 / 缺口 | 责任方 | +| --- | --- | --- | --- | +| 核心用例通过、P0 清零 | ⚠️ | 后端 83 条（含真实 ffmpeg smoke）全过；**前端与端到端用例不在本工程** | Codex/用户 | +| 支付闭环端到端 | ⚠️ | 票据校验/幂等/退款回收/对账**已实现并有单测**；**真实 Google Play 未联调**（缺 packageName + service account JSON，属付费凭据） | 用户（凭据）+ Codex（联调） | +| 播放长稳 + 弱网测试 | ❌ | 未做（需真机 + 网络模拟） | 前端/用户 | +| 多端（iOS/Android）回归 | ❌ | 未做（Android 无可用模拟器，iOS 有真机） | 前端/用户 | + +### 三、安全 + +| 检查项 | 状态 | 依据 / 缺口 | 责任方 | +| --- | --- | --- | --- | +| 播放签名 `signature-required=true`（生产必开） | ✅ | `application-prod.yml` 写死 `true`，`ProdSecretGuard` 再校验一次，缺了直接拒启 | Codex | +| JWT/签名密钥走环境变量，未硬编码/入库 | ✅ | 三件全 `${ENV:...}`；`.env` gitignore；镜像不含密钥 | Codex | +| 越权/注入/敏感数据专项测试 | ⚠️ | **越权**：创作者中心有专项用例（B 批）；**注入/SQL 注入**：全部走 MyBatis-Plus 参数绑定，无字符串拼接 SQL（人工核对），**无自动化用例**；敏感数据脱敏有实现（`AppIdentifier.mask`）但无专项测试 | Codex（需立项） | +| 生产密钥集中托管 | ⚠️ | 见 §七：现为 `.env` 文件权限隔离，未接 KMS/Vault | 用户/运维 | + +### 四、基础设施 + +| 检查项 | 状态 | 依据 / 缺口 | 责任方 | +| --- | --- | --- | --- | +| 数据库分区已生效 | ✅ | `watch_history`/`playback_ticket`/`order_event` 均为声明式月分区，`partition-maintenance` 启动时+每日补齐。**实测证据**：`select tableoid::regclass, count(*) from playback_ticket group by 1` → `playback_ticket_202610 \| 1`（落月分区，不是 `_default`）；`select count(*) from watch_history_default` → `0` | Codex | +| Redis/缓存（如接入）配置正确 | ⚠️ | compose 已备 Redis 容器，**代码尚未接入（C2 待做）**；当前不依赖 Redis | Codex（C2） | +| 媒资已迁 OSS/S3 + CDN（生产） | ❌ | **仍是本地磁盘 `./data/uploads`，与在线服务同机**；`MediaStorageService` 已把存储收敛到一处，切换 OSS 只需改它 + 转码产物上传路径 | 用户（账号）+ Codex | +| 备份恢复已配置并演练 | ❌ | 见 §五，差距最大 | 用户/运维 + Codex（脚本） | +| 监控告警已接入、告警可达 | ❌ | 见 §六 | 用户/运维 | + +### 五、商店与合规 + +| 检查项 | 状态 | 依据 / 缺口 | 责任方 | +| --- | --- | --- | --- | +| 应用名称/截图/文案/隐私标签一致 | ❌ | 未办（客户端上架材料） | 用户 | +| App Privacy / Data Safety / SDK 清单 | ❌ | 未办 | 用户 | +| 隐私政策、用户协议已上线 | ❌ | 未办（后端有 `app_user_consent` 落库能力，文案与页面需法务/前端） | 用户 | +| 版权/素材/商标授权台账 | ❌ | 未办 | 用户 | +| 商店账号/证书/包名有效 | ❌ | 未办；**并且包名仍不一致**（Android `com.stormg.lumadrama` / iOS `com.stormg.lumadramv`，见 C 端回执） | 用户（建议上架前统一） | + +### 六、发布与回滚 + +| 检查项 | 状态 | 依据 / 缺口 | 责任方 | +| --- | --- | --- | --- | +| 版本号 + tag 冻结（`v1.0.0`） | ❌ | 尚未打 tag（规范见 §四） | 用户（合并 main 时打） | +| 回滚方案已演练 | ❌ | 方案已写（`DEPLOY.md`§七），**未演练** | 用户/运维 | +| 值班表 + 告警 Runbook 就绪 | ⚠️ | `DEPLOY.md`§九「故障速查」可作为 Runbook 初稿；**值班表未定** | 用户 | +| 灰度/放量计划明确 | ❌ | 单机 Compose 无灰度能力；生产上 K8s 后再做 | 用户 | + +### 七、观察窗口（上线后） + +| 检查项 | 状态 | 依据 / 缺口 | 责任方 | +| --- | --- | --- | --- | +| 核心链路监控 | ❌ | 监控未接；**上线首日建议人工每 30 分钟跑一次 `tools/smoke.sh` + 看 `docker compose logs`** 作为过渡 | 用户/运维 | +| 支付/订单对账数据回看 | ⚠️ | 对账能力已在（`/admin/reconcile/run`，`storeAmountSum` 无数据源时返回 null + notes），**真实商店数据要等凭据** | Codex/用户 | +| 崩溃率/错误率观察 | ❌ | 未接监控；容器日志可人工查 | 用户/运维 | +| 问题复盘归档 | ⚠️ | 本工程有 PROGRESS/回执留痕习惯，可沿用 | Codex/用户 | + +## 九、风险 / 待确认（`CODING_STANDARDS`§7 要求：技术决策必须留痕） + +| # | 风险 / 待确认 | 影响 | 建议与责任方 | +| --- | --- | --- | --- | +| R1 | **媒资仍在本机磁盘**（`./data/uploads`），未迁 OSS/CDN | 单机磁盘满/机器损坏即媒资全丢；播放无法借 CDN 扛量 | `12-上线检查清单`§四把"迁 OSS/CDN"列为上线项，**属上线前必补**；`MediaStorageService` 已是唯一替换点，切换工作量可控（Codex 可做，需 OSS 账号） | +| R2 | **单点无高可用**：一台办公室主机跑全栈 | 机器/网络故障 = 服务全停；无灰度能力 | test 阶段可接受；**生产必须按 `04-部署架构`§三 生产规格（应用 2+、DB 主备）+ §五 上 K8s** | +| R3 | **备份未演练、无 WAL 归档、备份与库同机** | 真出事时可能既恢复不了也丢得多（RPO 远大于 5 分钟） | 上线前至少"每日全量 + 异机保存 + 一次恢复演练"；两周内补 WAL 归档与加密（见 §五） | +| R4 | **监控与告警未接** | 故障靠人发现；上线首日风险最高的窗口无自动告警 | 短期用"人工冒烟 + 容器 healthcheck"；随后按 `07-监控告警方案`部署（需先给服务加 actuator，属代码改动） | +| R5 | **商店合规未办**（隐私政策/Data Safety/SDK 清单/版权台账/包名） | 无法上架；印尼还涉及 Kominfo PSE 注册（未注册可能被整体封锁，见 `docs/08`/PRD 合规节） | 全部为用户侧工作；其中"包名统一"建议在上架前完成（一旦上架不可改） | +| R6 | **真实 Google Play 联调未做**（缺 packageName + service account JSON） | 支付闭环在真机/商店侧未验证；`STORE_VERIFIER=disabled` 时对外明确返回"尚未配置"，不会产生假订单 | 用户提供凭据后，Codex 用沙盒测试购买联调（`STORE_VERIFIER=google-play`） | +| R7 | **HTTPS/域名未就绪**，当前 IP+HTTP | 不满足 `04-部署架构`§四与 `10-安全方案`§二；公网明文传输不可接受 | 上线前按 §二 配域名 + 证书 + nginx（用户/运维） | +| R8 | **DB 账号未做最小权限**（单账号读写全库） | 应用被攻破即拥有 DDL 能力 | 拆 `fruitshorts_app`（仅 DML）与备份只读账号（见 §七） | +| R9 | **`/swagger-ui/**` 静态资源在 `SWAGGER_ENABLED=false` 时仍可访问** | 不泄露接口信息（spec 与 config 都已 404），但严格合规环境下应彻底关闭 | 可选加固：`spring.web.resources` 排除 webjar；需你点头再改（Codex） | +| R10 | 转码 worker 与在线服务**同机**（虽为独立容器） | 大批量转码会抢 CPU，影响播放稳定性 | `04-部署架构`§三 的完整方案是 worker 独立 1 台；上线前如有第二台机器就拆开，否则给 worker 容器加 CPU 限额（Codex 可改 compose） | + +## 十、上线前必补清单（按优先级） + +| 优先级 | 事项 | 依赖 | 责任方 | +| --- | --- | --- | --- | +| P0 | HTTPS + 独立域名 + nginx 反代（§二） | 域名、证书 | 用户/运维 | +| P0 | 每日全量备份 + 异机保存 + 一次恢复演练（§五） | 目标机 + 异地存储 | 用户/运维（Codex 可提供脚本） | +| P0 | 媒资迁 OSS/CDN（R1） | 云账号 | 用户 + Codex | +| P1 | tag 规范落地 + 回滚演练（§四） | — | 用户（合并 main 时）/ Codex 配合 | +| P1 | 监控告警最低可用（§六：容器 unhealthy 能到人） | 通知渠道 | 用户/运维 | +| P1 | 真实 Google Play 联调（R6） | 付费凭据 | 用户 → Codex | +| P2 | DB 最小权限账号（R8）、密钥集中托管（§七） | 运维 | 用户/运维 | +| P2 | K8s 生产化（R2）、灰度能力、WAL 归档与加密 | 生产资源 | 后续阶段 | diff --git a/DEPLOY.md b/DEPLOY.md index 8e2f831..4858cd7 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -4,6 +4,13 @@ > `docs/11-发布与回滚方案.md`、`docs/12-上线检查清单.md`（**播放签名生产必开**、密钥走环境变量）。 > 目标机形态：**办公室一台主机**（§三 精简方案：app/api/DB/Redis 合并 1 台 8C32G，转码 worker 独立进程）。 +> **本文只讲"怎么部署/怎么回滚"**。要回答"我们离 specs 还差什么、上线前必补什么"， +> 看 **[DEPLOY-CHECKLIST.md](./DEPLOY-CHECKLIST.md)**（环境映射、域名/HTTPS、备份恢复、监控、发布与回滚规范、 +> `docs/12-上线检查清单` 逐条对照表、风险/待确认）。 + +**这台办公室主机属于 `test` 环境**（`04-部署架构`§一：测试/联调、独立测试库、内网/VPN 访问）； +`pre`/`prod` 的规格与前置条件见 `DEPLOY-CHECKLIST.md` §一。 + ## 一、两条部署路径（先选一条） | 路径 | 适用 | 命令主线 | @@ -171,6 +178,18 @@ docker compose exec -T db pg_dump -U "${DB_USER:-fruitshorts}" "${DB_NAME:-fruit **prod fail-fast**（缺密钥时退出码 1 + 明确报错）、配置外置（`DB_URL` 等改动后仍能起）。 - 目标主机上有 Docker 之后，请**先跑 §三 的 1)–4) 步**确认；如报错把 `docker compose logs` 贴回来。 +## 八之二、上线前必须补的（治理类，详见 DEPLOY-CHECKLIST.md） + +以下四条**不是**"部署命令"层面的问题，但 `docs/12-上线检查清单` 把它们列为上线条件，此处给出醒目提示： + +1. **HTTPS + 独立域名 + 反向代理**（管理端/客户端 API/媒资分域名，`04-部署架构`§四 + `10-安全方案`§二）—— 现在只有 IP:HTTP； +2. **备份恢复**：specs 要求每日全量×30 天 + WAL 归档 + 加密 + 异地 + **RPO≤5min / RTO≤30min** + 季度演练， + 现在只有手动 `pg_dump`，且**备份与数据库在同一台机器上**（等于没备份）； +3. **监控告警**：Prometheus/Grafana/Loki 未部署；第一阶段按 specs 允许用日志兜底，但"容器 unhealthy 要能通知到人"； +4. **商店与合规**：隐私政策/Data Safety/SDK 清单/版权台账/包名统一，均未办（印尼还涉及 Kominfo PSE 注册）。 + +**逐条状态与"上线前必补清单（按优先级）"见 [DEPLOY-CHECKLIST.md](./DEPLOY-CHECKLIST.md)。** + ## 九、故障速查 | 现象 | 先看 | 处理 |