docker-compose

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Compose Skill

Docker Compose 技能文档

Installation

安装步骤

The skill invokes

docker compose

. Easiest: install Docker Desktop (includes Docker Engine + Compose):

Windows: Docker Desktop for Windows (WSL 2 or Hyper-V)
Mac: Docker Desktop for Mac (Apple Silicon or Intel)
Linux: Docker Desktop for Linux or Docker Engine + Compose plugin from Docker's repo

Verify:

docker compose version

本技能调用

docker compose

命令。最简单的方式是安装Docker Desktop（包含Docker Engine + Compose）：

Windows：Docker Desktop for Windows（支持WSL 2或Hyper-V）
Mac：Docker Desktop for Mac（支持Apple Silicon或Intel芯片）
Linux：Docker Desktop for Linux 或从Docker仓库安装Docker Engine + Compose插件

验证安装：

docker compose version

Cheat Sheet & Best Practices

速查表与最佳实践

Commands:

docker compose up -d

down

;

docker compose ps

logs -f <service>

;

docker compose exec <service> sh

;

docker compose build --no-cache

;

docker compose -f compose.prod.yaml config

— validate.

YAML: Use named volumes for DBs (

postgres_data:/var/lib/postgresql/data

). Use healthchecks (

healthcheck:

with

test

interval

timeout

retries

). One network default; reference services by name (e.g.

http://api:3000

). Use

env_file

environment

; keep secrets in

secrets:

Hacks:

-f compose.yaml -f override.yaml

merges files (later overrides). Use

--project-name

for isolation. Prefer

build: context: . dockerfile: Dockerfile

for dev; pin image tags in prod. Run

docker compose config

before

up

to catch errors.

常用命令：

docker compose up -d

down

；

docker compose ps

logs -f <service>

；

docker compose exec <service> sh

；

docker compose build --no-cache

；

docker compose -f compose.prod.yaml config

—— 验证配置。

YAML配置：为数据库使用命名卷（如

postgres_data:/var/lib/postgresql/data

）。配置健康检查（

healthcheck:

包含

test

、

interval

、

timeout

、

retries

参数）。默认使用单个网络；通过服务名称访问（例如

http://api:3000

）。使用

env_file

或

environment

配置环境变量；敏感信息存入

secrets:

。

实用技巧：

-f compose.yaml -f override.yaml

合并配置文件（后者覆盖前者）。使用

--project-name

实现环境隔离。开发环境优先使用

build: context: . dockerfile: Dockerfile

；生产环境固定镜像标签。启动前运行

docker compose config

排查错误。

Certifications & Training

认证与培训

Docker Certified Associate (DCA): Orchestration 25%, Image/Registry 20%, Install/Config 15%, Networking 15%, Security 15%, Storage 10%. Free: Official DCA Study Guide, Coursera DCA Prep (audit). Skill data: Compose YAML (services, volumes, networks, healthchecks), CLI (up/down/ps/logs/exec).

Docker认证助理（DCA）：编排占25%，镜像/仓库占20%，安装/配置占15%，网络占15%，安全占15%，存储占10%。免费资源：官方DCA学习指南，Coursera DCA备考课程（可旁听）。技能覆盖内容：Compose YAML（服务、卷、网络、健康检查），CLI命令（up/down/ps/logs/exec）。

Hooks & Workflows

钩子与工作流

Suggested hooks: Pre-up:

docker compose config

(validate). Post-down: optional cleanup. Use when devops or devops-troubleshooter is routed.

Workflows: Use with devops (primary), devops-troubleshooter (primary). Flow: validate compose → up/down/exec per task. See

operations/incident-response

for container debugging.

推荐钩子：启动前：

docker compose config

（验证配置）。停止后：可选清理操作。当路由到devops或devops-troubleshooter时触发。

工作流：与devops（主要）、devops-troubleshooter（主要）配合使用。流程：验证compose配置 → 根据任务执行up/down/exec操作。容器调试可参考

operations/incident-response

。

Overview

概述

This skill provides comprehensive Docker Compose management, enabling AI agents to orchestrate multi-container applications, manage services, inspect logs, and troubleshoot containerized environments with progressive disclosure for optimal context usage.

Context Savings: ~92% reduction

MCP Mode: ~25,000 tokens always loaded (multiple tools + schemas)
Skill Mode: ~700 tokens metadata + on-demand loading

本技能提供全面的Docker Compose管理能力，支持AI Agent编排多容器应用、管理服务、查看日志，并通过渐进式信息披露优化上下文使用，排查容器化环境问题。

上下文节省：约92%的缩减

MCP模式：始终加载约25,000个token（包含多个工具+ schema）
技能模式：仅加载约700个token的元数据+按需加载内容

When to Use

适用场景

Managing local development environments
Orchestrating multi-container applications
Debugging service connectivity and networking
Monitoring container logs and health
Building and updating service images
Testing containerized application stacks
Troubleshooting service failures
Managing application lifecycle (start, stop, restart)

管理本地开发环境
编排多容器应用
排查服务连通性与网络问题
监控容器日志与健康状态
构建与更新服务镜像
测试容器化应用栈
排查服务故障
管理应用生命周期（启动、停止、重启）

Requirements

前置要求

Docker Engine installed and running
Docker Compose V2 (
```
docker compose
```
plugin — V1
```
docker-compose
```
is end-of-life)

Valid

compose.yaml

(preferred) or

compose.yml

docker-compose.yml

in project

Appropriate permissions for Docker socket access

Docker Engine已安装并运行
Docker Compose V2（
```
docker compose
```
插件 —— V1
```
docker-compose
```
已停止维护）
项目中存在有效的
```
compose.yaml
```
（推荐）或
```
compose.yml
```
/
```
docker-compose.yml
```
文件
具备Docker套接字访问权限

Quick Reference

快速参考

bash

undefined

bash

undefined

List running services

列出运行中的服务

docker compose ps

