1. 从单兵作战到集团军：为什么我们需要Docker Compose

如果你已经用Docker跑过几个容器，比如一个MySQL数据库，或者一个Nginx服务器，那你肯定体验过它的便利：环境隔离、一键部署、版本控制。但现实中的项目，很少是“一个容器打天下”的。一个典型的Web应用，至少需要一个应用容器（比如你的Spring Boot或Node.js后端）、一个数据库容器（比如MySQL或PostgreSQL），可能还需要一个缓存容器（比如Redis）、一个消息队列（比如RabbitMQ），甚至前端和后端还要分开部署。

这时候，如果你还在用原始的docker run命令，画风就会变成这样：

# 先启动数据库 docker run -d --name mysql-db -e MYSQL_ROOT_PASSWORD=123456 -v /data/mysql:/var/lib/mysql mysql:8.0 # 再启动Redis docker run -d --name redis-cache -p 6379:6379 redis:alpine # 最后启动你的应用，并且要链接到上面两个服务，还要挂载配置文件，设置环境变量... docker run -d --name my-app -p 8080:8080 \ --link mysql-db:db \ --link redis-cache:redis \ -e DB_HOST=db \ -e REDIS_HOST=redis \ -v ./app-config:/config \ my-app-image:latest

这还只是三个服务。想象一下，每次启动项目，你都得敲这么一长串命令，顺序还不能错（数据库必须先于应用启动）。更麻烦的是，如果你想在另一台机器上复现这个环境，你得把这一堆命令记下来，或者写成一个又长又容易出错的脚本。这完全违背了Docker“一次构建，处处运行”的初衷。

Docker Compose就是来解决这个“容器编排”问题的。它不是一个独立的容器运行时，而是一个用于定义和运行多容器Docker应用的工具。你可以把它理解为一个“乐高说明书”。你用YAML格式写一个docker-compose.yml文件，在这个文件里，你清晰地定义出：这个应用由哪几个“服务”（Service，即容器）组成，每个服务用什么镜像、需要哪些端口、挂载哪些卷、依赖哪些其他服务、环境变量是什么。然后，只需要一条命令docker compose up，Compose就会按照你定义好的蓝图，自动帮你创建网络、拉取镜像、按顺序启动所有容器，并把它们组织成一个逻辑上统一的应用。

从“单兵作战”到“集团军协同”，Docker Compose让你管理复杂多容器应用变得像管理单个应用一样简单。它极大地简化了开发、测试和持续集成环境中的服务依赖管理，是现代化应用部署流程中不可或缺的一环。

2. 核心概念拆解：Service, Network, Volume 在Compose中的角色

要玩转Docker Compose，必须吃透它的三个核心抽象：服务（Service）、网络（Network）和卷（Volume）。它们共同构成了一个可运行应用的基础设施模型。

2.1 服务（Service）：应用的功能单元

在Compose的世界里，“服务”是最核心的概念。一个服务对应一个容器化的应用组件。例如，你的博客系统可能包含web（前端）、api（后端）、database（数据库）和cache（缓存）四个服务。

在docker-compose.yml中，每个服务都是一个顶级键。它的配置决定了这个容器如何运行：

services: web: image: nginx:alpine ports: - "80:80" depends_on: - api api: build: ./backend environment: - DB_HOST=database database: image: postgres:15 environment: POSTGRES_PASSWORD: secret

关键点解析：

• imagevsbuild：image指定从镜像仓库拉取现成的镜像（如nginx:alpine）。build则指定一个包含Dockerfile的目录路径，Compose会现场构建镜像。这在开发阶段极其常用，你改几行代码，docker compose up --build就能重建镜像并重启服务。
• depends_on：定义了服务间的启动依赖关系。上面例子中，Compose会先启动database和api，最后才启动web。但请注意，depends_on只控制启动顺序，并不等待目标服务“就绪”（比如PostgreSQL完成初始化、可以接受连接）。对于有严格就绪依赖的场景，需要结合健康检查（healthcheck）或使用脚本等待。
• environment：设置容器内的环境变量，这是向应用传递配置（如数据库连接串、API密钥）的标准方式。敏感信息不应硬编码在此，应使用env_file或Docker Secrets（生产环境）。

