docker-compose-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Compose Patterns

Docker Compose 模式

Overview

概述

This skill provides rules for creating, reviewing, and debugging Docker Compose configurations. Use it when the main artifact is

compose.yaml

compose.override.yaml

and the task is about service wiring rather than image-build internals.

此技能提供创建、审查和调试 Docker Compose 配置的规则。当主要产物是

compose.yaml

或

compose.override.yaml

且任务涉及服务连接而非镜像构建内部细节时使用。

When to use this skill

何时使用此技能

Activate this skill when:

Creating a new
```
compose.yaml
```
for a project
Adding or modifying services in an existing Compose file
Setting up development overrides with
```
compose.override.yaml
```
Debugging service startup ordering or connectivity issues

在以下情况激活此技能：

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

Do not use this skill when

不要使用此技能的情况

Do not use this skill when:

The project has no Docker setup yet and the main need is an initial scaffold
The main task is writing or optimizing a
```
Dockerfile
```
The main task is improving build caching, image size, or runtime user configuration

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

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

Core guidance

核心指导

File naming

文件命名

Use

compose.yaml

as the canonical filename. Do not use

docker-compose.yml

docker-compose.yaml

— those are legacy names.

使用

compose.yaml

作为规范文件名。不要使用

docker-compose.yml

或

docker-compose.yaml

—— 这些是旧名称。

Service definitions

服务定义

Give services clear, lowercase names that reflect their role:
```
web
```
,
```
db
```
,
```
cache
```
,
```
worker
```
.
Always pin image tags to a specific version. Never use
```
latest
```
or omit the tag.
Set
```
restart: unless-stopped
```
for long-running infrastructure services and non-development deployments.
Add
```
container_name
```
only when external tools need a predictable name. Otherwise, let Compose generate names.

为服务指定清晰的小写名称，反映其角色：
```
web
```
、
```
db
```
、
```
cache
```
、
```
worker
```
。
始终将镜像标签固定到特定版本。切勿使用
```
latest
```
或省略标签。
对于长期运行的基础设施服务和非开发部署，设置
```
restart: unless-stopped
```
。
仅在外部工具需要可预测名称时添加
```
container_name
```
。否则，让 Compose 生成名称。

Dependency modeling

依赖建模

Use
```
depends_on
```
with
```
condition: service_healthy
```
for services that must be ready before dependents start.
Every service listed in
```
depends_on
```
with a health condition must have a
```
healthcheck
```
defined.
Do not rely on
```
depends_on
```
without conditions — it only guarantees container start, not readiness.

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

Health checks

健康检查

Always add a
```
healthcheck
```
to database services (Postgres, MySQL, Redis, MongoDB).
Use the service's native client tool for health checks when available (e.g.,
```
pg_isready
```
,
```
redis-cli ping
```
,
```
mysqladmin ping
```
).

Set reasonable

interval

timeout

retries

, and

start_period

values. Start with:

interval: 5s

timeout: 3s

retries: 3

start_period: 10s

始终为数据库服务（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

。

Health checks for distroless or scratch images

针对 distroless 或 scratch 镜像的健康检查

Distroless, scratch-based, and hardened images contain no shell, curl, or wget. Do not bake tools into these images — that defeats their purpose. Instead, use a healthcheck sidecar that shares the application's network namespace:

yaml

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
    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

Key points:

The sidecar must stay alive with
```
entrypoint: ["sleep", "infinity"]
```
so Compose can execute the healthcheck inside it.
```
network_mode: "service:api"
```
makes
```
localhost
```
inside the sidecar resolve to the api container's loopback — no extra networking needed.
Keep the sidecar lightweight with a resource limit (32MB is sufficient for curl).
Services that depend on
```
api
```
being ready should reference the sidecar, not the api directly:

yaml

  worker:
    depends_on:
      api-health:
        condition: service_healthy