View service logs

查看服务日志

docker compose logs <service>

Start services

启动服务

docker compose up -d

Stop services

停止服务

docker compose down

Rebuild services

重新构建服务

docker compose build

Execute command in container

在容器中执行命令

docker compose exec <service> <command>

Live development reloading (Compose Watch)

本地开发热重载（Compose Watch）

docker compose watch

Start with a profile active

激活指定配置文件启动

docker compose --profile debug up -d

Validate merged config

验证合并后的配置

docker compose config

undefined

docker compose config

undefined

2026 Feature Highlights

2026年功能亮点

compose.yaml — Canonical Filename

compose.yaml — 标准文件名

Docker Compose V2 prefers

compose.yaml

(and

compose.yml

) over the legacy

docker-compose.yml

. The

version:

top-level field is deprecated and should be omitted entirely in new files.

yaml

undefined

Docker Compose V2优先使用

compose.yaml

（和

compose.yml

），而非旧版的

docker-compose.yml

。顶层字段

version:

已弃用，新文件中应完全省略。

yaml

undefined

compose.yaml (preferred — no version: field needed)

compose.yaml （推荐格式 —— 无需version:字段）

services: web: build: . ports: - '8080:80' db: image: postgres:16-alpine environment: POSTGRES_PASSWORD: example volumes: - postgres_data:/var/lib/postgresql/data

volumes: postgres_data:

undefined

services: web: build: . ports: - '8080:80' db: image: postgres:16-alpine environment: POSTGRES_PASSWORD: example volumes: - postgres_data:/var/lib/postgresql/data

volumes: postgres_data:

undefined

Compose Watch — Live Development Reloading

Compose Watch — 本地开发热重载

Compose Watch (GA as of Compose 2.22+) replaces the manual rebuild-restart cycle during development. Configure a

develop.watch

block per service. Three actions are available:

Action	Behavior
`sync`	Instantly copies changed files into the running container
`rebuild`	Triggers `docker compose build` + recreates the container
`sync+restart`	Syncs files then restarts the container process (no full rebuild)

yaml

services:
  api:
    build: .
    ports:
      - '3000:3000'
    develop:
      watch:
        # Sync source instantly — no rebuild needed for interpreted code
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        # Rebuild when dependency manifest changes
        - action: rebuild
          path: package.json
        # Restart only when config changes
        - action: sync+restart
          path: ./config
          target: /app/config

Start with:

bash

undefined

Compose Watch（自Compose 2.22+起正式发布）替代了开发过程中手动重建-重启的循环。可在每个服务下配置

develop.watch

块，支持三种操作：

操作	行为描述
`sync`	即时将变更文件复制到运行中的容器内
`rebuild`	触发 `docker compose build` 并重新创建容器
`sync+restart`	同步文件后重启容器进程（无需完整重建）

yaml

services:
  api:
    build: .
    ports:
      - '3000:3000'
    develop:
      watch:
        # 即时同步源码 —— 解释型代码无需重建
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        # 依赖清单变更时触发重建
        - action: rebuild
          path: package.json
        # 配置变更时仅重启
        - action: sync+restart
          path: ./config
          target: /app/config

启动命令：

bash

undefined

Watch mode (keeps output in foreground)

监听模式（保持前台输出）

docker compose watch

Or combined with up

或与up命令结合使用

docker compose up --watch


**When to use each action:**

- `sync` — interpreted languages (Node.js, Python, Ruby) where the runtime picks up changes
- `sync+restart` — config or template files that require a process restart but not a full rebuild
- `rebuild` — dependency manifest changes (`package.json`, `requirements.txt`, `go.mod`)

docker compose up --watch


**各操作适用场景**：

- `sync` —— 解释型语言（Node.js、Python、Ruby），运行时可自动识别变更
- `sync+restart` —— 配置或模板文件变更，需重启进程但无需完整重建
- `rebuild` —— 依赖清单变更（`package.json`、`requirements.txt`、`go.mod`）

Profiles — Environment-Specific Services

配置文件（Profiles）—— 环境专属服务

Profiles allow a single

compose.yaml

to serve multiple environments. Services without a profile always start. Services with profiles only start when that profile is activated.

yaml

services:
  # Always starts — no profile
  api:
    build: .
    ports:
      - '3000:3000'
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

  # Only with --profile debug
  pgadmin:
    image: dpage/pgadmin4:latest
    profiles: ['debug']
    ports:
      - '5050:80'
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@admin.com
      PGADMIN_DEFAULT_PASSWORD: admin

  # Only with --profile monitoring
  prometheus:
    image: prom/prometheus:latest
    profiles: ['monitoring']
    ports:
      - '9090:9090'

  grafana:
    image: grafana/grafana:latest
    profiles: ['monitoring']
    ports:
      - '3001:3000'

volumes:
  db_data:

bash

undefined

配置文件允许单个

compose.yaml

适配多环境。无配置文件的服务始终启动，带配置文件的服务仅在激活对应配置文件时启动。

yaml

services:
  # 始终启动 —— 无配置文件
  api:
    build: .
    ports:
      - '3000:3000'
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

  # 仅在--profile debug时启动
  pgadmin:
    image: dpage/pgadmin4:latest
    profiles: ['debug']
    ports:
      - '5050:80'
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@admin.com
      PGADMIN_DEFAULT_PASSWORD: admin

  # 仅在--profile monitoring时启动
  prometheus:
    image: prom/prometheus:latest
    profiles: ['monitoring']
    ports:
      - '9090:9090'

  grafana:
    image: grafana/grafana:latest
    profiles: ['monitoring']
    ports:
      - '3001:3000'

volumes:
  db_data:

bash

undefined

Default: api + db only

默认：仅启动api + db

docker compose up -d

Debug: api + db + pgadmin

调试模式：启动api + db + pgadmin

docker compose --profile debug up -d

Monitoring: api + db + prometheus + grafana

