.pouch/skills/deployer/README.md

deployer

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

支持两种用法：

• 独立配置中心：一个专门的 Git 仓库管所有机器的所有服务（如 app00）
• 项目内环境：在普通项目里放 .skiff/deployer/{prod,test,dev}/， 把这个项目的生产/测试/开发环境也用同一套流程部署

什么时候使用

• 想用一套固定流程把本地改好的 Docker Compose 配置发到某台服务器
• 要升级某个服务的镜像版本、重启服务、看远程容器状态和日志
• 有编译好的 .deb 包要装到某台机器上（scp 上传安装，或从 URL 直接拉）
• 新加一个服务、把服务从一台机器挪到另一台、或下线旧服务
• 想给当前项目加 prod/test/dev 三套远程环境并随时部署其中一套
• 需要一张「哪台机器跑哪些服务」的清单

使用前准备

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

使用示例

# 独立配置中心
帮我把 vyyo1/naiveproxy 的配置改完部署上去
升级 vora3/gpt-load 的镜像版本
列一下现在所有服务和各自在哪台机器上
新增一个服务 uptime 到 vora3，先帮我建好目录结构
vhom1 上那个 naiveproxy 为什么 sync 失败？

# deb 包安装
把 ./gpt-load_1.2.0_amd64.deb 装到 web1 上
把这个目录里的三个 .deb 都推到 deploy@nas 再安装
web1 能出网，直接让它从 https://... 把包拉下来装

# 项目内环境
给这个项目建好 .skiff/deployer，prod 和 test 分别放到两台机器上
把 test 环境重新部署一下
prod 的 compose 加个 redis，改完发上去

Agent 会做什么

1. 读服务/环境目录（及共享的父目录）的 _config.yaml，确定目标机器和远程路径； 项目内布局从 .skiff/deployer/ 自动发现，无需额外配置
2. 用 skill 自带脚本把本地目录同步到远程（rsync，自动排除 data/、_data/）
3. 在远程执行对应的 docker compose 操作（启动 / 重建 / 升级 / 重启）
4. deb 包安装走独立脚本：scp 上传到暂存目录后远程 apt 安装，失败自动修依赖
5. 同步后查看容器状态和日志确认生效
6. 只针对你指定的那一个服务操作，不会批量动整台机器

项目内布局下，远程目录名自动带上项目前缀（如 my-project-prod）， 避免同一台机器上多个项目的同名环境互相覆盖；需要固定名字时在 _config.yaml 写 name:。

重要边界：同步使用 --delete，远程多余的文件会被删除；数据库、证书等运行时数据 必须放在排除目录或远程绝对路径挂载。涉及删除数据卷、清理远程文件的操作会先向你确认。

如何判断完成

• 脚本输出显示同步完成、远程命令执行成功
• ps 显示容器 Up、logs 无报错；升级后镜像 tag 与配置一致
• deb 安装后 ssh <node> dpkg -l 能看到目标包，服务能正常启动
• 域名/端口类服务能 curl 通