2.2 网络（Network）：服务间的通信总线

默认情况下，当你执行docker compose up时，Compose会为这个项目创建一个独立的、默认的桥接网络。这个网络是项目隔离的关键。所有在同一个Compose文件中定义的服务，都会自动加入这个网络。

在这个网络里，服务之间可以通过服务名作为主机名直接通信。这是Compose带来的巨大便利。以上面的YAML为例，在api服务的容器内部，你可以直接使用database这个主机名来连接PostgreSQL数据库，而无需知道它的具体IP地址。同样，web服务中的Nginx配置里，proxy_pass可以直接指向http://api:3000。

你还可以定义自定义网络，实现更精细的网络隔离，比如将前端服务和后端服务放在一个网络，将后端服务和数据库放在另一个网络。

2.3 卷（Volume）：数据的持久化存储

容器本身是无状态的，当容器被删除，其内部产生的所有数据（如MySQL的数据文件、应用上传的图片、日志）都会随之消失。卷（Volume）就是用来持久化存储这些数据的Docker对象。

在Compose中，你可以声明和管理卷：

services: database: image: mysql:8.0 volumes: - db_data:/var/lib/mysql # 命名卷 - ./my-cnf:/etc/mysql/conf.d # 绑定挂载（主机路径） volumes: db_data: # 声明一个命名卷

• 命名卷（Named Volume）：如上面的db_data。由Docker管理，生命周期独立于容器，是最推荐的数据持久化方式。你无需关心它在主机上的具体路径，Docker会妥善处理。删除容器不会删除卷，下次启动新容器挂载同一个卷，数据依然存在。
• 绑定挂载（Bind Mount）：如./my-cnf:/etc/mysql/conf.d。直接将主机上的一个目录或文件挂载到容器内。这在开发时非常有用，你可以在主机上修改代码，容器内实时生效，无需重建镜像。但在生产环境需谨慎使用，因为它将主机目录暴露给了容器，可能存在安全风险，且移植性差。
• 匿名卷：在服务中直接使用容器路径（如- /var/lib/mysql），Docker会自动创建匿名卷。不推荐在Compose中显式使用，因为难以管理。

理解并善用这三大概念，你就能像搭积木一样，用Compose文件清晰、可靠地定义出整个应用的运行态。

3. 手把手编写你的第一个 docker-compose.yml 文件

理论说再多，不如动手写一个。我们来为一个简单的“待办事项”（Todo）应用编写一个Compose文件。这个应用包含：

1. 一个Node.js后端（REST API），使用express框架。
2. 一个PostgreSQL数据库，用于存储数据。
3. 一个PgAdmin（数据库管理工具），方便我们查看数据。

3.1 项目结构与准备

假设你的项目目录结构如下：

my-todo-app/ ├── docker-compose.yml ├── backend/ │ ├── Dockerfile │ ├── package.json │ └── server.js └── .env # （可选）环境变量文件

• backend/Dockerfile内容（示例）：

  FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . EXPOSE 3000 CMD ["node", "server.js"]

• backend/server.js是一个简单的Express应用，会连接POSTGRES_HOST环境变量指定的数据库。

3.2 编写 docker-compose.yml

现在，在my-todo-app根目录下创建docker-compose.yml文件：