监控模式：启动api + db + prometheus + grafana

docker compose --profile monitoring up -d

Multiple profiles

激活多个配置文件

docker compose --profile debug --profile monitoring up -d

Via environment variable

通过环境变量激活

COMPOSE_PROFILES=debug,monitoring docker compose up -d


**Profile naming rules:** `[a-zA-Z0-9][a-zA-Z0-9_.-]+` — lowercase kebab-case recommended.

COMPOSE_PROFILES=debug,monitoring docker compose up -d


**配置文件命名规则**：`[a-zA-Z0-9][a-zA-Z0-9_.-]+` —— 推荐使用小写短横线分隔格式。

Include — Composable Configs

Include — 可组合的配置

The

include

top-level key (introduced in Compose 2.20) allows you to split large compose files into modular, team-owned pieces. Each included file is loaded with its own project directory context, resolving relative paths correctly.

yaml

undefined

顶层键

include

（Compose 2.20+引入）允许将大型compose文件拆分为模块化、团队专属的片段。每个被包含的文件将加载自身的项目目录上下文，正确解析相对路径。

yaml

undefined

compose.yaml (root — application layer)

compose.yaml（根目录 —— 应用层）

include:

./infra/compose.yaml # DB, Redis, message broker
./monitoring/compose.yaml # Prometheus, Grafana

services: api: build: . depends_on: - db # defined in infra/compose.yaml - redis # defined in infra/compose.yaml


```yaml

include:

./infra/compose.yaml # 数据库、Redis、消息队列
./monitoring/compose.yaml # Prometheus、Grafana

services: api: build: . depends_on: - db # 定义在infra/compose.yaml中 - redis # 定义在infra/compose.yaml中


```yaml

infra/compose.yaml (infrastructure layer — owned by platform team)

infra/compose.yaml（基础设施层 —— 由平台团队维护）

services: db: image: postgres:16-alpine healthcheck: test: ['CMD-SHELL', 'pg_isready -U postgres'] interval: 5s timeout: 3s retries: 5 volumes: - db_data:/var/lib/postgresql/data

redis: image: redis:7-alpine healthcheck: test: ['CMD', 'redis-cli', 'ping'] interval: 5s timeout: 3s retries: 5

volumes: db_data:


`include` is recursive — included files can themselves include other files. Conflicts between resource names cause an error (no silent merging).

services: db: image: postgres:16-alpine healthcheck: test: ['CMD-SHELL', 'pg_isready -U postgres'] interval: 5s timeout: 3s retries: 5 volumes: - db_data:/var/lib/postgresql/data

redis: image: redis:7-alpine healthcheck: test: ['CMD', 'redis-cli', 'ping'] interval: 5s timeout: 3s retries: 5

volumes: db_data:


`include`支持递归 —— 被包含的文件可继续包含其他文件。资源名称冲突会触发错误（不会静默合并）。

Healthcheck Best Practices

健康检查最佳实践

Always define healthchecks on stateful services so that

depends_on: condition: service_healthy

works correctly. Without healthchecks, dependent services may start before their dependency is ready.

yaml

services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
      interval: 10s # How often to check
      timeout: 5s # Time to wait for response
      retries: 5 # Failures before marking unhealthy
      start_period: 30s # Grace period during container startup

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 3

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy # waits until db passes healthcheck
      redis:
        condition: service_healthy

Healthcheck guidelines:

Use
```
CMD
```
(array form) not
```
CMD-SHELL
```
(string form) where possible — avoids shell injection risk
Use
```
CMD-SHELL
```
only when you need shell features (
```
pg_isready
```
,
```
curl -f
```
, etc.)
Set
```
start_period
```
for services with slow startup (JVM apps, first-run migrations)
Avoid
```
curl
```
in Alpine-based images unless explicitly installed; prefer
```
wget -q --spider
```
or native checks

For HTTP services:

test: ["CMD-SHELL", "wget -q --spider http://localhost:3000/health || exit 1"]

始终为有状态服务定义健康检查，确保

depends_on: condition: service_healthy

正常工作。若无健康检查，依赖服务可能在其依赖项就绪前启动。

yaml

services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
      interval: 10s # 检查间隔
      timeout: 5s # 响应超时时间
      retries: 5 # 标记为不健康前的重试次数
      start_period: 30s # 容器启动后的宽限期

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 3

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy # 等待db通过健康检查
      redis:
        condition: service_healthy

健康检查指南：

尽可能使用
```
CMD
```
（数组形式）而非
```
CMD-SHELL
```
（字符串形式）—— 避免Shell注入风险
仅在需要Shell功能（如
```
pg_isready
```
、
```
curl -f
```
等）时使用
```
CMD-SHELL
```
为启动缓慢的服务（JVM应用、首次运行迁移）设置
```
start_period
```
Alpine镜像中使用
```
curl
```
需先安装；优先使用
```
wget -q --spider
```
或原生检查

HTTP服务：

test: ["CMD-SHELL", "wget -q --spider http://localhost:3000/health || exit 1"]

Multi-Stage Build Pattern

多阶段构建模式

Use multi-stage Dockerfiles to keep production images minimal and secure. Reference the specific build stage in compose.yaml for development.

dockerfile

undefined

使用多阶段Dockerfile缩小生产镜像体积并提升安全性。在compose.yaml中指定特定构建阶段用于开发。

dockerfile

undefined

Dockerfile

Stage 1: deps — install dependencies

阶段1：deps —— 安装依赖

FROM node:20-alpine AS deps WORKDIR /app COPY package*.json ./ RUN npm ci

Stage 2: builder — compile/transpile

阶段2：builder —— 编译/转译

FROM deps AS builder COPY . . RUN npm run build

Stage 3: runner — minimal production image

阶段3：runner —— 最小化生产镜像

