laily
adaa8e4edd
agent-runtime executes fixed tester node operations over JSON stdin. deployer prepare brings up the local test Compose service the same way. test-preflight now passes the tester binding; tester select skips unauthorized cases before creating a runner.
101 lines
7.9 KiB
Markdown
101 lines
7.9 KiB
Markdown
---
|
||
name: deployer
|
||
description: >-
|
||
初始化或检查项目部署配置；管理测试环境的本机 Docker Compose、通过 app00 Agent
|
||
terminal 触发正式环境部署，以及 Argo CD GitOps（改清单开 MR，用户合并后同步）。触发词：初始化
|
||
deployer、部署、sync、升级、装 deb、ArgoCD、GitOps；ACK 拉起测试环境时也可使用。
|
||
---
|
||
|
||
# deployer：测试本机 Compose、正式 Agent 部署与 Argo CD GitOps
|
||
|
||
- **测试 Compose**：本地镜像/配置 → 在本机环境目录触发 `docker compose`，不 SSH、不走远程同步。
|
||
- **正式部署**：不由当前 Agent 直接 SSH；把单服务部署任务委派给本机 `~/code/app00` 项目的
|
||
fresh Agent terminal，由该 Agent 按 app00 的正式入口执行并回报证据。
|
||
- **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)。
|
||
- 两者都有且意图不清：先问。
|
||
- 不适用：没有 `.pouch/deployer/` 的随手 `docker compose`、Nomad、常规 `kubectl apply`、构建并推送镜像（走 builder）。测试 node 必须是本机；正式环境不在这里直接 SSH。
|
||
|
||
## 边界
|
||
|
||
- 所有 sync/up/recreate/upgrade/restart 必须按单服务执行，禁止节点级批量。
|
||
- `rsync` 带 `--delete`：sync 前先把远程服务目录拷到 `$HOME/bakeup/deployer-skill/<name>/<时间戳>/`（每服务留 5 份）；运行时数据仍须在 `data/`、`_data/` 或远程绝对路径挂载，否则会被清掉。
|
||
- 仓库只放静态配置；证书、数据库、上传文件不进 Git，也不进同步范围。`unused/` 不参与发现与部署。
|
||
- `node` 是非正式 Compose 轨道的 `~/.ssh/config` Host 别名（可用 `user@host`）。用户没给别名就不要写假 node。
|
||
- `.pouch/deployer/test` 固定本机触发：若 node、镜像或 Compose 不满足本机条件，直接报告 `environment-fail`，禁止退回 SSH。
|
||
- `.pouch/deployer/prod` 固定走 [production-agent.md](references/production-agent.md)，禁止执行 `sync.py`、`remote.py` 或直接 SSH。
|
||
- 密钥不入库。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` 用户点名再加。`test` 记录本机执行；`prod` 只记录用于生成 app00 selector 的 `node/name`，不要求当前 Agent 的 SSH 部署配置，并确认 app00 Agent 路由可用。没有必要字段就不要发明假值，目录可建、列为待配置。有根目录 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（无 rsync 时 sync 用 scp 兜底，不擅自安装）
|
||
下一步: 一句话
|
||
```
|
||
|
||
## 检查
|
||
|
||
只读。运行 `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` 环境，否则报告 `environment-fail`。未点名 `prod` 不要动它。
|
||
3. 不要改 compose tag、不要构建镜像、不要看其它环境。
|
||
4. `test` 环境：确认解析出的 node 是本机、`docker image inspect` 能看到 compose tag；进入 `.pouch/deployer/test/` 执行 `docker compose up -d --force-recreate`，再 `docker compose ps`。不要 `sync.py`、`remote.py`、SSH 或创建部署 Agent terminal。
|
||
5. `prod` 环境：停止本轨道的 Compose 操作，读取 [production-agent.md](references/production-agent.md)，在本机 `~/code/app00` 项目创建 fresh Agent terminal 并委派正式部署；当前 Agent 不得直接执行 `sync.py`、`remote.py` 或 SSH。
|
||
6. 只有明确点名的非正式远程 Compose 环境，才允许 `sync.py <svc>` 后调用 `remote.py <svc> recreate`；只重启调用 `remote.py <svc> restart`，并用 `remote.py <svc> ps` 验证。
|
||
|
||
test-preflight 的一次性部署入口为 `scripts/deploy/prepare.py`。它从 stdin 接收
|
||
`{"operation":"prepare","environment":"test","project_root":"/abs/project","host":"...","public_host":"..."}`，
|
||
只解析项目 `.pouch/deployer/test`，复用 `lib.service_info` 的 `_config.yaml` 继承和 node
|
||
规则，确认 node 是本机后才按 `docker compose config`、`up -d --force-recreate`、`ps`
|
||
顺序准备单个 test 服务。输出始终是 `{status, observed, deployment_id?, checks?}` JSON；
|
||
prod、缺配置、非本机 node 为 `blocked`，Compose/命令失败为 `environment-fail`。诊断只写
|
||
stderr，不输出 `.env` 或命令输出中的凭据。
|
||
|
||
compose 用 `image:` 且用户说刚合并了代码：现有 tag 对不上这次提交时，**一句问**要不要先重建镜像，然后停。不要自己改 tag、不要走 builder。
|
||
|
||
新增/下线、deb、镜像 tag 升级、NAS 失败：再读 [compose.md](references/compose.md)。字段见 [config-reference.md](references/config-reference.md)。
|
||
|
||
## 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 不入库。
|