version: '3.8' # 指定Compose文件格式版本，建议使用3.x services: # 后端API服务 api: build: ./backend # 使用当前目录下的backend文件夹中的Dockerfile构建镜像 container_name: todo-api # 为容器指定一个自定义名称 restart: unless-stopped # 容器退出时自动重启（除非手动停止） ports: - "3000:3000" # 将主机的3000端口映射到容器的3000端口 environment: # 设置环境变量 - NODE_ENV=production - POSTGRES_HOST=database # 关键！使用服务名“database”作为主机名 - POSTGRES_USER=${DB_USER:-postgres} # 从.env文件或默认值读取 - POSTGRES_PASSWORD=${DB_PASSWORD:-changeme} - POSTGRES_DB=${DB_NAME:-todos} depends_on: - database # 声明依赖，先启动database服务 networks: - app-network # 健康检查：确保应用真正就绪 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3000/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s # 数据库服务 database: image: postgres:15-alpine # 使用官方PostgreSQL Alpine镜像，体积小 container_name: todo-db restart: unless-stopped environment: POSTGRES_USER: ${DB_USER:-postgres} POSTGRES_PASSWORD: ${DB_PASSWORD:-changeme} POSTGRES_DB: ${DB_NAME:-todos} volumes: - postgres_data:/var/lib/postgresql/data # 使用命名卷持久化数据库数据 networks: - app-network # 数据库的健康检查更为重要 healthcheck: test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-postgres}"] interval: 10s timeout: 5s retries: 5 # 数据库管理工具 pgadmin: image: dpage/pgadmin4 container_name: todo-pgadmin restart: unless-stopped environment: PGADMIN_DEFAULT_EMAIL: admin@example.com PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD:-admin} ports: - "8080:80" # 通过主机8080端口访问PgAdmin Web界面 depends_on: database: condition: service_healthy # 高级用法：等待database服务通过健康检查 networks: - app-network # 定义网络和卷 networks: app-network: # 定义一个自定义网络，所有服务将加入此网络 driver: bridge volumes: postgres_data: # 定义一个命名卷，用于数据库持久化

3.3 关键配置深度解读

1. 版本（version）：3.8是一个广泛兼容且功能稳定的版本。它对应Docker Engine 19.03.0+。你不需要追求最新版本，稳定够用即可。
2. 环境变量与.env文件：我们使用了${VAR_NAME:-default_value}这种语法。Compose会自动读取项目根目录下的.env文件。你可以创建.env文件来设置敏感信息，而无需硬编码在YAML中：

   DB_USER=myuser DB_PASSWORD=MyS3cr3tP@ss! DB_NAME=tododb PGADMIN_PASSWORD=Pg@dminS3cr3t!

   重要：务必把.env文件加入.gitignore，防止密码泄露。
3. 健康检查（healthcheck）：这是生产级配置的关键。它让Compose（或其他编排工具）能感知服务内部状态。api服务检查/health端点，database服务使用pg_isready命令。在pgadmin的depends_on中，我们使用了condition: service_healthy，这确保了PgAdmin只在数据库完全就绪后才启动，避免了连接失败。
4. 网络隔离：我们显式定义了一个名为app-network的桥接网络。三个服务都连接到此网络，它们可以相互通过服务名访问，但与主机或其他Compose项目中的容器隔离，更安全。
5. 数据持久化：postgres_data是一个命名卷，它保证了即使database容器被销毁重建，数据库文件也不会丢失。这个卷的数据存储在Docker管理区域（Linux下通常在/var/lib/docker/volumes/），无需手动备份路径。

4. 实战操作：启动、管理、调试与日常运维

文件写好了，接下来就是让它跑起来。Docker Compose提供了一套简洁而强大的命令行工具。

4.1 核心命令全解析

在包含docker-compose.yml的目录下，执行以下命令：

• 启动所有服务：

  docker compose up

  默认在前台运行，所有容器的日志会混合输出到当前终端。按Ctrl+C会停止所有容器。

  • 后台启动：加-d参数，docker compose up -d。
  • 重建镜像并启动：在开发中，修改代码或Dockerfile后，使用docker compose up -d --build。Compose会对配置了build的服务重新构建镜像。

• 查看服务状态：

  docker compose ps

  这会列出所有由当前Compose项目管理的容器，显示它们的名称、状态、端口映射等信息，比docker ps更聚焦于当前项目。

• 查看服务日志：

  docker compose logs

  查看所有服务的混合日志。

  • 查看特定服务：docker compose logs api
  • 实时跟踪（tail -f）：docker compose logs -f api database

• 停止服务：

  docker compose down

  这是最重要的命令之一。它会停止并移除所有容器、网络（默认创建的），但不会移除命名卷和数据卷，这是为了保护你的数据。如果你也想移除卷，需要加-v参数：docker compose down -v（危险操作！会删除所有数据！）。

