feat: add deployer

2026-08-24 09:44:59 +08:00
parent 31bc5f45ce
commit e4d4319919
20 changed files with 1971 additions and 288 deletions
@@ -0,0 +1,137 @@
+# `_config.yaml` 配置参考
+
+`_config.yaml` 供 skill 部署脚本解析，决定同步目标与排除规则。可放在**服务目录、部署根或其任意祖先目录**；子目录中的字段覆盖父目录（继承合并）。
+
+## 放置位置（两种布局）
+
+| 布局 | 部署根 | `_config.yaml` 典型位置 |
+|------|--------|------------------------|
+| 独立配置中心仓库（`DEPLOYER_ROOT` 指向） | 仓库根 | 主机目录 `vyyo1/_config.yaml`、服务目录 |
+| 项目内环境 `.skiff/deployer/{env}/` | `.skiff/deployer/` | 根级共享默认、各环境目录覆盖 |
+
+项目布局示例：
+
+```yaml
+# .skiff/deployer/_config.yaml — 三个环境共享
+node: my-vps
+base_path: /srv/apps
+
+# .skiff/deployer/prod/_config.yaml — 仅生产环境差异
+node: prod-vps          # 覆盖父级
+name: my-project-api    # 可选，覆盖默认的 {项目名}-{env}
+```
+
+## 字段一览
+
+| 字段 | 必填 | 可继承 | 说明 |
+|------|------|--------|------|
+| `node` | 是 | 是 | SSH 目标主机别名 |
+| `port` | 否 | 是 | SSH 端口，默认 22 |
+| `identity_file` | 否 | 是 | SSH 私钥路径 |
+| `base_path` | 否 | 是 | 远程部署根目录，默认 `/opt/app` |
+| `sync_exclude` | 否 | 是 | rsync 排除目录列表 |
+| `name` | 否 | 是 | 远程目录名覆盖（见下） |
+
+## name（可选）
+
+远程目录名默认取服务/环境文件夹最后一级名称。**项目内环境布局**默认改为
+`{git仓库名}-{env}`（如 `my-project-prod`），防止同主机多项目的同名环境互相覆盖。
+写 `name:` 显式指定最终远程目录名（不含 base_path 部分）。
+
+## node（必填）
+
+对应 `~/.ssh/config` 中的 `Host` 别名，支持带用户形式：
+
+```yaml
+node: deploy@prod
+```
+
+独立仓库布局默认远程目录名 = 服务文件夹最后一级名称：`vyyo1/naiveproxy` → `{base_path}/naiveproxy`；
+项目环境布局见上文 name 一节。
+兜底规则：合并后仍无 `node` 时，若**直接父目录名**是 SSH Host 别名则作为 node。
+
+
+## port（可选）
+
+```yaml
+node: edge
+port: 2222
+```
+
+sync 通过 `rsync -e "ssh -p PORT"` 连接，remote 使用 `ssh -p PORT`。
+与 `~/.ssh/config` 的 `Port` 同时存在时以 `_config.yaml` 为准（命令行覆盖 config）。
+
+## identity_file（可选）
+
+```yaml
+node: edge
+identity_file: ~/.ssh/deploy_ed25519
+```
+
+须为绝对路径或 `~` 开头；私钥不进 Git。带 passphrase 的密钥需事先加入 ssh-agent，脚本不支持交互输入。
+
+## base_path（可选）
+
+```yaml
+node: nas
+base_path: /volume1/docker   # 默认路径是符号链接的设备写真实路径
+```
+
+实际同步目标 `{base_path}/{服务名}`。
+
+## sync_exclude（可选）
+
+rsync 排除的目录名列表（仅目录名）。默认已排除 `data`、`_data`。
+子级重新定义时**整体替换**父级列表（非追加）：
+
+```yaml
+sync_exclude:
+  - data
+  - _data
+  - logs
+```
+
+运行时数据放这些目录或 compose 挂载的远程绝对路径（如 `/data01/docker/<svc>/`），避免被 `--delete` 清掉。
+
+---
+
+## 继承合并规则
+
+1. 收集**部署根自身**的 `_config.yaml`（全局默认），再收集部署根到服务目录路径上的所有 `_config.yaml`
+2. 按祖先 → 子顺序合并；同名字段后者覆盖前者；`sync_exclude` 整体替换
+3. 无任何配置且父目录名为 SSH Host 别名 → 兜底为 node
+
+## 配置组织建议
+
+| 场景 | 建议 |
+|------|------|
+| 同一 SSH 主机多个服务 | 主机目录写一份 `node`/`base_path`，子服务免重复 |
+| 各服务目标不同 | 服务目录单独写 `_config.yaml` |
+| 个别覆盖 | 子目录只写差异字段 |
+| 项目三环境同主机 | `.skiff/deployer/_config.yaml` 写共享 node，各环境只放差异 |
+| 项目环境分属不同主机 | 各环境 `_config.yaml` 分别写 `node` |
+
+## 示例
+
+```yaml
+# hosts/nas/_config.yaml — 该节点下所有服务共享
+node: nas
+base_path: /volume1/docker
+
+# hosts/web1/_config.yaml
+node: web1
+port: 2222
+identity_file: ~/.ssh/web1_ed25519
+
+# hosts/web2/special/_config.yaml — 覆盖父级的 node
+node: deploy@web2-backup
+```
+
+## 可部署服务判定
+
+同时满足才被 `list.py` 发现：
+
+- 目录内有 `compose.yaml`
+- 能通过继承或兜底解析出 `node`
+- 独立仓库布局：路径中不含 `unused/` 段
+- 项目环境布局：位于部署根 `.skiff/deployer/` 内（其外的项目文件不扫描）