FROM node:20-alpine AS runner RUN addgroup -g 1001 -S appgroup && adduser -S -u 1001 -G appgroup appuser WORKDIR /app COPY --from=builder --chown=appuser:appgroup /app/dist ./dist COPY --from=deps --chown=appuser:appgroup /app/node_modules ./node_modules USER appuser EXPOSE 3000 HEALTHCHECK --interval=30s --timeout=5s --retries=3
CMD wget -q --spider http://localhost:3000/health || exit 1 CMD ["node", "dist/index.js"]


```yaml

FROM node:20-alpine AS runner RUN addgroup -g 1001 -S appgroup && adduser -S -u 1001 -G appgroup appuser WORKDIR /app COPY --from=builder --chown=appuser:appgroup /app/dist ./dist COPY --from=deps --chown=appuser:appgroup /app/node_modules ./node_modules USER appuser EXPOSE 3000 HEALTHCHECK --interval=30s --timeout=5s --retries=3 \ CMD wget -q --spider http://localhost:3000/health || exit 1 CMD ["node", "dist/index.js"]


```yaml

compose.yaml — dev targets the builder stage for faster iteration

compose.yaml —— 开发环境使用builder阶段以加速迭代

services: api: build: context: . dockerfile: Dockerfile target: builder # Stop at builder stage in dev (includes devDeps) develop: watch: - action: sync path: ./src target: /app/src ignore: - node_modules/ - action: rebuild path: package.json


```yaml

services: api: build: context: . dockerfile: Dockerfile target: builder # 开发环境停留在builder阶段（包含开发依赖） develop: watch: - action: sync path: ./src target: /app/src ignore: - node_modules/ - action: rebuild path: package.json


```yaml

compose.prod.yaml — production uses the full runner stage

compose.prod.yaml —— 生产环境使用完整的runner阶段

services: api: build: context: . dockerfile: Dockerfile target: runner # Minimal, non-root production image restart: unless-stopped

undefined

services: api: build: context: . dockerfile: Dockerfile target: runner # 最小化、非root权限的生产镜像 restart: unless-stopped

undefined

Resource Limits (Best Practice)

资源限制（最佳实践）

Always define resource limits to prevent container resource exhaustion:

yaml

services:
  api:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    restart: unless-stopped

始终定义资源限制，防止容器资源耗尽：

yaml

services:
  api:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    restart: unless-stopped

Tools

工具集

The skill provides 15 tools across service management, monitoring, build operations, and troubleshooting categories:

本技能提供15个工具，涵盖服务管理、监控、构建操作与故障排查四大类别：

Service Management (5 tools)

服务管理（5个工具）

up

Start services defined in compose.yaml.

Parameter	Type	Description	Default
`detached`	boolean	Run in detached mode	true
`build`	boolean	Build images before starting	false
`force_recreate`	boolean	Recreate containers	false
`project_name`	string	Project name override	directory name
`services`	array	Specific services to start	all services
`profiles`	array	Profiles to activate	none
`watch`	boolean	Enable Compose Watch mode	false

Example:

bash

docker compose up -d
docker compose up --build
docker compose up web api
docker compose --profile debug up -d
docker compose up --watch

Safety: Requires confirmation for production environments.

启动compose.yaml中定义的服务。

参数	类型	描述	默认值
`detached`	boolean	后台运行模式	true
`build`	boolean	启动前构建镜像	false
`force_recreate`	boolean	强制重新创建容器	false
`project_name`	string	覆盖项目名称	目录名称
`services`	array	指定要启动的服务	所有服务
`profiles`	array	要激活的配置文件	无
`watch`	boolean	启用Compose Watch模式	false

示例：

bash

docker compose up -d
docker compose up --build
docker compose up web api
docker compose --profile debug up -d
docker compose up --watch

安全提示：生产环境需要确认。

down

Stop and remove containers, networks, volumes.

Parameter	Type	Description	Default
`volumes`	boolean	Remove volumes (BLOCKED)	false
`remove_orphans`	boolean	Remove orphaned containers	false
`project_name`	string	Project name override	directory name

Example:

bash

docker compose down
docker compose down --remove-orphans

Safety: Volume removal (

-v

flag) is BLOCKED by default. Requires confirmation.

停止并移除容器、网络、卷。

参数	类型	描述	默认值
`volumes`	boolean	移除卷（已禁用）	false
`remove_orphans`	boolean	移除孤立容器	false
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose down
docker compose down --remove-orphans

安全提示：卷移除（

-v

参数）默认禁用，需手动确认。

start

Start existing containers without recreating them.

Parameter	Type	Description	Default
`services`	array	Specific services to start	all services
`project_name`	string	Project name override	directory name

Example:

bash

docker compose start
docker compose start web

启动现有容器（不重新创建）。

参数	类型	描述	默认值
`services`	array	指定要启动的服务	所有服务
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose start
docker compose start web

stop

Stop running containers without removing them.

Parameter	Type	Description	Default
`timeout`	number	Shutdown timeout (seconds)	10
`services`	array	Specific services to stop	all services
`project_name`	string	Project name override	directory name

Example:

bash

docker compose stop
docker compose stop --timeout 30 web

停止运行中的容器（不移除）。

参数	类型	描述	默认值
`timeout`	number	关闭超时时间（秒）	10
`services`	array	指定要停止的服务	所有服务
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose stop
docker compose stop --timeout 30 web

restart

Restart services (stop + start).

Parameter	Type	Description	Default
`timeout`	number	Shutdown timeout (seconds)	10
`services`	array	Specific services to restart	all services
`project_name`	string	Project name override	directory name

Example:

bash

docker compose restart
docker compose restart api

重启服务（停止+启动）。

参数	类型	描述	默认值
`timeout`	number	关闭超时时间（秒）	10
`services`	array	指定要重启的服务	所有服务
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose restart
docker compose restart api

Status & Logs (3 tools)

状态与日志（3个工具）

ps

List containers with status information.

Parameter	Type	Description	Default
`all`	boolean	Show all containers (including stopped)	false
`services`	array	Filter by services	all services
`project_name`	string	Project name override	directory name