Distroless、基于 scratch 和加固镜像不包含 shell、curl 或 wget。不要将工具嵌入这些镜像 —— 那会破坏其目的。相反，使用共享应用网络命名空间的 healthcheck 边车：

yaml

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
    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

关键点：

边车必须通过
```
entrypoint: ["sleep", "infinity"]
```
保持存活，以便 Compose 在其中执行健康检查。
```
network_mode: "service:api"
```
使边车内的
```
localhost
```
解析为 api 容器的回环地址 —— 无需额外网络配置。
通过资源限制保持边车轻量（32MB 对 curl 足够）。
依赖
```
api
```
就绪的服务应引用边车，而非直接引用 api：

yaml

  worker:
    depends_on:
      api-health:
        condition: service_healthy

Volumes

卷

Use named volumes for data that must persist across container recreations (database data, uploaded files).
Use bind mounts only for development-time source code syncing.
Define all named volumes in the top-level
```
volumes:
```
key.
Do not mount the Docker socket unless the service genuinely requires it.

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

Networks

网络

For single-application stacks, the default network is sufficient. Do not create custom networks unless you need isolation between service groups.
When creating custom networks, prefer bridge driver and give networks descriptive names.
Use the top-level
```
networks:
```
key to define all custom networks.

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

Environment variables

环境变量

Use
```
environment:
```
for non-sensitive values that are few in number.
Use
```
env_file:
```
pointing to a
```
.env
```
file for longer lists of variables.
Never hardcode secrets (passwords, API keys) directly in
```
compose.yaml
```
. Use
```
env_file:
```
or Docker secrets.
When defaults are needed in the
```
environment:
```
block for local development, use variable substitution with fallbacks:
```
${DB_PASSWORD:-postgres}
```
. Never write bare plaintext values for password fields.
Add
```
.env
```
to
```
.gitignore
```
.

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

Development overrides

开发覆盖

Use
```
compose.override.yaml
```
for development-only settings. Compose loads it automatically alongside
```
compose.yaml
```
.
Put bind mounts for source code, debug ports, and development environment variables in the override file.
Use
```
develop.watch
```
for file-syncing and auto-rebuild in development when supported.
Keep production-oriented settings in the base
```
compose.yaml
```
and override only what changes for development.

仅对开发设置使用
```
compose.override.yaml
```
。Compose 会自动将其与
```
compose.yaml
```
一起加载。
在覆盖文件中放置源代码的绑定挂载、调试端口和开发环境变量。
在支持时使用
```
develop.watch
```
进行开发中的文件同步和自动重建。
将面向生产的设置保留在基础
```
compose.yaml
```
中，仅覆盖开发所需更改的内容。

Compose Watch

Prefer
```
develop.watch
```
over manual bind mounts for development workflows.
Use
```
action: sync
```
for files that should be copied into the container on change (source code).
Use
```
action: rebuild
```
for files that require a full image rebuild (dependency files like
```
package.json
```
,
```
requirements.txt
```
).
Use
```
action: sync+restart
```
for configuration files that need a process restart.

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

Destructive commands

破坏性命令

Some Compose commands delete data irreversibly. Before running any of the following, state exactly which data will be deleted and get explicit confirmation from the user — do not run them as a side effect of debugging, restarting, or "cleaning up" a stack:

```
docker compose down -v
```
/
```
docker compose down --volumes
```
— deletes named volumes, including database data.
```
docker volume rm
```
/
```
docker volume prune
```
run against a Compose project's volumes — deletes volumes directly. For the standalone case (no Compose project in play), see
```
docker-destructive-guardrails
```
instead. A volume referenced via
```
external: true
```
isn't managed by the Compose project either (
```
down -v
```
won't touch it) — treat it as the standalone case too: run
```
docker volume rm
```
without
```
-f
```
first, and get explicit confirmation before deleting it.
```
docker compose rm -v
```
— deletes anonymous volumes attached to removed containers.