• 进入容器执行命令（调试神器）：

  docker compose exec api sh

  这相当于在运行中的api服务容器里，打开一个shell。你可以在这里查看文件、运行命令（如npm list、curl localhost:3000）、检查环境变量等，对于调试问题极其有用。

• 重启服务：

  docker compose restart api

• 暂停/恢复服务：

  docker compose pause database docker compose unpause database

4.2 开发、测试与生产的多环境配置

一个项目通常有开发、测试、生产等多个环境。它们的配置（如端口、镜像标签、资源限制）往往不同。Docker Compose通过两种主要方式支持多环境：

方法一：使用多个Compose文件（推荐）这是最灵活的方式。你有一个基础的docker-compose.yml，然后通过-f参数指定覆盖文件。

1. docker-compose.yml(基础配置，定义所有服务):

   services: api: build: . environment: - NODE_ENV=development database: image: postgres:15-alpine

2. docker-compose.override.yml(开发环境覆盖，默认自动加载):

   services: api: ports: - "3000:3000" volumes: - .:/app # 绑定挂载，实现代码热更新 - /app/node_modules command: npm run dev # 覆盖为开发命令

   开发时，直接docker compose up，Compose会自动合并override.yml。
3. docker-compose.prod.yml(生产环境覆盖):

   services: api: build: . image: myregistry.com/myapp:${TAG:-latest} # 使用构建好的特定标签镜像 environment: - NODE_ENV=production deploy: # 生产环境可能使用Swarm模式配置 resources: limits: cpus: '1' memory: 512M # 移除开发用的绑定挂载和端口映射（可能由反向代理处理） volumes: - app-logs:/var/log/app volumes: app-logs:

   生产环境部署时：docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

方法二：使用环境变量插值在YAML中大量使用${VARIABLE}，然后在不同环境通过.env文件或Shell环境变量来设置。这适合配置项多但结构差异不大的情况。

4.3 常见问题排查与调试技巧

1. 服务启动失败：depends_on的坑症状：api服务不断重启，日志显示“数据库连接失败”。 原因：depends_on只保证database容器启动，不保证PostgreSQL进程就绪接受连接。 解决方案：

   • 使用健康检查：如上文示例，为database配置healthcheck，并为依赖它的服务（如api）在depends_on中设置condition: service_healthy（Compose v2.1+格式略有不同，注意版本）。
   • 应用层重试：在你的应用代码（如Node.js、Java）中，实现数据库连接的重试逻辑。
   • 使用wait-for-it.sh或dockerize工具：在容器的启动命令前，插入一个等待脚本。

2. 端口冲突症状：Error starting userland proxy: listen tcp4 0.0.0.0:8080: bind: address already in use原因：主机上的8080端口已被其他程序（可能是另一个容器）占用。 解决方案：

   • docker compose ps查看是否已有容器占用了该端口。
   • netstat -tulpn | grep :8080(Linux) 或lsof -i :8080(Mac) 查找占用进程。
   • 修改docker-compose.yml中的端口映射，例如将"8080:80"改为"8081:80"。

3. 卷权限问题（常见于Linux主机）症状：数据库容器启动失败，日志显示“Permission denied” on/var/lib/postgresql/data。 原因：容器内进程（如postgres用户，UID=999）试图写入挂载的主机目录，但主机目录的所有者权限不匹配。 解决方案（针对命名卷，这是最佳实践）：

   • 使用命名卷：Docker会自动处理好权限，这是首选。
   • 如果必须用绑定挂载：确保主机目录对容器内进程的用户可写。可能需要调整主机目录的权限（chown或chmod），但这有安全风险。

4. 镜像构建缓存导致代码未更新症状：修改了代码，docker compose up --build后，应用行为还是旧的。 原因：Docker构建缓存。如果Dockerfile中COPY . .之前的层（如RUN npm install）没有变化，Docker可能会使用缓存，导致新的代码文件没有被复制进去。 解决方案：

   • docker compose build --no-cache api：强制不使用缓存重建镜像。
   • 优化Dockerfile，将经常变动的步骤（如COPY）放在后面，不常变的步骤（如安装依赖）放在前面，以最大化利用缓存。

5. 从Compose到生产：进阶模式与最佳实践

