feat(deployer): add Argo CD / GitOps workflow with MR-based deployment

2026-08-24 20:37:55 +08:00
parent 282a6809ac
commit ee31278947
4 changed files with 279 additions and 36 deletions
@@ -1,13 +1,14 @@
 # deployer

-把「一堆 VPS / NAS 上的 Docker 服务」变成一个 Git 仓库就能管的事：仓库里只放服务配置（数据），
-部署、同步、升级的方法和脚本全部由这个 skill 自带，换台电脑、换个项目都能直接用。
+把「服务怎么跑」写进 Git，部署方法由这个 skill 自带：换台电脑、换个项目都能直接用。

-支持两种用法：
+支持三种用法：

- **独立配置中心**：一个专门的 Git 仓库管所有机器的所有服务（如 app00）
- **项目内环境**：在普通项目里放 `.skiff/deployer/{prod,test,dev}/`，
-  把这个项目的生产/测试/开发环境也用同一套流程部署
+- **独立配置中心**：一个专门的 Git 仓库管所有机器的所有 Compose 服务（如 app00）
+- **项目内 Compose 环境**：在普通项目里放 `.skiff/deployer/{prod,test,dev}/`，
+  把这个项目的生产/测试/开发环境用 rsync + docker compose 部署
+- **Argo CD / GitOps**：项目里放 `.skiff/deployer/argocd.yaml`；Agent 改 GitOps 并开 MR，
+  你合并后由 Argo CD 同步。仓库既可以只写 Git 地址（部署时浅 clone），也可以指定本机已有目录。

 ## 什么时候使用

@@ -17,13 +18,13 @@
 - 新加一个服务、把服务从一台机器挪到另一台、或下线旧服务
 - 想给当前项目加 prod/test/dev 三套远程环境并随时部署其中一套
 - 需要一张「哪台机器跑哪些服务」的清单
+- 镜像要进 Kubernetes，走 Argo CD：改 GitOps、开 MR、合并后部署

 ## 使用前准备

- 本机装有 Python 3、`rsync`、`ssh`
- 目标机器装好 Docker + Docker Compose v2
- `~/.ssh/config` 里为每台机器配好 Host 别名，且能免密（或 agent）登录
- 知道每个服务的运行时数据放在哪（这些目录不能被同步覆盖）
+- 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。

 ## 使用示例

@@ -44,6 +45,11 @@ web1 能出网，直接让它从 https://... 把包拉下来装
 给这个项目建好 .skiff/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 会做什么
@@ -55,6 +61,8 @@ prod 的 compose 加个 redis，改完发上去
 4. deb 包安装走独立脚本：scp 上传到暂存目录后远程 apt 安装，失败自动修依赖
 5. 同步后查看容器状态和日志确认生效
 6. 只针对你指定的那一个服务操作，不会批量动整台机器
+7. Argo CD：读 `.skiff/deployer/argocd.yaml`，浅 clone 或使用 `repo_dir`，改清单，推分支开 MR，停下来等你合并；
+   不直接 kubectl 发布，不把 Harbor/TLS 密钥提交进 Git

 项目内布局下，远程目录名自动带上项目前缀（如 `my-project-prod`），
 避免同一台机器上多个项目的同名环境互相覆盖；需要固定名字时在 `_config.yaml` 写 `name:`。
@@ -68,3 +76,46 @@ prod 的 compose 加个 redis，改完发上去
 - `ps` 显示容器 Up、`logs` 无报错；升级后镜像 tag 与配置一致
 - deb 安装后 `ssh <node> dpkg -l` 能看到目标包，服务能正常启动
 - 域名/端口类服务能 curl 通
+- Argo CD：给出 MR 链接；合入后 Application Synced，域名/healthz 可访问
+
+## Argo CD 的两种接法
+
+在业务项目里放 `.skiff/deployer/argocd.yaml`。Agent 只改 GitOps 并开 MR，**你合并之后** Argo CD 才部署。镜像、namespace、域名、Secret 名以 GitOps 清单为准，不必在这个文件里再抄一遍。
+
+### 1. 只写仓库地址（默认）
+
+本机不用长期放 GitOps 仓库。部署时 Agent 浅 clone 到临时目录，改完开 MR，用完删掉。
+
+```yaml
+# .skiff/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
+# .skiff/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/<项目名>` 时才需要。