141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# `_config.yaml` 配置参考
|
||
|
||
`_config.yaml` 供 **Compose 轨道**脚本解析，决定同步目标与排除规则。可放在**服务目录、部署根或其任意祖先目录**；子目录中的字段覆盖父目录（继承合并）。
|
||
|
||
Argo CD 轨道用独立文件 `.skiff/deployer/argocd.yaml`，字段见 [argocd.md](argocd.md)。
|
||
不要把 `argocd:` 嵌进本文件（脚本解析器不支持嵌套映射）。
|
||
|
||
## 放置位置（两种布局）
|
||
|
||
| 布局 | 部署根 | `_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/` 内（其外的项目文件不扫描）
|