feat(deployer): skip sync on localhost and complete skill READMEs
Redeploy locally with docker compose when the node is 127.0.0.1 and the image already exists. Make list/sync/remote/deb importable under python3 -I -S. Add human README.md for every builtin skill, slim ack's user-facing docs, and drop unused OpenSpec config.
This commit is contained in:
@@ -22,6 +22,15 @@
|
||||
- 需要一张「哪台机器跑哪些服务」的清单
|
||||
- 镜像要进 Kubernetes，走 Argo CD：改 GitOps、开 MR、合并后部署
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
pouch add deployer # 当前项目
|
||||
pouch add deployer -g # 全局
|
||||
```
|
||||
|
||||
不要 `pouch init deployer`。对新项目说「用 deployer 初始化」。
|
||||
|
||||
## 使用前准备
|
||||
|
||||
- Compose：本机 Python 3、`rsync`、`ssh`；目标机器 Docker Compose v2；`~/.ssh/config` 免密（或 agent）
|
||||
@@ -50,6 +59,7 @@ web1 能出网，直接让它从 https://... 把包拉下来装
|
||||
# 项目内环境
|
||||
给这个项目建好 .pouch/deployer，prod 和 test 分别放到两台机器上
|
||||
把 test 环境重新部署一下
|
||||
本机测试镜像已经有了，直接重启，别 sync
|
||||
prod 的 compose 加个 redis，改完发上去
|
||||
|
||||
# Argo CD
|
||||
@@ -62,8 +72,8 @@ GitOps 我已经 clone 在 ../infra-gitops，用那个目录开 MR
|
||||
|
||||
1. 读服务/环境目录（及共享的父目录）的 `_config.yaml`，确定目标机器和远程路径；
|
||||
项目内布局从 `.pouch/deployer/` 自动发现，无需额外配置
|
||||
2. 用 skill 自带脚本把本地目录同步到远程（rsync，自动排除 `data/`、`_data/`）
|
||||
3. 在远程执行对应的 `docker compose` 操作（启动 / 重建 / 升级 / 重启）
|
||||
2. 目标是本机且镜像已在本机 docker：不 sync、不 SSH，在该环境目录直接 `docker compose`
|
||||
3. 否则用 skill 自带脚本把本地目录同步到远程（rsync，自动排除 `data/`、`_data/`），再远程 `docker compose`（启动 / 重建 / 升级 / 重启）
|
||||
4. deb 包安装走独立脚本：scp 上传到暂存目录后远程 apt 安装，失败自动修依赖
|
||||
5. 同步后查看容器状态和日志确认生效
|
||||
6. 只针对你指定的那一个服务操作，不会批量动整台机器
|
||||
@@ -78,8 +88,8 @@ GitOps 我已经 clone 在 ../infra-gitops，用那个目录开 MR
|
||||
|
||||
## 如何判断完成
|
||||
|
||||
- 脚本输出显示同步完成、远程命令执行成功
|
||||
- `ps` 显示容器 Up、`logs` 无报错；升级后镜像 tag 与配置一致
|
||||
- 本机：`docker compose ps` 容器 Up。远程：sync 成功且 `remote.py ps` 容器 Up
|
||||
- `logs` 无报错；升级后镜像 tag 与配置一致
|
||||
- deb 安装后 `ssh <node> dpkg -l` 能看到目标包，服务能正常启动
|
||||
- 域名/端口类服务能 curl 通
|
||||
- Argo CD：给出 MR 链接；合入后 Application Synced，域名/healthz 可访问
|
||||
|
||||
@@ -19,10 +19,10 @@ description: >-
|
||||
|
||||
- 初始化、接入 deployer，或给新项目建测试/生产环境：执行「初始化」。
|
||||
- 检查 `.pouch/deployer`、node、compose 是否齐全：执行「检查」。
|
||||
- 部署、同步、升级、重启、装 deb、新增/下线服务：执行「Compose 操作」。发现不了服务或解析不出 node 时停止，转入「初始化」。不要静默初始化。
|
||||
- 部署、重新部署、同步、升级、重启、布测试环境、装 deb、新增/下线服务：执行「Compose 操作」。发现不了服务或解析不出 node 时停止，转入「初始化」。不要静默初始化。
|
||||
- ArgoCD / GitOps / 开 MR 部署：执行「Argo CD」。步骤见 [argocd.md](references/argocd.md)。
|
||||
- 两者都有且意图不清：先问。
|
||||
- 不适用：单机 docker、Nomad、常规 `kubectl apply`、构建并推送镜像（走 builder）。
|
||||
- 不适用：没有 `.pouch/deployer/` 的随手 `docker compose`、Nomad、常规 `kubectl apply`、构建并推送镜像（走 builder）。本机 node 仍走本 skill，镜像已在本机则跳过 sync。
|
||||
|
||||
## 边界
|
||||
|
||||
@@ -66,11 +66,22 @@ python3 -I -S <skill-dir>/scripts/deploy/check.py --project <project-root>
|
||||
|
||||
## 被 ACK 调用
|
||||
|
||||
ACK 的「运行测试环境」和回归前布环境会加载本 skill，对 `.pouch/deployer/<env>`（通常是 `test`）按「Compose 操作」执行。ACK 只负责何时布、把访问地址写入 `deliveryRuns`；不要把本 skill 的脚本复制进 ACK。生产环境、Argo CD 合入和节点级批量仍须用户明确要求。
|
||||
ACK 的「运行测试环境」和回归前布环境会加载本 skill，按「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` 验证。
|
||||
重启 / 重新部署 / 同步 / 布测试环境走默认路径。不要读 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](references/compose.md)。字段见 [config-reference.md](references/config-reference.md)。
|
||||
|
||||
## Argo CD
|
||||
|
||||
|
||||
@@ -81,6 +81,8 @@ python3 <skill-dir>/scripts/deploy/sync.py <service-path>
|
||||
|
||||
| 意图 | 命令 |
|
||||
|------|------|
|
||||
| 本机已有镜像（node 是 localhost，image 已在本机 docker） | 不要 sync。在 env 目录 `docker compose up -d --force-recreate` |
|
||||
| 重新部署远程环境 | `sync.py <svc> && remote.py <svc> recreate` |
|
||||
| 只同步文件，不动容器 | `sync.py <svc>` |
|
||||
| 应用 compose/配置变更 | `sync.py <svc> && remote.py <svc> up` |
|
||||
| 改配置后强制重建 | `remote.py <svc> recreate`（配合前置 sync） |
|
||||
@@ -88,7 +90,7 @@ python3 <skill-dir>/scripts/deploy/sync.py <service-path>
|
||||
| 仅重启，不同步文件 | `remote.py <svc> restart` |
|
||||
| 排查 | `remote.py <svc> ps` / `remote.py <svc> logs` |
|
||||
|
||||
若项目有 Makefile 封装，命令形如 `make deploy TGT=<服务路径>`。没有 Makefile 时直接调 python 脚本，不要新建封装层。
|
||||
脚本一律 `python3 -I -S <skill-dir>/scripts/deploy/<name>.py`。有 `make deploy TGT=` 才用 Makefile；没有就直接调脚本，不要读 Makefile 去发明封装。
|
||||
|
||||
`sync.py` 使用 `rsync -avz --delete`；本机无 rsync 时 tar over SSH 兜底。运行时数据必须放在默认排除的 `data/`、`_data/`，或 compose 挂载的远程绝对路径，否则会被清掉。
|
||||
|
||||
|
||||
@@ -31,7 +31,11 @@ import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from lib import (
|
||||
_SCRIPT_DIR = Path(__file__).resolve().parent
|
||||
if str(_SCRIPT_DIR) not in sys.path:
|
||||
sys.path.insert(0, str(_SCRIPT_DIR))
|
||||
|
||||
from lib import ( # noqa: E402
|
||||
project_root,
|
||||
run_remote,
|
||||
scp_base_args,
|
||||
|
||||
@@ -6,8 +6,13 @@ from __future__ import annotations
|
||||
import os
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
from pathlib import Path
|
||||
|
||||
from lib import discover_services, project_root
|
||||
_SCRIPT_DIR = Path(__file__).resolve().parent
|
||||
if str(_SCRIPT_DIR) not in sys.path:
|
||||
sys.path.insert(0, str(_SCRIPT_DIR))
|
||||
|
||||
from lib import discover_services, project_root # noqa: E402
|
||||
|
||||
|
||||
def main() -> int:
|
||||
|
||||
@@ -20,8 +20,13 @@ import argparse
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from lib import project_root, run_remote, service_info
|
||||
_SCRIPT_DIR = Path(__file__).resolve().parent
|
||||
if str(_SCRIPT_DIR) not in sys.path:
|
||||
sys.path.insert(0, str(_SCRIPT_DIR))
|
||||
|
||||
from lib import project_root, run_remote, service_info # noqa: E402
|
||||
|
||||
REMOTE_COMMANDS = {
|
||||
"up": "docker compose up -d",
|
||||
|
||||
@@ -16,8 +16,13 @@ import shlex
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from lib import DEFAULT_BASE_PATH, project_root, rsync_ssh_args, service_info, ssh_cmd
|
||||
_SCRIPT_DIR = Path(__file__).resolve().parent
|
||||
if str(_SCRIPT_DIR) not in sys.path:
|
||||
sys.path.insert(0, str(_SCRIPT_DIR))
|
||||
|
||||
from lib import DEFAULT_BASE_PATH, project_root, rsync_ssh_args, service_info, ssh_cmd # noqa: E402
|
||||
|
||||
|
||||
def sync_directory(info: dict) -> int:
|
||||
|
||||
Reference in New Issue
Block a user