From dfe251c52b2af0298b062d10a9d91b99aa3eb222 Mon Sep 17 00:00:00 2001 From: zheng020 Date: Mon, 8 Jun 2026 14:29:49 +0800 Subject: [PATCH] docs: add Spec Review Refinements section (10.1-10.7) --- ...26-06-08-docker-to-k8s-migration-design.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/docs/superpowers/specs/2026-06-08-docker-to-k8s-migration-design.md b/docs/superpowers/specs/2026-06-08-docker-to-k8s-migration-design.md index 2923aab..97ca8e6 100644 --- a/docs/superpowers/specs/2026-06-08-docker-to-k8s-migration-design.md +++ b/docs/superpowers/specs/2026-06-08-docker-to-k8s-migration-design.md @@ -500,3 +500,89 @@ k8s/ (新目录,根目录同级) - 监控/日志/告警接入 - 灾备多集群 - K8s 内的 StatefulSet (Postgres/Redis 用云服务,不自己跑) + +--- + +## 十、Spec Review Refinements + +本文档经 spec-document-reviewer 审查通过 (Status: Approved)。以下为审查中识别的可执行细化项,留待 writing-plans 阶段处理: + +### 10.1 前置条件:`group_id` 字段已就绪 + +> 来自 4.2.2 节的隐含假设 + +Helm chart 能成功 install 并不等于 K8s 上的多组数据隔离已生效。多组隔离依赖现有 schema 已含 `group_id` 列(或配套 migration 已先于 K8s 部署完成)。 + +**实施计划中需明确**: Step 1 启动前的 blocker — 验证所有数据表已有 `group_id`,或先发一份 DB migration 再做 K8s 部署。 + +### 10.2 镜像仓库路径决策 + +> 来自 4.2.4 的歧义 + +`values.yaml` 中 `image.repository` 必须明确指向一个 registry: + +- **选项 A (推荐)**: 阿里云 ACR,`image.repository: registry.cn-shanghai.aliyuncs.com/topfans/`,CI 构建推送 +- **选项 B**: 自建 Harbor,`image.repository: harbor.example.com/topfans/` + +**实施计划中需选其一**,并写明 deploy.sh 的去留: + +- 选 A: 改 deploy.sh 为 CI 触发器,服务器只拉不构建 +- 选 B: 保留 deploy.sh 构建逻辑,但目标改为推 Harbor 而非本地 + +### 10.3 Secret 落盘策略 + +> 来自 4.2.6 的潜在泄漏 + +`values-prod.yaml` 含明文密钥会污染 git。**实施计划中需**: +- 把 `values-prod.yaml` 加入 `.gitignore`,只提交 `values-prod.example.yaml` (空值) +- 真值由 CI/CD 注入,或用 `kubeseal` / `sops` 加密后提交 +- 本期最低要求: 真值不进 git + +### 10.4 数据库迁移时序 + +> 来自 CLAUDE.md PostgreSQL 序列同步规则 + 第 6 节 Step 3 + +若选择"从 VM 迁数据到 RDS"路径,需明确: + +- `init-db.sql` 的 `setval(...)` 同步操作放在流量切换**之前**还是**之后** +- 推荐: 切换**前**以 Job 形式跑完,验证 `pg_sequences` 全部 `is_healthy=true` 后再切流量 +- 详见 CLAUDE.md 的强制规范 + +### 10.5 HEALTHCHECK 修复范围 + +> 来自 4.2.5 的歧义 + +K8s 用 Helm chart 里的 `livenessProbe` / `readinessProbe`,**不再依赖 Dockerfile HEALTHCHECK**。两种选择: + +- **A. 只改 K8s 探针,不动 Dockerfile**: 保持向后兼容,本地 docker-compose 仍可用 +- **B. 同时修 Dockerfile**: 顺手修 bug,让 compose 也能看到正确健康状态 + +**推荐 A** — 本次任务专注 K8s,Dockerfile 修复单独提一个 issue。 + +### 10.6 跨 namespace Dubbo 调用模式 (为新服务预留) + +> 来自审查中识别 — 当前 spec 未明确 + +当未来 `admin` / `review` 部署在 `topfans-shared` 时,它们需要调用各组的数据服务(如 review 审核 group-a 的 gallery): + +```yaml +# 未来 review 服务的环境变量 (在 topfans-shared namespace) +# 需要按 group 动态获取或路由 +DUBBO_GALLERY_SERVICE_URL: tri://galleryservice.topfans-group-a.svc.cluster.local:20001 +DUBBO_GALLERY_SERVICE_URL_GROUP_B: tri://galleryservice.topfans-group-b.svc.cluster.local:20001 +``` + +**当前不实现**,但 `topfans-shared` 的 chart 结构需考虑: 共享服务将来需要某种方式(配置中心/服务发现)拿到各组的服务地址。本期不展开,记入"未来工作"。 + +### 10.7 评审通过的完整决策 + +| # | 决策点 | 选择 | +|---|---|---| +| 1 | K8s 隔离粒度 | 按"组" (1+ 明星/组) | +| 2 | 配置格式 | Helm Chart | +| 3 | 数据库部署 | 外部托管 (RDS/ElastiCache) | +| 4 | Gateway 位置 | 每组 namespace 内 | +| 5 | 新服务位置 | `topfans-shared` | +| 6 | 镜像仓库 | 待定 (10.2 中 A/B 选一) | +| 7 | Docker HEALTHCHECK 修复 | 本期不动,改 K8s 探针 | +| 8 | `docker/` 目录 | 保留,继续支撑本地开发 |