.pouch/skills/deployer/references/config-reference.md

_config.yaml 配置参考

_config.yaml 供 Compose 轨道脚本解析，决定同步目标与排除规则。可放在服务目录、部署根或其任意祖先目录；子目录中的字段覆盖父目录（继承合并）。

Argo CD 轨道用独立文件 .skiff/deployer/argocd.yaml，字段见 argocd.md。 不要把 argocd: 嵌进本文件（脚本解析器不支持嵌套映射）。

放置位置（两种布局）

布局	部署根	_config.yaml 典型位置
独立配置中心仓库（DEPLOYER_ROOT 指向）	仓库根	主机目录 vyyo1/_config.yaml、服务目录
项目内环境 .skiff/deployer/{env}/	.skiff/deployer/	根级共享默认、各环境目录覆盖

项目布局示例：

# .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 别名，支持带用户形式：

node: deploy@prod

独立仓库布局默认远程目录名 = 服务文件夹最后一级名称：vyyo1/naiveproxy → {base_path}/naiveproxy； 项目环境布局见上文 name 一节。 兜底规则：合并后仍无 node 时，若直接父目录名是 SSH Host 别名则作为 node。

port（可选）

node: edge
port: 2222

sync 通过 rsync -e "ssh -p PORT" 连接，remote 使用 ssh -p PORT。 与 ~/.ssh/config 的 Port 同时存在时以 _config.yaml 为准（命令行覆盖 config）。

identity_file（可选）

node: edge
identity_file: ~/.ssh/deploy_ed25519

须为绝对路径或 ~ 开头；私钥不进 Git。带 passphrase 的密钥需事先加入 ssh-agent，脚本不支持交互输入。

base_path（可选）

node: nas
base_path: /volume1/docker   # 默认路径是符号链接的设备写真实路径

实际同步目标 {base_path}/{服务名}。

sync_exclude（可选）

rsync 排除的目录名列表（仅目录名）。默认已排除 data、_data。 子级重新定义时整体替换父级列表（非追加）：

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

示例

# 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/ 内（其外的项目文件不扫描）