Example:

bash

docker compose ps
docker compose ps --all

Output Fields: NAME, IMAGE, STATUS, PORTS

列出容器及其状态信息。

参数	类型	描述	默认值
`all`	boolean	显示所有容器（包含已停止）	false
`services`	array	按服务筛选	所有服务
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose ps
docker compose ps --all

输出字段：NAME、IMAGE、STATUS、PORTS

logs

View service logs with streaming support.

Parameter	Type	Description	Default
`services`	array	Services to view logs for	all services
`follow`	boolean	Follow log output (stream)	false
`tail`	number	Number of lines to show	100
`timestamps`	boolean	Show timestamps	false
`since`	string	Show logs since timestamp/duration	none
`project_name`	string	Project name override	directory name

Example:

bash

docker compose logs web
docker compose logs --tail 50 --follow api
docker compose logs --since "2026-01-01T10:00:00"

Note: Follow mode automatically terminates after 60 seconds to prevent indefinite streaming.

查看服务日志，支持流式输出。

参数	类型	描述	默认值
`services`	array	要查看日志的服务	所有服务
`follow`	boolean	跟踪日志输出（流式）	false
`tail`	number	显示的日志行数	100
`timestamps`	boolean	显示时间戳	false
`since`	string	显示指定时间点/时间段后的日志	无
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose logs web
docker compose logs --tail 50 --follow api
docker compose logs --since "2026-01-01T10:00:00"

注意：跟踪模式会在60秒后自动终止，防止无限流式输出。

top

Display running processes in containers.

Parameter	Type	Description	Default
`services`	array	Services to inspect	all services
`project_name`	string	Project name override	directory name

Example:

bash

docker compose top
docker compose top web

Output: Process list with PID, USER, TIME, COMMAND

显示容器中运行的进程。

参数	类型	描述	默认值
`services`	array	要检查的服务	所有服务
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose top
docker compose top web

输出：进程列表，包含PID、USER、TIME、COMMAND

Build & Images (3 tools)

构建与镜像（3个工具）

build

Build or rebuild service images.

Parameter	Type	Description	Default
`no_cache`	boolean	Build without cache	false
`pull`	boolean	Pull newer image versions	false
`parallel`	boolean	Build in parallel	true
`services`	array	Services to build	all services
`project_name`	string	Project name override	directory name

Example:

bash

docker compose build
docker compose build --no-cache web
docker compose build --pull

Safety: Requires confirmation for no-cache builds (resource-intensive).

构建或重新构建服务镜像。

参数	类型	描述	默认值
`no_cache`	boolean	不使用缓存构建	false
`pull`	boolean	拉取更新的镜像版本	false
`parallel`	boolean	并行构建	true
`services`	array	要构建的服务	所有服务
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose build
docker compose build --no-cache web
docker compose build --pull

安全提示：无缓存构建（资源密集型）需要确认。

pull

Pull service images from registry.

Parameter	Type	Description	Default
`ignore_pull_failures`	boolean	Continue if pull fails	false
`services`	array	Services to pull	all services
`project_name`	string	Project name override	directory name

Example:

bash

docker compose pull
docker compose pull web api

Safety: Requires confirmation for production environments.

从注册表拉取服务镜像。

参数	类型	描述	默认值
`ignore_pull_failures`	boolean	拉取失败时继续	false
`services`	array	要拉取的服务	所有服务
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose pull
docker compose pull web api

安全提示：生产环境需要确认。

images

List images used by services.

Parameter	Type	Description	Default
`project_name`	string	Project name override	directory name

Example:

bash

docker compose images

Output Fields: CONTAINER, REPOSITORY, TAG, IMAGE ID, SIZE

列出服务使用的镜像。

参数	类型	描述	默认值
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose images

输出字段：CONTAINER、REPOSITORY、TAG、IMAGE ID、SIZE

Execution (2 tools)

执行操作（2个工具）

exec

Execute a command in a running container.

Parameter	Type	Description	Required
`service`	string	Service name	Yes
`command`	array	Command to execute	Yes
`user`	string	User to execute as	container default
`workdir`	string	Working directory	container default
`env`	object	Environment variables	none
`project_name`	string	Project name override	directory name

Example:

bash

docker compose exec web bash
docker compose exec -u root api ls -la /app
docker compose exec db psql -U postgres

Safety:

Destructive commands (
```
rm -rf
```
,
```
dd
```
,
```
mkfs
```
) are BLOCKED
Root user execution requires confirmation
Default timeout: 30 seconds

在运行中的容器内执行命令。

参数	类型	描述	必填项
`service`	string	服务名称	是
`command`	array	要执行的命令	是
`user`	string	执行命令的用户	容器默认用户
`workdir`	string	工作目录	容器默认目录
`env`	object	环境变量	无
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose exec web bash
docker compose exec -u root api ls -la /app
docker compose exec db psql -U postgres

安全提示：

破坏性命令（
```
rm -rf
```
、
```
dd
```
、
```
mkfs
```
）被禁用
以root用户执行需要确认
默认超时时间：30秒

run

Run a one-off command in a new container.

Parameter	Type	Description	Default
`service`	string	Service to run	Required
`command`	array	Command to execute	service default
`rm`	boolean	Remove container after run	true
`no_deps`	boolean	Don't start linked services	false
`user`	string	User to execute as	container default
`env`	object	Environment variables	none
`project_name`	string	Project name override	directory name

Example:

bash

docker compose run --rm web npm test
docker compose run --no-deps api python manage.py migrate

Safety: Requires confirmation for commands that modify data.

在新容器中运行一次性命令。

参数	类型	描述	默认值
`service`	string	要运行的服务	必填
`command`	array	要执行的命令	服务默认命令
`rm`	boolean	运行后移除容器	true
`no_deps`	boolean	不启动关联服务	false
`user`	string	执行命令的用户	容器默认用户
`env`	object	环境变量	无
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose run --rm web npm test
docker compose run --no-deps api python manage.py migrate

