From f0e5735ffa5e4d115963d8494c552c6b3790c3f8 Mon Sep 17 00:00:00 2001
From: dongliang <dongliang@dongliangdeMac-mini.local>
Date: Mon, 6 Apr 2026 12:42:48 +0930
Subject: [PATCH] feat(dev-cicd): CD deployment checklist + health check port
 mismatch lesson

---
 skills-dev/dev-cicd-plugin/skills/SKILL.md | 52 +++++++++++++++++++++-
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/skills-dev/dev-cicd-plugin/skills/SKILL.md b/skills-dev/dev-cicd-plugin/skills/SKILL.md
index fcc97e9..e6ec71f 100644
--- a/skills-dev/dev-cicd-plugin/skills/SKILL.md
+++ b/skills-dev/dev-cicd-plugin/skills/SKILL.md
@@ -305,7 +305,10 @@ Pipeline 失败
 └── 部署失败
     ├── "Connection refused" (SSH) → 目标服务器 SSH 端口/密钥
     ├── "health check failed" → 应用启动慢，增加重试等待
-    └── "port already in use" → docker compose down 先停旧容器
+    ├── "port already in use" → docker compose down 先停旧容器
+    ├── "no such service: xxx" → 服务器 compose 与 CI 配置不一致
+    ├── health check 失败但容器在跑 → curl URL 的端口与实际服务端口不匹配
+    └── --no-deps 跳过了 nginx → health check 走 port 80 但 nginx 未启动
 ```
 
 ### 3.2 常见错误速查
@@ -323,6 +326,9 @@ Pipeline 失败
 | `denied: requested access` (push) | ACR 镜像路径缺 namespace | registry/**namespace**/image |
 | `docker compose pull` 超时 | 拉了 Docker Hub 的 postgres/redis | `docker compose pull gateway web` 只拉业务镜像 |
 | `docker compose up -d` 也超时 | up 隐含 pull 所有 service | `docker compose up -d --no-deps gateway web` |
+| health check 失败但容器在跑 | curl URL 端口 ≠ 服务端口 | 检查 nginx(80) vs gateway(8080)，直接 `curl :8080/health` |
+| `--no-deps` 后 nginx 没启动 | nginx 被 no-deps 跳过 | 显式加 `--no-deps gateway web nginx` |
+| `no such service: xxx` | 服务器 compose 缺 service | SSH 检查实际 compose 文件 |
 | `missing icon file 120x120` | 无 App Icon asset | 创建 Assets.xcassets + AppIcon |
 | `UIInterfaceOrientation` iPad | 缺 iPad 方向声明 | 四方向 + `UIRequiresFullScreen` |
 
@@ -536,7 +542,49 @@ grep -rn 'password\|secret\|token' .gitea/workflows/ | grep -v 'secrets\.' | gre
 
 ---
 
-## 8. 与其他技能的关系
+## 8. CD 部署前验证清单
+
+**每次修改 deploy 步骤前必须逐项确认：**
+
+```
+1. 服务器 compose 有哪些 service？
+   → ssh <server> "docker compose -f <file> config --services"
+
+2. CI deploy 启动了哪些 service？
+   → grep "up -d" .gitea/workflows/ci-cd.yml
+
+3. health check URL 指向哪个端口？
+   → grep "curl.*health" .gitea/workflows/ci-cd.yml
+
+4. 该端口由哪个 service 服务？
+   → port 80 = nginx, port 8080 = gateway, port 3001 = web
+
+5. 该 service 是否在 deploy 启动列表中？
+   → 如果 health check 走 nginx:80，deploy 必须包含 nginx
+
+6. 基础服务（postgres/redis）是否已运行？
+   → docker compose ps 检查，不要在 CI 中重启它们
+
+7. Docker Hub 可达吗？
+   → 国内服务器必须配镜像源，或只拉 ACR 镜像
+```
+
+**部署命令标准模板：**
+```bash
+# 只拉业务镜像（不触碰 Docker Hub）
+docker compose -f docker-compose.prod.yml pull gateway web
+
+# 只重启业务容器 + nginx（不动 postgres/redis）
+docker compose -f docker-compose.prod.yml up -d --no-deps gateway web nginx
+
+# 直接检查 gateway 端口（不依赖 nginx）
+sleep 10
+curl -sf http://localhost:8080/health
+```
+
+---
+
+## 9. 与其他技能的关系
 
 | 技能 | 协作点 |
 |------|--------|