# `_config.yaml` 配置参考

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

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

## 放置位置（两种布局）

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

项目布局示例：

```yaml
# .pouch/deployer/_config.yaml — 三个环境共享
node: my-vps
base_path: /srv/apps

# .pouch/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` |
| 个别覆盖 | 子目录只写差异字段 |
| 项目三环境同主机 | `.pouch/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/` 段
- 项目环境布局：位于部署根 `.pouch/deployer/` 内（其外的项目文件不扫描）