115 lines
3.7 KiB
Markdown
115 lines
3.7 KiB
Markdown
# Composer
|
||
|
||
多租户 Docker Compose 编排工具。扫描 `users/` 下的用户目录，校验每个用户的 `compose.yml`，生成注入网络配置的快照，然后启动所有服务。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
<root>/
|
||
├── users/
|
||
│ ├── 10-alice/ # 优先级-用户名
|
||
│ │ ├── compose.yml # 必需
|
||
│ │ ├── .env # 可选（明文）
|
||
│ │ ├── .env.gpg # 可选（加密，二选一即可）
|
||
│ │ ├── app/
|
||
│ │ │ └── Dockerfile
|
||
│ │ └── ...
|
||
│ └── 20-bob/
|
||
│ └── ...
|
||
└── snapshots/ # 自动生成（每次覆盖）
|
||
├── 10-alice/
|
||
│ └── compose.yml # 已注入网络配置的版本
|
||
└── 20-bob/
|
||
```
|
||
|
||
- 目录名格式：`<数字优先级>-<用户名>`
|
||
- 用户名：`[a-z0-9]+`
|
||
- 优先级数字越小越先处理
|
||
|
||
## CLI 参数
|
||
|
||
| 参数 | 必需 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `--root` | | `.` | 项目根目录 |
|
||
| `--network` | | `cloud` | 注入到 services 的外部网络名 |
|
||
| `--volume-parent` | ✓ | | 卷挂载路径白名单前缀 |
|
||
| `--dry` | | `false` | 只打印操作，不实际执行 |
|
||
|
||
## compose.yml 约束
|
||
|
||
### 允许的顶层字段
|
||
|
||
只有 `services` 被识别。如果 YAML 中有 `networks`、`volumes`、`version` 等额外顶层键，会触发 **WARN** —— 它们会被 Pydantic 静默丢弃，可能与网络注入冲突。
|
||
|
||
### 允许的 service 字段
|
||
|
||
`build` `image` `volumes` `command` `depends_on` `entrypoint` `env_file` `environment`
|
||
|
||
`build` 可以是字符串（指向含 Dockerfile 的目录）或对象 `{context, dockerfile, args}`。其他键同样触发 WARN。
|
||
|
||
### 卷约束
|
||
|
||
所有 volume 的宿主机路径必须以 `--volume-parent` 为前缀，且只允许 `ro` 模式。
|
||
|
||
### 环境文件
|
||
|
||
- 支持明文 `.env` 或 GPG 加密 `.env.gpg`
|
||
- 只校验明文文件的内容格式（`KEY=value` 或 `export KEY=value`）
|
||
- 如果只存在 `.env.gpg` 则跳过内容校验
|
||
|
||
## 运行流程
|
||
|
||
```
|
||
1. 扫描 users/ → 解析优先级和用户名
|
||
2. 加载每个 compose.yml → Pydantic 校验
|
||
3. 检测注入干扰字段（WARN）
|
||
4. 校验 service 引用、Dockerfile 存在性、卷路径、env_file
|
||
5. ── 有错则退出 ──
|
||
6. 为每个用户创建 snapshots/<prio>-<name>/
|
||
7. 拷贝所有文件：compose.yml 注入网络配置，.gpg 文件解密
|
||
8. ── 快照失败则退出 ──
|
||
9. 在每个快照目录执行 docker compose up --remove-orphans --build --detach
|
||
```
|
||
|
||
## 网络注入
|
||
|
||
快照中的 `compose.yml` 会被注入：
|
||
|
||
```yaml
|
||
networks:
|
||
cloud: # --network 参数值
|
||
external: true
|
||
alice: # 用户名
|
||
name: alice
|
||
|
||
services:
|
||
app:
|
||
networks: [cloud, alice]
|
||
```
|
||
|
||
每个 service 的 `networks` 会被**覆盖**为 `[<network>, <username>]`。
|
||
|
||
## GPG 解密
|
||
|
||
快照拷贝时，`.gpg` 后缀的文件会调用系统 `gpg --decrypt --batch` 解密，输出到去掉 `.gpg` 后缀的路径。原 `.gpg` 文件不进入快照。
|
||
|
||
要求运行环境已配置好 GPG 密钥，且能无交互解密。
|
||
|
||
## Dry-run 模式
|
||
|
||
`--dry` 执行全部校验，但只打印操作摘要：
|
||
|
||
```
|
||
[dry] would snapshot users/10-alice -> snapshots/10-alice
|
||
[dry] inject networks: .networks.cloud.external=true, ...
|
||
[dry] would run: docker compose -f snapshots/10-alice/compose.yml up ...
|
||
```
|
||
|
||
不创建目录、不写文件、不解密、不启动容器。
|
||
|
||
## 错误处理
|
||
|
||
- **校验阶段有错** → 打印错误并 `exit 1`（不创建快照）
|
||
- **快照创建失败**（单个用户）→ 标记错误，跳过该用户，继续处理其他用户；全部完成后 `exit 1`
|
||
- **compose up 失败**（单个用户）→ 标记错误，继续启动其他用户；全部完成后 `exit 1`
|