---
name: deployer
description: >-
  初始化或检查项目部署配置；管理多机 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](references/argocd.md)。
- 两者都有且意图不清：先问。
- 不适用：单机 docker、Nomad、常规 `kubectl apply`、构建并推送镜像（走 builder）。

## 边界

- 所有 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](references/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）：

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

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

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

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

## 检查

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

## 被 ACK 调用

ACK 的「运行测试环境」和回归前布环境会加载本 skill，对 `.pouch/deployer/<env>`（通常是 `test`）按「Compose 操作」执行。ACK 只负责何时布、把访问地址写入 `deliveryRuns`；不要把本 skill 的脚本复制进 ACK。生产环境、Argo CD 合入和节点级批量仍须用户明确要求。

## Compose 操作

读 [compose.md](references/compose.md)。用 `list.py` 摸底，再按意图对**单个服务**执行 sync/up/recreate/upgrade/restart。解析 `_config.yaml` 见 [config-reference.md](references/config-reference.md)。sync 报错但 ssh 正常时，按 compose.md 的 NAS 兜底处理。每次操作后 `remote.py <svc> ps` / `logs` 验证。

## Argo CD

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