Remote Docker Compose
Overview
在远程 Linux 服务器上完成一次标准化的 Docker 部署：SSH 登录 → 建目录 → 拉取镜像 → 写 docker-compose.yml（配置与数据外挂到宿主机）→ docker compose up -d → 验证。
本 skill 是流程与规矩，不是一份写死参数的部署脚本。目标服务器的连接信息、要部署的镜像名称/地址、目录、端口、密钥等一律不得固定在 skill 中，必须每次从当前用户输入或上下文中解析后确定。
三条硬性规矩（不可违反）
- 参数不固定 / 只从输入或上下文解析。 服务器连接信息与镜像名称/地址永远不写进本 skill。上下文缺失就按第 2 条询问，禁止臆造或用占位符直接执行。
- 执行前必须信息校验，缺失则一问一答。 动手前先检查①服务器连接信息、②镜像名称或地址是否存在。任一缺失，就用提问工具（
AskUserQuestion）一次只问一个问题，逐项补齐（server → 镜像 → 目录 → 端口 → 凭据 → 卷/环境变量）。不要在一段话里堆多个问题。 - 先出方案、用户确认后再执行。 信息齐了也不许直接跑。先产出一份安装方案 + 相关配置（目录结构、
docker-compose.yml内容、配置文件内容、将执行的命令）给用户确认。只有用户明确表示"确认/继续/执行"后，才登录服务器动手。未经确认，绝不执行任何会改变服务器状态的命令（拉镜像、写文件、起容器）。
> 记住：读操作（如探测 docker 版本）可在方案阶段进行，但任何写操作/状态变更都必须等到确认之后。
文件布局硬规矩（env 文件位置，不可违反）
.env/ secrets 文件必须放在config/目录下。 所有敏感项（密码、密钥、token）写入<target_dir>/config/<app>.env（如config/redis.env、config/postgres.env），严禁放在项目根目录。docker-compose.yml 用env_file: - ./config/<app>.env引入。好处：secrets 与应用配置、compose 文件、数据目录分层清晰，且可整体chmod 600 config/*.env收紧权限。
> ⚠️ docker compose 变量替换的坑：compose 文件里若用 ${VAR} 引用某个值（例如某些镜像把密码写进 command 参数），该替换只读取项目根目录的 .env，不会读取 env_file 指向的 config/<app>.env。因此：
> - 优先让应用进程直接读取 env_file 注入的环境变量（绝大多数官方镜像支持 REDIS_PASSWORD / POSTGRES_PASSWORD 等），compose 内联不要写值；
> - 若确实必须在 compose 内引用该值，改用「应用配置文件读取 env」或「方案里显式说明此限制」等方式解决，不要为图省事把 secrets 放回根目录 .env。
SSH 通道硬规矩（优先使用 ssh-remote-connection）
- SSH 远程连接优先调用
ssh-remote-connectionskill。 所有需要登录服务器执行的动作（预检、建目录、拉镜像、写文件、compose up、验证），优先用ssh-remote-connectionskill 的scripts/connect.sh完成，不要在 remote-docker-compose 内自己拼原生ssh/sshpass命令。仅当该 skill 不可用、或连接参数无法映射到其SSH_*变量时，才退回references/execution-mechanics.md的原生 ssh 通道兜底。
调用约定：
- 执行前先加载 ssh-remote-connection skill；
- 用本次解析出的连接参数（第 1 条：来自用户输入/上下文，不写死）注入环境变量：SSH_HOST / SSH_USER / SSH_PORT（默认 22 可省略）/ SSH_AUTH_METHOD（key|password|auto）/ SSH_KEY_PATH / SSH_PASSWORD；
- 远程命令统一走 scripts/connect.sh "<远程命令>"；需先进入部署目录时设 SERVER_PROJECT_PATH=<target_dir>，或在命令内 cd <target_dir> && ...；
- 写文件（base64 回写）也通过该通道执行，命令形态见 references/execution-mechanics.md。
需要解析的输入
A. 服务器连接信息
| 字段 | 说明 | 缺失时 |
|---|---|---|
| host | IP 或域名 | 必问 |
| user | SSH 用户名 | 必问 |
| port | SSH 端口 | 默认 22，可推断 |
| auth | 认证方式：密钥路径 或 密码 | 必确认其一 |
B. 部署描述
| 字段 | 说明 | 缺失时 |
|---|---|---|
| image | 镜像名称/地址（含 registry 与 tag，如 registry/ns/name:tag） |
必问 |
| target_dir | 宿主机目标目录（如 /root/<app>） |
建议问，缺省用 /<user>/<app> 需说明 |
| container_name | 容器名 | 可从镜像名推断 |
| ports | 端口映射 | 建议问 |
| config | 需要外挂的配置文件与内容 | 建议问 |
| data | 数据持久化目录 | 建议问（默认同名 data 子目录） |
| env/secret | 环境变量、密码等（必须写入 <target_dir>/config/<app>.env） |
涉及密码必问或明示默认值 |
| restart | 重启策略 | 默认 unless-stopped |
Workflow
Step 0 — 解析（不提问）
从用户本轮消息与上下文里抽取 A、B 两组字段。能推断的（如 port=22、container_name、restart）先补默认值并标注"用了默认值，可改"。
Step 1 — 校验 + 一问一答
对照上面两张表检查缺口。逐个用 AskUserQuestion 询问缺失的关键项（一次一个问题，选项化，推荐项放第一并标注推荐）。凭据类（密码/密钥路径）如用户未给，明确问；不要让用户在一轮里回答多个问题。
Step 2 — 生成安装方案与配置，交用户确认（关键门禁）
按 references/install-plan-template.md 产出一份中文方案，至少包含：
- 服务器与镜像概要
- 宿主机目录结构（如 <target_dir>/{config,data}）
- 将写入的文件完整内容：docker-compose.yml、各配置文件、env 文件
- 将执行的命令清单（建目录 → 拉镜像 → 写文件 → compose up → 验证）
- 风险与待澄清项（如默认密码需修改、端口是否占用、数据目录是否会被覆盖、pg_hba 等来源限制）
然后停下等待用户确认。用户未明确同意前，不得进入 Step 3。
Step 3 — 执行（仅确认后）
- 预检（只读）：
docker --version、docker compose version、目标目录是否存在、端口是否占用。 - 建目录：
mkdir -p <target_dir>/config <target_dir>/data。 - 拉镜像：
docker pull <image>,如果拉取失败立即停止、回报并给出排查命令。 - 写文件：用 base64 回写避免引号/heredoc 问题（见
references/execution-mechanics.md）。 - 启动：
cd <target_dir> && docker compose up -d。 - 若镜像数据目录要求特定属主（如 postgres alpine 的 uid 70），在启动前
chown数据目录。
Step 4 — 验证与回报
docker compose ps、docker ps --filter name=<container>- 端口监听：
ss -ltnp | grep <port> docker logs --tail 50 <container>确认就绪- 回报：实际路径、文件清单、容器状态、对外端口，以及需要用户跟进的点（改密码、收紧来源 IP 等）。
Resources
ssh-remote-connectionskill（兄弟 skill）— SSH 通道的优先选择：用它的scripts/connect.sh执行所有远程命令，自动处理密钥/密码认证、known_hosts信任与跨平台差异。remote-docker-compose 自身不重复造 SSH 轮子。references/execution-mechanics.md— SSH 执行机制（优先connect.sh、原生 ssh 兜底、密钥/密码认证、base64 回写、预检与验证命令、Windows 环境注意事项）。执行阶段必读。references/install-plan-template.md— Step 2 交付给用户确认的安装方案模板，按其结构产出。scripts/ssh_exec.py— 无第三方依赖的 SSH 执行助手：check验证连通、run执行命令、put回写文件（base64）。参数可用命令行或环境变量（SSH_HOST/SSH_USER/SSH_PORT/SSH_KEY_PATH/SSH_PASSWORD）。assets/docker-compose.template.yml— 通用 compose 模板（占位符形式，不含任何具体镜像地址），按实际部署填值后作为方案的一部分展示给用户。