安全提示：修改数据的命令需要确认。

Configuration (2 tools)

配置（2个工具）

config

Validate and view the Compose file configuration.

Parameter	Type	Description	Default
`resolve_image_digests`	boolean	Pin image tags to digests	false
`no_interpolate`	boolean	Don't interpolate env vars	false
`project_name`	string	Project name override	directory name

Example:

bash

docker compose config
docker compose config --resolve-image-digests

Output: Parsed and merged Compose configuration

验证并查看Compose文件配置。

Parameter	类型	描述	默认值
`resolve_image_digests`	boolean	将镜像标签固定为摘要	false
`no_interpolate`	boolean	不插值环境变量	false
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose config
docker compose config --resolve-image-digests

输出：解析并合并后的Compose配置

port

Print the public port binding for a service port.

Parameter	Type	Description	Required
`service`	string	Service name	Yes
`private_port`	number	Container port	Yes
`protocol`	string	Protocol (tcp/udp)	tcp
`project_name`	string	Project name override	directory name

Example:

bash

docker compose port web 80
docker compose port db 5432

Output:

<host>:<port>

binding

打印服务端口的公开绑定。

参数	类型	描述	必填项
`service`	string	服务名称	是
`private_port`	number	容器端口	是
`protocol`	string	协议（tcp/udp）	tcp
`project_name`	string	覆盖项目名称	目录名称

示例：

bash

docker compose port web 80
docker compose port db 5432

输出：

<host>:<port>

绑定信息

Common Workflows

常见工作流

Start a Development Environment

启动开发环境

bash

undefined

bash

undefined

1. Validate configuration

1. 验证配置

docker compose config

2. Pull latest images

2. 拉取最新镜像

docker compose pull

3. Build custom images

3. 构建自定义镜像

docker compose build

4. Start services in detached mode

4. 后台启动服务

docker compose up -d

5. Check service status

5. 检查服务状态

docker compose ps

6. View logs

6. 查看日志

docker compose logs --tail 100

undefined

docker compose logs --tail 100

undefined

Live Development with Compose Watch

使用Compose Watch进行本地开发

bash

undefined

bash

undefined

1. Ensure develop.watch blocks are configured in compose.yaml

1. 确保compose.yaml中配置了develop.watch块

2. Start with watch mode (foreground, shows sync events)

2. 启动监听模式（前台，显示同步事件）

docker compose watch

3. Or start detached then watch

3. 或后台启动后再监听

docker compose up -d docker compose watch --no-up

undefined

docker compose up -d docker compose watch --no-up

undefined

Troubleshoot a Failing Service

排查故障服务

bash

undefined

bash

undefined

1. Check container status

1. 检查容器状态

docker compose ps --all

2. View service logs

2. 查看服务日志

docker compose logs --tail 200 failing-service

3. Inspect running processes

3. 检查运行中的进程

docker compose top failing-service

4. Check configuration

4. 验证配置

docker compose config

5. Restart the service

5. 重启服务

docker compose restart failing-service

6. If needed, recreate container

6. 若需要，重新创建容器

docker compose up -d --force-recreate failing-service

undefined

docker compose up -d --force-recreate failing-service

undefined

Update Service Images

更新服务镜像

bash

undefined

bash

undefined

1. Pull latest images

1. 拉取最新镜像

docker compose pull

2. Stop services

2. 停止服务

docker compose down

3. Rebuild if using custom Dockerfiles

3. 若使用自定义Dockerfile，重新构建

docker compose build --pull

4. Start with new images

4. 启动新镜像

docker compose up -d

5. Verify services

5. 验证服务

docker compose ps

undefined

docker compose ps

undefined

Debug Service Connectivity

排查服务连通性

bash

undefined

bash

undefined

1. Check running services

1. 检查运行中的服务

docker compose ps

2. Inspect port mappings

2. 检查端口映射

docker compose port web 80 docker compose port api 3000

3. Exec into container

3. 进入容器

docker compose exec web sh

4. Test connectivity (from inside container)

4. 测试连通性（从容器内部）

docker compose exec web curl api:3000/health

5. Check logs for errors

5. 查看错误日志

docker compose logs web api

undefined

docker compose logs web api

undefined

Clean Up Environment

清理环境

bash

undefined

bash

undefined

1. Stop all services

1. 停止所有服务

docker compose down

2. Remove orphaned containers

2. 移除孤立容器

docker compose down --remove-orphans

3. View images

3. 查看镜像

docker compose images

4. Clean up (manual - volume removal BLOCKED)

4. 清理（手动操作 - 卷移除已禁用）

Volumes require manual cleanup with explicit confirmation

卷清理需要手动确认

undefined

undefined

Use Profiles for Environment-Specific Services

使用配置文件启动环境专属服务

bash

undefined

bash

undefined

Development: default services only

开发环境：仅启动默认服务

docker compose up -d

Development + debug tools

开发环境+调试工具

docker compose --profile debug up -d

Start monitoring stack

启动监控栈

docker compose --profile monitoring up -d

Via env var (useful in CI)

通过环境变量设置（适用于CI）

COMPOSE_PROFILES=monitoring docker compose up -d

Stop and clean a specific profile

停止并清理特定配置文件的服务

docker compose --profile debug down

undefined

docker compose --profile debug down

undefined

Configuration

配置

Environment Variables

环境变量

Variable	Description	Default
`COMPOSE_PROJECT_NAME`	Default project name	directory name
`COMPOSE_FILE`	Compose file path	`compose.yaml`
`COMPOSE_PROFILES`	Comma-separated active profiles	(none)
`COMPOSE_PATH_SEPARATOR`	Path separator for multiple files	`:` (Linux/Mac), `;` (Windows)
`DOCKER_HOST`	Docker daemon socket	`unix:///var/run/docker.sock`
`COMPOSE_HTTP_TIMEOUT`	HTTP timeout for API calls	60
`COMPOSE_PARALLEL_LIMIT`	Max parallel operations	unlimited

