.pouch/skills/deployer/SKILL.md

name, description

name	description
deployer	初始化或检查项目部署配置；管理多机 Docker Compose（脚本同步后远程 compose）与 Argo CD GitOps（改清单开 MR，用户合并后同步）。触发词：初始化 deployer、部署、sync、升级、装 deb、ArgoCD、GitOps；ACK 拉起测试环境时也可使用。

deployer：Compose 节点与 Argo CD GitOps

• Compose：本地改 compose.yaml → 脚本同步到 SSH 节点 → 远程 docker compose。
• Argo CD：改 GitOps 仓库清单 → 开 PR/MR → 用户合并 → Argo CD 同步。不要用 Compose 的 sync.py/remote.py 去推集群。

开始时解析当前 SKILL.md 所在目录，记为 <skill-dir>。优先 git rev-parse --show-toplevel 解析项目根。不要创建 .pouch/deployer/ 之外的 假配置中心，也不要用 pouch init deployer。

选择模式

• 初始化、接入 deployer，或给新项目建测试/生产环境：执行「初始化」。
• 检查 .pouch/deployer、node、compose 是否齐全：执行「检查」。
• 部署、重新部署、同步、升级、重启、布测试环境、装 deb、新增/下线服务：执行「Compose 操作」。发现不了服务或解析不出 node 时停止，转入「初始化」。不要静默初始化。
• ArgoCD / GitOps / 开 MR 部署：执行「Argo CD」。步骤见 argocd.md。
• 两者都有且意图不清：先问。
• 不适用：没有 .pouch/deployer/ 的随手 docker compose、Nomad、常规 kubectl apply、构建并推送镜像（走 builder）。本机 node 仍走本 skill，镜像已在本机则跳过 sync。

边界

• 所有 sync/up/recreate/upgrade/restart 必须按单服务执行，禁止节点级批量。
• rsync 带 --delete：运行时数据必须在 data/、_data/ 或远程绝对路径挂载，否则会被清掉。
• 仓库只放静态配置；证书、数据库、上传文件不进 Git，也不进同步范围。unused/ 不参与发现与部署。
• node 是 ~/.ssh/config 的 Host 别名（可用 user@host）。用户没给别名就不要写假 node。
• 密钥不入库。Compose 优先放远程 .env；Argo CD 的 dockerconfigjson / TLS 私钥只存在集群 Secret。
• 不 --force 推送、不硬 reset，除非用户明确要求。Argo CD 不直接推默认分支。
• 镜像固定 tag，不用 :latest；成对升级的服务要同步升。
• ACK 调用不能把范围扩到生产环境、Argo 合入或节点级批量。

初始化

独立配置中心仓库（已设 DEPLOYER_ROOT）只做检查，不要改成项目内布局。_config.yaml 字段见 config-reference.md。

1. 探测：.pouch/deployer/、根目录 compose、Dockerfile、ACK intents.testEnvironment、argocd.yaml。
2. Compose 与 Argo 都有且意图不清：先问。两边都要也可以，必须分开确认。
3. Compose / 新项目（ACK 默认需要 test）：默认只建 test；prod/dev 用户点名再加。问 SSH Host 别名；没给不要写假 node，目录可建、列为待配置。有根目录 compose：提议迁到 .pouch/deployer/<env>/，确认后才动。只有 Dockerfile：可给单服务 compose 草稿，用户确认后写入，不发明多服务网格。
4. Argo：只问 GitOps repo（或 repo_dir），写 .pouch/deployer/argocd.yaml。不 clone、不开 MR、不 kubectl apply。
5. 运行（不 SSH、不 up）：

python3 -I -S <skill-dir>/scripts/deploy/check.py --project <project-root>

6. 缺 node / compose / ssh 别名 = 部分完成或阻塞。不覆盖已有 compose/_config.yaml。除非用户明确要求，不部署、不提交。

## deployer 初始化：完成 | 部分完成 | 阻塞

已具备: …
待配置: 路径 + 字段 + 可粘贴示例 + 缺了会挡住哪步
工具链: ssh / rsync（缺则怎么装，不擅自安装）
下一步: 一句话

检查

只读。运行 scripts/deploy/check.py --project <project-root>，用同一报告格式，标题改为 ## deployer 检查：…。不写文件、不 SSH。用户明确要求修复后再转入初始化。

被 ACK 调用

ACK 的「运行测试环境」和回归前布环境会加载本 skill，按「Compose 操作」的默认路径布测试环境。ACK 只负责何时布、把访问地址写入 deliveryRuns；不要把本 skill 的脚本复制进 ACK。生产环境、Argo CD 合入和节点级批量仍须用户明确要求。

Compose 操作

重启 / 重新部署 / 同步 / 布测试环境走默认路径。不要读 compose.md、不要初始化、不要读 Makefile。

1. 在项目根执行：python3 -I -S <skill-dir>/scripts/deploy/list.py
2. 只操作一个服务：用户点名的 env；「测试」→ test，没有 test 就用非 prod 的那个。未点名 prod 不要动它。
3. 不要改 compose tag、不要构建镜像、不要看其它环境。
4. 本机镜像：node 的 ssh HostName 是 127.0.0.1/localhost，且 docker image inspect 看得到 compose 里的 tag → 不要 sync.py / remote.py。进 .pouch/deployer/<env>/ 执行 docker compose up -d --force-recreate，再 ps。完。
5. 否则才 sync + remote：python3 -I -S <skill-dir>/scripts/deploy/sync.py <svc> 然后 python3 -I -S <skill-dir>/scripts/deploy/remote.py <svc> recreate。只要重启：remote.py <svc> restart。
6. 远程路径验证：remote.py <svc> ps；异常再 logs。完。

compose 用 image: 且用户说刚合并了代码：现有 tag 对不上这次提交时，一句问要不要先重建镜像，然后停。不要自己改 tag、不要走 builder。

新增/下线、deb、镜像 tag 升级、NAS 失败：再读 compose.md。字段见 config-reference.md。

Argo CD

读 argocd.md。读 .pouch/deployer/argocd.yaml（无则只问 Git 地址写成 repo:）。按已有应用惯例改清单，从默认分支拉出分支开 MR。停在 MR，不合并、不 kubectl apply 工作负载。无 app-of-apps 时提醒用户首次 apply 那份 application.yaml。Harbor / TLS Secret 不入库。