docker-compose

Docker Compose

在整个 Compose 生命周期中使用此技能：对应用程序建模、验证解析后的配置、启动或更新服务、检查运行时状态并诊断故障。优先采用当前的 Compose 规范。创建新文件时，不要添加顶层 version 键：它已过时，也不会选择架构版本。

操作流程

1. 发现 Compose 文件、项目目录、环境文件、配置文件、外部资源，以及任务属于开发、CI、预发布还是生产环境。
2. 建模应用程序：使用服务、用于持久化状态的命名卷、用于隔离的显式网络、用于敏感文件的机密，以及用于可选服务的配置文件。
3. 运行前解析：

   docker compose -f compose.yaml config --quiet
   docker compose -f compose.yaml config
   docker compose -f compose.yaml config --services
   

4. 操作时使用范围最小的命令：up -d SERVICE、restart SERVICE、run --rm SERVICE COMMAND 或 exec SERVICE COMMAND。除非有意删除数据并已确认，否则避免使用 down -v。
5. 验证：检查 ps、健康状态、日志、容器内检查，以及适用时对外发布的端点。
6. 按顺序诊断：解析后的模型 → 容器状态 → 日志 → 健康检查 → 网络成员关系／DNS → 挂载／权限 → 镜像／构建架构 → 主机资源。

决策规则

• depends_on 控制创建顺序，不保证就绪状态。使用真正的 healthcheck 和 condition: service_healthy；对迁移或作业使用 service_completed_successfully。不要将 sleep 用作就绪判断逻辑。
• 容器通过服务名称和容器端口（db:5432）访问同级服务，而不是通过主机发布的端口或容器 IP。
• 简单项目使用默认网络。使用独立网络隔离不同层；对没有外部网关的网络使用 internal: true；只有在项目外部创建网络时，才使用显式命名且设置了 external: true 的网络。
• 开发期间使用绑定挂载挂载源代码／配置，使用命名卷保存状态，并对不可变输入使用只读挂载。注意主机路径挂载可能因平台而异。
• 将凭据存放在 Compose 机密或外部机密管理器中，不要放在镜像、Git 或普通环境变量中。仅向需要相应机密的服务授权。Compose 机密会挂载到 /run/secrets/<name>。
• 使用配置文件启用调试、迁移、可观测性或 GPU 工作负载等可选工具。核心服务不应关联任何配置文件。
• 明确解析插值。Shell 变量优先于 --env-file，而 --env-file 优先于项目 .env；必填值使用 ${REQUIRED:?explain}，字面美元符号使用 $$。例如，如果必须由容器 Shell 而非 Compose 展开变量，请写成 test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"]。使用 docker compose config --environment 检查。
• 合并多个文件时，后续文件会应用于基础文件。相对路径基于第一个／基础文件解析。使用 docker compose config 检查结果；如果常规合并行为不符合预期，请使用 !reset 或 !override。
• Compose Watch 适用于从本地源代码构建的服务。对支持热重载的源代码使用 sync，对配置使用 sync+restart，对依赖项或镜像更改使用 rebuild。容器用户必须能够写入目标路径。
• 将 deploy 字段视为依实现而定。请验证目标 Compose 实现会强制执行哪些设置；该规范明确允许部分支持。

快速命令卡

docker compose version
docker compose config --quiet
docker compose up -d --build
docker compose ps
docker compose logs -f --tail=100 SERVICE
docker compose exec SERVICE COMMAND
docker compose run --rm SERVICE COMMAND
docker compose restart SERVICE
docker compose stop
docker compose down                    # preserves named volumes
docker compose down --remove-orphans
docker compose pull && docker compose up -d
docker compose --profile debug up -d
docker compose up --watch
docker compose port SERVICE CONTAINER_PORT
docker network inspect PROJECT_default
docker volume inspect PROJECT_VOLUME

高价值默认设置

• 当 compose.yaml 旁边存在 compose.override.yaml，且未提供 -f 文件时，Compose 会自动加载该覆盖文件；用于生产环境组合时，请显式指定 -f 文件。
• 破坏性 CI 闸门： 在 docker compose -p ci-${CI_JOB_ID:?CI_JOB_ID is required} config --services 确认项目名称已隔离之前，绝不要运行 down --volumes；在共享环境中，除非明确需要操作确切的数据范围，否则不要使用 --volumes。
• 将 deploy 资源和放置字段视为依赖目标环境的设置：渲染后的字段可能有效，但本地实现可能会忽略它。请在运行时验证是否生效。

基础/开发/生产命令矩阵

# Base or default development override
docker compose config --quiet
docker compose up --watch

# Explicit production model
IMAGE_TAG=release-1 docker compose -f compose.yaml -f compose.prod.yaml config --quiet
IMAGE_TAG=release-1 docker compose -f compose.yaml -f compose.prod.yaml up -d

# Optional tooling
docker compose --profile debug up -d

默认的 compose.override.yaml 会自动加载；生产环境覆盖文件必须显式选择。

渲染后的配置不等于运行时验证。 config 可以确认密钥声明、资源限制或健康检查是否存在，但只有运行时检查才能证明密钥文件已挂载、健康检查已通过，或目标实现已强制执行 deploy 限制。请使用 exec、ps、inspect，并在目标主机上测量实际行为进行验证。

参考资料导航

加载时机	参考资料
启动项目或选择基本组件	references/01-model-and-file-design.md
依赖项、健康检查、关闭或作业	references/02-lifecycle-and-health.md
DNS、端口、网络、卷或持久化	references/03-networking-and-storage.md
.env、插值、配置文件或覆盖文件	references/04-configuration-and-overrides.md
Watch、构建、CI 或生产运维	references/05-development-and-production.md
密钥、最小权限或供应链问题	references/06-security.md
故障需要系统化排查流程	references/07-troubleshooting.md
CLI 命令或字段查询	references/08-command-playbook.md
源覆盖范围和时效性检查	references/00-source-index.md

随附文件

• templates/：可移植的基础、开发、生产、环境和密钥文件示例。
• assets/project-review-checklist.md：交接和部署前审查清单。
• scripts/compose-doctor.sh：确定性验证和运行时诊断，支持文本或 JSON 输出。

故障边界

• config --quiet 只能证明模型解析成功，不能证明镜像已拉取、服务已启动或应用正确运行。
• 容器正在运行不代表服务已就绪。健康检查通过也不代表端到端验证已完成。
• docker compose down 会移除项目容器和网络；通常会保留命名卷。down -v 具有破坏性。

不适用场景

对于 Kubernetes、Swarm 调度或其他平台的部署控制器，请使用相应编排器专用的技能。Compose 可以描述部分部署概念，但不能替代该平台的运维 API。