If the goal is only to restart services or reclaim containers/networks, use

docker compose down

(no

-v

) or

docker compose restart

instead — these leave named volumes intact.

某些 Compose 命令会不可逆地删除数据。在运行以下任何命令之前，明确说明将删除哪些数据并获得用户的明确确认 —— 不要将其作为调试、重启或“清理”技术栈的副作用而运行：

docker compose down -v

docker compose down --volumes

—— 删除命名卷，包括数据库数据。

```
docker volume rm
```
/
```
docker volume prune
```
针对 Compose 项目的卷运行 —— 直接删除卷。对于独立情况（不涉及 Compose 项目），请改用
```
docker-destructive-guardrails
```
。通过
```
external: true
```
引用的卷也不由 Compose 项目管理（
```
down -v
```
不会触碰它）—— 也将其视为独立情况：先不带
```
-f
```
运行
```
docker volume rm
```
，并在删除前获得明确确认。
```
docker compose rm -v
```
—— 删除附加到已移除容器的匿名卷。

如果目标只是重启服务或回收容器/网络，使用

docker compose down

（不加

-v

）或

docker compose restart

代替 —— 这些命令会保留命名卷。

Related skills

References

参考

```
references/service-dependencies.md
```
— Detailed guidance on
```
depends_on
```
, health check patterns for common databases, and startup ordering strategies.
```
references/volumes-and-networks.md
```
— Patterns for volume mounts, named volumes, bind mounts, and network configuration.

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

Assets

资源

```
assets/compose-web-app.yaml
```
— Complete multi-service web app (app + Postgres + Redis) with health checks, dependencies, and named volumes.
```
assets/compose-dev-override.yaml
```
— Development override showing bind mounts, debug ports, and Compose Watch configuration.
```
assets/bad-vs-good.md
```
— Before/after comparisons of common Compose mistakes and their fixes.

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

Scripts

脚本

scripts/verify-compose.sh
— Validates
```
compose.yaml
```
with
```
docker compose config --quiet
```
, without printing resolved configuration.
bash
```
bash scripts/verify-compose.sh [--help]
```
Exit status is
```
0
```
when the Compose configuration is valid or help is requested, the non-zero status from
```
docker compose config --quiet
```
when validation fails, and
```
2
```
for invalid arguments. Plain
```
docker compose config
```
can expose interpolated and
```
env_file
```
credentials in tool output or logs; use quiet validation by default. Compose warnings and errors are still emitted and may contain sensitive details.

scripts/verify-compose.sh
— 使用
```
docker compose config --quiet
```
验证
```
compose.yaml
```
，不打印解析后的配置。
bash
```
bash scripts/verify-compose.sh [--help]
```
当 Compose 配置有效或请求帮助时退出状态为
```
0
```
，验证失败时返回
```
docker compose config --quiet
```
的非零状态，参数无效时返回
```
2
```
。普通的
```
docker compose config
```
可能会在工具输出或日志中暴露插值和
```
env_file
```
凭据；默认使用静默验证。Compose 警告和错误仍会输出，可能包含敏感细节。

Checks

检查

```
checks/verification.md
```
— Detailed verification runbook for manual review.

```
checks/verification.md
```
— 用于手动审查的详细验证手册。

docker-compose-patterns

Original

Translation

Docker Compose Patterns

Docker Compose 模式

Overview

概述

When to use this skill

何时使用此技能

Do not use this skill when

不要使用此技能的情况

Core guidance

核心指导

File naming

文件命名

Service definitions

服务定义

Dependency modeling

依赖建模

Health checks

健康检查

Health checks for distroless or scratch images

针对 distroless 或 scratch 镜像的健康检查

Volumes

卷

Networks

网络

Environment variables

环境变量

Development overrides

开发覆盖

Compose Watch

Compose Watch

Destructive commands

破坏性命令

Related skills

相关技能

References

参考

Assets

资源

Scripts

脚本

Checks

检查