当你熟悉了基本的Compose操作后，可以考虑以下进阶用法，让你的容器化部署更健壮、更专业。

5.1 使用Profiles控制服务启动组合

Compose v3.8+ 引入了Profiles功能，允许你标记服务，然后按需启动一组服务。这比维护多个文件更轻量，适合定义可选的服务组合。

services: web: # ... 基础配置 database: # ... 基础配置 redis: image: redis:alpine profiles: ["cache"] # 这个服务属于“cache” profile monitoring: image: grafana/grafana profiles: ["monitor"] # 这个服务属于“monitor” profile

• 默认启动（不启用任何profile）：docker compose up只会启动web和database。
• 启动带缓存的环境：docker compose --profile cache up会启动web,database,redis。
• 启动所有服务：docker compose --profile cache --profile monitor up。

这在需要不同功能组合（如开发带监控、测试带缓存）的场景下非常方便。

5.2 资源限制与部署配置

为了防止某个容器耗尽主机资源，你可以在Compose文件中设置资源限制。这对于生产环境尤为重要。

services: api: # ... 其他配置 deploy: # 注意：`deploy` 部分主要在Docker Swarm模式下生效，但某些资源限制在 `docker compose up` 时也有效（取决于版本） resources: limits: cpus: '0.5' # 最多使用0.5个CPU核心 memory: 512M # 内存硬限制，超过会被OOM Killer终止 reservations: cpus: '0.1' memory: 256M # 内存软保证，尽量分配这么多 # 对于非Swarm模式，也可以使用旧式配置（仍有效）： # mem_limit: 512M # mem_reservation: 256M # cpus: 0.5

5.3 集成到CI/CD流水线

Docker Compose是CI/CD（持续集成/持续部署）的绝佳伴侣。你可以在GitLab CI、GitHub Actions、Jenkins等工具中轻松使用它。

一个典型的GitHub Actions工作流步骤可能如下：

jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - name: Start services with Docker Compose run: | docker compose -f docker-compose.test.yml up -d # 等待服务健康 docker compose -f docker-compose.test.yml run --rm wait-for-db - name: Run tests run: | docker compose -f docker-compose.test.yml run --rm api npm test - name: Stop services if: always() # 无论测试成功与否，都清理环境 run: docker compose -f docker-compose.test.yml down

5.4 安全最佳实践

1. 永远不要将秘密硬编码在docker-compose.yml中。使用.env文件，并确保它被.gitignore排除。对于生产环境，考虑使用Docker Secrets（Swarm模式）或云服务商提供的密钥管理服务（如AWS Secrets Manager, Azure Key Vault）。
2. 使用非root用户运行容器。在你的Dockerfile中，使用USER指令切换到一个非root用户。

   FROM node:18-alpine RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001 USER nodejs # ... 后续指令将以nodejs用户身份运行

3. 定期更新基础镜像。镜像中的软件可能存在安全漏洞。定期（或在CI流水线中）使用docker compose build --pull来获取基础镜像的最新版本，并重建你的应用镜像。
4. 扫描镜像漏洞。使用docker scan命令（集成Snyk）或Trivy、Clair等工具，对构建出的镜像进行安全漏洞扫描。
5. 限制容器能力。在Compose文件中，可以移除不必要的Linux能力，设置为只读文件系统等。

   services: api: # ... security_opt: - no-new-privileges:true cap_drop: - ALL cap_add: - NET_BIND_SERVICE # 只添加必要的权限，如绑定低端口 read_only: true # 设置根文件系统为只读 tmpfs: # 对需要写入的目录使用tmpfs - /tmp - /var/run

从编写第一个简单的docker-compose.yml，到管理包含数十个服务的复杂应用，Docker Compose始终是本地开发、测试和小规模生产部署的利器。它用声明式的配置，将基础设施即代码（Infrastructure as Code）的理念轻量化地带入日常开发，极大地提升了开发者的体验和部署的一致性。当你需要更强大的集群管理、服务发现、滚动更新等功能时，可以很自然地将Compose文件作为基础，迁移到Kubernetes（例如使用kompose工具转换）或Docker Swarm，这又是另一个广阔天地了。