变量名	描述	默认值
`COMPOSE_PROJECT_NAME`	默认项目名称	目录名称
`COMPOSE_FILE`	Compose文件路径	`compose.yaml`
`COMPOSE_PROFILES`	逗号分隔的激活配置文件	无
`COMPOSE_PATH_SEPARATOR`	多文件路径分隔符	`:` （Linux/Mac）、 `;` （Windows）
`DOCKER_HOST`	Docker守护进程套接字	`unix:///var/run/docker.sock`
`COMPOSE_HTTP_TIMEOUT`	API调用的HTTP超时时间	60
`COMPOSE_PARALLEL_LIMIT`	最大并行操作数	无限制

Setup

安装设置

Install Docker Engine:

bash

# macOS
brew install --cask docker

# Linux (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Windows
# Download Docker Desktop from docker.com

Verify Docker Compose:

bash

# Check Docker version
docker --version

# Check Compose version (must be V2, e.g. 2.24+)
docker compose version

Create compose.yaml (no

version:

field — V2 does not require it):

yaml

services:
  web:
    build: .
    ports:
      - '8080:80'
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: example
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5

Test the skill:
bash
```
docker compose config
docker compose ps
```

安装Docker Engine：

bash

# macOS
brew install --cask docker

# Linux（Ubuntu/Debian）
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Windows
# 从docker.com下载Docker Desktop

验证Docker Compose：

bash

# 检查Docker版本
docker --version

# 检查Compose版本（必须是V2，如2.24+）
docker compose version

创建compose.yaml（无需

version:

字段 —— V2不要求）：

yaml

services:
  web:
    build: .
    ports:
      - '8080:80'
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: example
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5

测试技能：
bash
```
docker compose config
docker compose ps
```

Safety Features

安全特性

Blocked Operations

禁用操作

The following operations are BLOCKED by default to prevent accidental data loss:

Volume removal:
```
docker compose down -v
```
(BLOCKED - requires manual confirmation)
Full cleanup:
```
docker compose down -v --rmi all
```
(BLOCKED - extremely destructive)
Destructive exec:
```
rm -rf
```
,
```
dd
```
,
```
mkfs
```
,
```
sudo rm
```
inside containers (BLOCKED)
Force removal:
```
docker compose rm -f
```
(BLOCKED - use stop then rm)

以下操作默认禁用，防止意外数据丢失：

卷移除：
```
docker compose down -v
```
（禁用 - 需手动确认）
完全清理：
```
docker compose down -v --rmi all
```
（禁用 - 极具破坏性）
破坏性exec命令：容器内执行
```
rm -rf
```
、
```
dd
```
、
```
mkfs
```
、
```
sudo rm
```
（禁用）
强制移除：
```
docker compose rm -f
```
（禁用 - 应先stop再rm）

Confirmation Required

需要确认的操作

These operations require explicit confirmation:

Building with
```
--no-cache
```
(resource-intensive)
Pulling images in production environments
Starting services with
```
--force-recreate
```
Executing commands as root user
Running commands that modify databases
Stopping services with very short timeouts

以下操作需要明确确认：

使用
```
--no-cache
```
构建（资源密集型）
生产环境拉取镜像
使用
```
--force-recreate
```
启动服务
以root用户执行命令
运行修改数据库的命令
使用极短超时时间停止服务

Auto-Terminating Operations

自动终止操作

The following operations auto-terminate to prevent resource issues:

Log following (
```
--follow
```
): 60-second timeout
Service execution (
```
exec
```
): 30-second timeout
One-off commands (
```
run
```
): 60-second timeout

以下操作会自动终止，防止资源问题：

日志跟踪（
```
--follow
```
）：60秒超时
服务执行（
```
exec
```
）：30秒超时
一次性命令（
```
run
```
）：60秒超时

Error Handling

错误处理

Common Errors:

Error	Cause	Fix
`docker: command not found`	Docker not installed	Install Docker Engine
`Cannot connect to Docker daemon`	Docker not running	Start Docker service
`network ... not found`	Network cleanup issue	Run `docker compose down` then `up`
`port is already allocated`	Port conflict	Change port mapping or stop conflicting service
`no configuration file provided`	Missing compose file	Create `compose.yaml`
`service ... must be built`	Image not built	Run `docker compose build`
`service unhealthy`	Healthcheck failing	Check `docker compose logs <service>`
`include path not found`	Missing included file	Verify paths in `include:` block

Recovery:

Validate configuration:
```
docker compose config
```
Check Docker status:
```
docker info
```
View service logs:
```
docker compose logs
```
Force recreate:
```
docker compose up -d --force-recreate
```

Clean restart:

docker compose down && docker compose up -d

常见错误：

错误信息	原因	修复方案
`docker: command not found`	未安装Docker	安装Docker Engine
`Cannot connect to Docker daemon`	Docker未运行	启动Docker服务
`network ... not found`	网络清理问题	运行 `docker compose down` 后再执行 `up`
`port is already allocated`	端口冲突	修改端口映射或停止冲突服务
`no configuration file provided`	缺少compose文件	创建 `compose.yaml`
`service ... must be built`	镜像未构建	运行 `docker compose build`
`service unhealthy`	健康检查失败	查看 `docker compose logs <service>`
`include path not found`	缺少被包含的文件	验证 `include:` 块中的路径

恢复步骤：

验证配置：
```
docker compose config
```
检查Docker状态：
```
docker info
```
查看服务日志：
```
docker compose logs
```
强制重新创建：
```
docker compose up -d --force-recreate
```

完全重启：

docker compose down && docker compose up -d

Integration with Agents

与Agent的集成

This skill integrates with the following agents:

本技能与以下Agent集成：

