docker-compose-patterns

Docker Compose 模式

概述

此技能提供创建、审查和调试 Docker Compose 配置的规则。当主要产物是 compose.yaml 或 compose.override.yaml，且任务涉及服务连接而非镜像构建细节时，请使用此技能。

何时使用此技能

在以下情况下启用此技能：

• 为项目创建新的 compose.yaml
• 在现有 Compose 文件中添加或修改服务
• 使用 compose.override.yaml 设置开发环境覆盖配置
• 调试服务启动顺序或连接问题

何时不使用此技能

在以下情况下不要使用此技能：

• 项目尚无 Docker 配置，主要需求是搭建初始框架
• 主要任务是编写或优化 Dockerfile
• 主要任务是改进构建缓存、镜像大小或运行时用户配置

核心指导

文件命名

使用 compose.yaml 作为规范文件名。不要使用 docker-compose.yml 或 docker-compose.yaml——这些是旧版名称。

服务定义

• 为服务指定清晰的小写名称，以体现其用途：web、db、cache、worker。
• 始终将镜像标签固定到特定版本。绝不要使用 latest 或省略标签。
• 对长期运行的基础设施服务和非开发部署设置 restart: unless-stopped。
• 仅当外部工具需要可预测的名称时才添加 container_name。否则，让 Compose 自动生成名称。

依赖关系建模

• 对于必须在依赖服务启动前就绪的服务，使用带有 condition: service_healthy 的 depends_on。
• 在 depends_on 中列出且带有健康条件的每个服务都必须定义 healthcheck。
• 不要依赖不带条件的 depends_on——它只能保证容器启动，不能保证服务就绪。

健康检查

• 始终为数据库服务（Postgres、MySQL、Redis、MongoDB）添加 healthcheck。
• 如有可用的原生客户端工具，使用该工具执行健康检查（例如 pg_isready、redis-cli ping、mysqladmin ping）。
• 为 interval、timeout、retries 和 start_period 设置合理的值。可从以下值开始：interval: 5s、timeout: 3s、retries: 3、start_period: 10s。

Distroless 或 scratch 镜像的健康检查

Distroless、基于 scratch 的镜像和经过加固的镜像不包含 shell、curl 或 wget。不要将工具打包进这些镜像——这会违背其设计目的。请改用与应用共享网络命名空间的健康检查 sidecar：

services:
  api:
    build:
      context: .
      target: runtime          # distroless / hardened image
    ports:
      - "8080:8080"
    # No healthcheck here — the image has no tools to run one

  api-health:
    image: curlimages/curl:8.22.0
    network_mode: "service:api"   # shares api's localhost
    entrypoint: ["sleep", "infinity"]  # keep sidecar alive for healthcheck
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 45s
    deploy:
      resources:
        limits:
          memory: 32M

要点：

• sidecar 必须通过 entrypoint: ["sleep", "infinity"] 保持运行，以便 Compose 能在其中执行健康检查。
• network_mode: "service:api" 会使 sidecar 内的 localhost 指向 api 容器的回环地址，无需额外网络配置。
• 使用资源限制让 sidecar 保持轻量（curl 使用 32MB 就足够）。
• 依赖 api 就绪的服务应引用sidecar，而不是直接引用 api：

  worker:
    depends_on:
      api-health:
        condition: service_healthy

卷

• 对需要在容器重建后保留的数据（数据库数据、上传的文件）使用命名卷。
• 仅在开发期间使用绑定挂载同步源代码。
• 在顶层 volumes: 键下定义所有命名卷。
• 除非服务确实需要，否则不要挂载 Docker socket。

网络

• 对于单应用堆栈，默认网络已足够。除非需要在服务组之间隔离，否则不要创建自定义网络。
• 创建自定义网络时，优先使用 bridge 驱动，并为网络指定描述性名称。
• 使用顶层 networks: 键定义所有自定义网络。

环境变量

• 对于数量较少的非敏感值，请使用 environment:。
• 对于较长的变量列表，请使用 env_file: 指向 .env 文件。
• 切勿在 compose.yaml 中直接硬编码机密信息（密码、API 密钥）。请使用 env_file: 或 Docker secrets。
• 如果需要在 environment: 块中为本地开发设置默认值，请使用带回退值的变量替换：${DB_PASSWORD:-postgres}。切勿在密码字段中直接填写明文值。
• 将 .env 添加到 .gitignore。

