laily
10d8800f07
Give ack, builder, and deployer an explicit init/check mode that reports missing project config instead of failing mid-work. Point builder at makefile.builder so its contract targets do not collide with an existing Makefile.
128 lines
5.8 KiB
Markdown
128 lines
5.8 KiB
Markdown
# deployer
|
||
|
||
把「服务怎么跑」写进 Git，部署方法由这个 skill 自带：换台电脑、换个项目都能直接用。
|
||
|
||
支持三种用法：
|
||
|
||
- **独立配置中心**：一个专门的 Git 仓库管所有机器的所有 Compose 服务（如 app00）
|
||
- **项目内 Compose 环境**：在普通项目里放 `.pouch/deployer/{prod,test,dev}/`，
|
||
把这个项目的生产/测试/开发环境用 rsync + docker compose 部署
|
||
- **Argo CD / GitOps**：项目里放 `.pouch/deployer/argocd.yaml`；Agent 改 GitOps 并开 MR，
|
||
你合并后由 Argo CD 同步。仓库既可以只写 Git 地址（部署时浅 clone），也可以指定本机已有目录。
|
||
|
||
## 什么时候使用
|
||
|
||
- 给新项目初始化 deployer：检查缺什么，引导补 `.pouch/deployer/`
|
||
- 想用一套固定流程把本地改好的 Docker Compose 配置发到某台服务器
|
||
- 要升级某个服务的镜像版本、重启服务、看远程容器状态和日志
|
||
- 有编译好的 .deb 包要装到某台机器上（scp 上传安装，或从 URL 直接拉）
|
||
- 新加一个服务、把服务从一台机器挪到另一台、或下线旧服务
|
||
- 想给当前项目加 prod/test/dev 三套远程环境并随时部署其中一套
|
||
- ACK 说「重新布测试环境」或跑回归前要先拉起 `.pouch/deployer/test`
|
||
- 需要一张「哪台机器跑哪些服务」的清单
|
||
- 镜像要进 Kubernetes，走 Argo CD：改 GitOps、开 MR、合并后部署
|
||
|
||
## 使用前准备
|
||
|
||
- Compose：本机 Python 3、`rsync`、`ssh`；目标机器 Docker Compose v2；`~/.ssh/config` 免密（或 agent）
|
||
- 知道每个 Compose 服务的运行时数据放在哪（这些目录不能被同步覆盖）
|
||
- Argo CD：能 clone/push GitOps 仓库（SSH 或已登录的 HTTPS），并能开 MR（GitLab `glab` / GitHub `gh` / Gitea `tea`）。本机不必长期放一份 GitOps checkout。
|
||
|
||
## 使用示例
|
||
|
||
```text
|
||
# 新项目
|
||
用 deployer 初始化这个项目
|
||
给这个项目接上 test 环境，SSH 别名是 my-vps
|
||
|
||
# 独立配置中心
|
||
帮我把 vyyo1/naiveproxy 的配置改完部署上去
|
||
升级 vora3/gpt-load 的镜像版本
|
||
列一下现在所有服务和各自在哪台机器上
|
||
新增一个服务 uptime 到 vora3，先帮我建好目录结构
|
||
vhom1 上那个 naiveproxy 为什么 sync 失败？
|
||
|
||
# deb 包安装
|
||
把 ./gpt-load_1.2.0_amd64.deb 装到 web1 上
|
||
把这个目录里的三个 .deb 都推到 deploy@nas 再安装
|
||
web1 能出网，直接让它从 https://... 把包拉下来装
|
||
|
||
# 项目内环境
|
||
给这个项目建好 .pouch/deployer，prod 和 test 分别放到两台机器上
|
||
把 test 环境重新部署一下
|
||
prod 的 compose 加个 redis，改完发上去
|
||
|
||
# Argo CD
|
||
把这个项目接到 argocd，仓库写成 git@git.example.com:org/infra-gitops.git
|
||
GitOps 我已经 clone 在 ../infra-gitops，用那个目录开 MR
|
||
升镜像 tag，改 GitOps 开 MR
|
||
```
|
||
|
||
## Agent 会做什么
|
||
|
||
1. 读服务/环境目录（及共享的父目录）的 `_config.yaml`，确定目标机器和远程路径；
|
||
项目内布局从 `.pouch/deployer/` 自动发现，无需额外配置
|
||
2. 用 skill 自带脚本把本地目录同步到远程（rsync，自动排除 `data/`、`_data/`）
|
||
3. 在远程执行对应的 `docker compose` 操作（启动 / 重建 / 升级 / 重启）
|
||
4. deb 包安装走独立脚本：scp 上传到暂存目录后远程 apt 安装，失败自动修依赖
|
||
5. 同步后查看容器状态和日志确认生效
|
||
6. 只针对你指定的那一个服务操作，不会批量动整台机器
|
||
7. Argo CD：读 `.pouch/deployer/argocd.yaml`，浅 clone 或使用 `repo_dir`，改清单，推分支开 MR，停下来等你合并；
|
||
不直接 kubectl 发布，不把 Harbor/TLS 密钥提交进 Git
|
||
|
||
项目内布局下，远程目录名自动带上项目前缀（如 `my-project-prod`），
|
||
避免同一台机器上多个项目的同名环境互相覆盖；需要固定名字时在 `_config.yaml` 写 `name:`。
|
||
|
||
重要边界：同步使用 `--delete`，远程多余的文件会被删除；数据库、证书等运行时数据
|
||
必须放在排除目录或远程绝对路径挂载。涉及删除数据卷、清理远程文件的操作会先向你确认。
|
||
|
||
## 如何判断完成
|
||
|
||
- 脚本输出显示同步完成、远程命令执行成功
|
||
- `ps` 显示容器 Up、`logs` 无报错；升级后镜像 tag 与配置一致
|
||
- deb 安装后 `ssh <node> dpkg -l` 能看到目标包，服务能正常启动
|
||
- 域名/端口类服务能 curl 通
|
||
- Argo CD：给出 MR 链接；合入后 Application Synced，域名/healthz 可访问
|
||
|
||
## Argo CD 的两种接法
|
||
|
||
在业务项目里放 `.pouch/deployer/argocd.yaml`。Agent 只改 GitOps 并开 MR，**你合并之后** Argo CD 才部署。镜像、namespace、域名、Secret 名以 GitOps 清单为准，不必在这个文件里再抄一遍。
|
||
|
||
### 1. 只写仓库地址（默认）
|
||
|
||
本机不用长期放 GitOps 仓库。部署时 Agent 浅 clone 到临时目录，改完开 MR，用完删掉。
|
||
|
||
```yaml
|
||
# .pouch/deployer/argocd.yaml
|
||
repo: git@git.example.com:org/infra-gitops.git
|
||
```
|
||
|
||
`https://git.example.com/org/infra-gitops.git` 也可以。对本机 git 来说这个地址要能 clone 和 push。
|
||
|
||
对 Agent 说：
|
||
|
||
```text
|
||
把这个项目接到 argocd，仓库是 git@git.example.com:org/infra-gitops.git
|
||
升到 v0.0.2，改 GitOps 开 MR
|
||
```
|
||
|
||
### 2. 指定本地目录（不 clone）
|
||
|
||
GitOps 仓库已经 checkout 在旁边时，写 `repo_dir`，Agent 直接进这个目录改、推分支、开 MR。
|
||
|
||
```yaml
|
||
# .pouch/deployer/argocd.yaml
|
||
repo: git@git.example.com:org/infra-gitops.git
|
||
repo_dir: ../infra-gitops
|
||
```
|
||
|
||
也可以只写 `repo_dir`（远程从该目录的 `origin` 读）。相对路径相对**业务项目根**。
|
||
|
||
对 Agent 说：
|
||
|
||
```text
|
||
GitOps 已经 clone 在 ../infra-gitops，用那个目录开 MR
|
||
```
|
||
|
||
两种接法都可以再加 `path:`，仅当 Application 目录不是默认的 `argocd/applications/<项目名>` 时才需要。
|