Primary Agents

主要Agent

devops: Local development, CI/CD integration, container orchestration
developer: Application development, testing, debugging

devops：本地开发、CI/CD集成、容器编排
developer：应用开发、测试、调试

Secondary Agents

次要Agent

qa: Integration testing, test environment setup
incident-responder: Debugging production issues, service recovery
cloud-integrator: Cloud deployment, migration to Kubernetes
performance-engineer: Performance testing, resource optimization

qa：集成测试、测试环境搭建
incident-responder：生产问题调试、服务恢复
cloud-integrator：云部署、向Kubernetes迁移
performance-engineer：性能测试、资源优化

Progressive Disclosure

渐进式信息披露

The skill uses progressive disclosure to minimize context usage:

Initial Load: Only metadata and tool names (~700 tokens)
Tool Invocation: Specific tool schema loaded on-demand (~100-150 tokens)
Result Streaming: Large outputs (logs) streamed incrementally
Context Cleanup: Old results cleared after use

Context Optimization:

Use
```
--tail
```
to limit log output
Use service filters to target specific containers
Prefer
```
ps
```
over
```
ps --all
```
for active services only
Use
```
--since
```
for time-bounded log queries

本技能使用渐进式信息披露以最小化上下文使用：

初始加载：仅加载元数据和工具名称（约700个token）
工具调用：按需加载特定工具的schema（约100-150个token）
结果流式输出：大型输出（如日志）增量流式返回
上下文清理：使用后清除旧结果

上下文优化技巧：

使用
```
--tail
```
限制日志输出
使用服务筛选器定位特定容器
优先使用
```
ps
```
而非
```
ps --all
```
查看活跃服务
使用
```
--since
```
查询指定时间范围内的日志

Troubleshooting

故障排查

Skill Issues

技能相关问题

Docker Compose not found:

bash

undefined

Docker Compose未找到：

bash

undefined

Check Docker Compose version

检查Docker Compose版本

docker compose version

V1 (docker-compose) is end-of-life — upgrade to V2

V1（docker-compose）已停止维护 —— 升级到V2

Docker Compose V2 is integrated into Docker CLI as a plugin

Docker Compose V2已作为插件集成到Docker CLI中


**Permission denied**:

```bash


**权限拒绝**：

```bash

Add user to docker group (Linux)

将用户加入docker组（Linux）

sudo usermod -aG docker $USER newgrp docker

Verify permissions

验证权限

docker ps


**Compose file issues**:

```bash

docker ps


**Compose文件问题**：

```bash

Validate syntax

验证语法

docker compose config

Check for errors (quiet mode — exit code only)

检查错误（静默模式 —— 仅返回退出码）

docker compose config -q

View resolved configuration

查看解析后的配置

docker compose config --resolve-image-digests


**Network issues**:

```bash

docker compose config --resolve-image-digests


**网络问题**：

```bash

List networks

列出网络

docker network ls

Remove unused networks

移除未使用的网络

docker network prune

Recreate services

重新创建服务

docker compose down docker compose up -d


**Healthcheck failures**:

```bash

docker compose down docker compose up -d


**健康检查失败**：

```bash

Inspect healthcheck status

检查健康检查状态

docker inspect <container_id> | grep -A 10 Health

View healthcheck output

查看健康检查输出

docker compose logs <service>

Manually run the healthcheck command

手动运行健康检查命令

docker compose exec <service> pg_isready -U postgres


**Compose Watch not syncing**:

```bash

docker compose exec <service> pg_isready -U postgres


**Compose Watch不同步**：

```bash

Verify develop.watch block is present in compose.yaml

验证compose.yaml中存在develop.watch块

docker compose config | grep -A 20 develop

Ensure Compose version is 2.22+

确保Compose版本为2.22+

docker compose version

Watch requires build: attribute (not image: only)

Watch功能需要build属性（不能仅使用image:）

undefined

undefined

Performance Considerations

性能考量

Build caching: Use layer caching for faster builds; avoid
```
--no-cache
```
unless necessary
Multi-stage builds: Dramatically reduce production image size (often 80%+)
Parallel operations: Docker Compose V2 parallelizes by default; use
```
COMPOSE_PARALLEL_LIMIT
```
to control
Resource limits: Define CPU/memory limits in compose file to prevent resource exhaustion
Log rotation: Use logging drivers to prevent disk space issues
Volume cleanup: Regularly clean unused volumes (requires manual confirmation)
Compose Watch vs bind mounts: Prefer
```
develop.watch
```
for cross-platform development; bind mounts have I/O performance issues on macOS/Windows

构建缓存：使用分层缓存加速构建；除非必要，否则避免
```
--no-cache
```
多阶段构建：大幅减少生产镜像体积（通常减少80%+）
并行操作：Docker Compose V2默认并行执行；使用
```
COMPOSE_PARALLEL_LIMIT
```
控制
资源限制：在compose文件中定义CPU/内存限制，防止资源耗尽
日志轮转：使用日志驱动防止磁盘空间不足
卷清理：定期清理未使用的卷（需手动确认）
Compose Watch vs 绑定挂载：优先使用
```
develop.watch
```
进行跨平台开发；绑定挂载在macOS/Windows上存在I/O性能问题

Sources

资料来源

Related Skills

Memory Protocol (MANDATORY)

内存协议（强制）

Before starting: Read

.claude/context/memory/learnings.md

After completing:

New pattern ->
```
.claude/context/memory/learnings.md
```
Issue found ->
```
.claude/context/memory/issues.md
```
Decision made ->
```
.claude/context/memory/decisions.md
```

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

开始前：阅读

.claude/context/memory/learnings.md

完成后：

新模式 ->
```
.claude/context/memory/learnings.md
```
发现的问题 ->
```
.claude/context/memory/issues.md
```
做出的决策 ->
```
.claude/context/memory/decisions.md
```

假设会被中断：未存入内存的内容视为未发生。",