开发环境覆盖配置

• 使用 compose.override.yaml 设置仅用于开发环境的配置。Compose 会自动将其与 compose.yaml 一起加载。
• 在覆盖文件中添加源代码绑定挂载、调试端口和开发环境变量。
• 在支持的情况下，使用 develop.watch 在开发时同步文件并自动重新构建。
• 在基础 compose.yaml 中保留面向生产环境的配置，仅在覆盖文件中修改开发环境所需的部分。

Compose Watch

• 在开发工作流中，优先使用 develop.watch，而非手动绑定挂载。
• 对发生更改时应复制到容器中的文件（源代码），使用 action: sync。
• 对需要完整重建映像的文件（依赖文件，例如 package.json、requirements.txt），使用 action: rebuild。
• 对需要重启进程的配置文件，使用 action: sync+restart。

破坏性命令

部分 Compose 命令会不可逆地删除数据。在运行以下任何命令之前，请准确说明将删除哪些数据，并征得用户明确确认——切勿在调试、重启或“清理”堆栈时顺带运行这些命令：

• docker compose down -v / docker compose down --volumes — 删除命名卷，包括数据库数据。
• 对 Compose 项目的卷运行 docker volume rm / docker volume prune — 直接删除卷。对于独立场景（没有正在使用的 Compose 项目），请改用 docker-destructive-guardrails。通过 external: true 引用的卷也不归 Compose 项目管理（down -v 不会触及它）——同样按独立场景处理：先不带 -f 运行 docker volume rm，并在删除前征得用户明确确认。
• docker compose rm -v — 删除与已移除容器关联的匿名卷。

如果目的只是重启服务或回收容器／网络，请使用 docker compose down（不带 -v）或 docker compose restart——这些命令会保留命名卷。

相关技能

• 对于首次搭建 Docker 项目和创建基础文件，请使用 docker-project-foundations。
• 对于 Dockerfile 内部机制、构建缓存、多阶段构建和 .dockerignore，请使用 docker-build-strategies。
• 对于 Compose 之外的破坏性 Docker CLI 命令（docker system prune、docker rm -f、映像／网络／构建器清理、独立卷删除）以及破坏性命令防护措施的跨产品索引，请使用 docker-destructive-guardrails。

参考资料

• references/service-dependencies.md — 关于 depends_on、常见数据库的健康检查模式以及启动顺序策略的详细指南。
• references/volumes-and-networks.md — 卷挂载、命名卷、绑定挂载和网络配置模式。

资源文件

• assets/compose-web-app.yaml — 完整的多服务 Web 应用（应用 + Postgres + Redis），包含健康检查、依赖项和命名卷。
• assets/compose-dev-override.yaml — 开发环境覆盖配置示例，展示绑定挂载、调试端口和 Compose Watch 配置。
• assets/bad-vs-good.md — 常见 Compose 错误及其修正方法的前后对比。

脚本

• scripts/verify-compose.sh — 使用 docker compose config --quiet 验证当前目录中的 Compose 项目，不打印解析后的配置。请从项目根目录（包含 compose.yaml 的目录）运行，并将脚本路径解析为相对于此技能目录的路径：

  bash "<skill-dir>/scripts/verify-compose.sh" [--help]
  

  将 <skill-dir> 替换为包含此 SKILL.md 的文件夹的绝对路径；scripts/ 路径相对于该文件夹，而非项目目录。请勿先切换到技能目录：该脚本会验证当前目录中的 Compose 项目。如果无法解析技能目录，请直接运行 docker compose config --quiet。当 Compose 配置有效或请求了帮助时，退出状态为 0；验证失败时，退出状态为 docker compose config --quiet 返回的非零状态；参数无效时，退出状态为 2。普通的 docker compose config 可能会在工具输出或日志中暴露插值后的凭据和 env_file 中的凭据；默认使用安静模式进行验证。Compose 警告和错误仍会输出，其中可能包含敏感信息。

检查

• checks/verification.md — 用于人工审查的详细验证操作手册。