Docker 工程化实践（六）：Docker Compose 管理多容器应用

Docker 工程化实践系列 · 第 6 篇

引言：一个后端项目从来不止一个服务

前面五篇文章，我们构建和优化的都是一个独立的 Fastify API 容器。但在真实的后端项目中，你的架构大概率是这样的：

1
                Nginx（反向代理）
2
                  │
3
              Fastify API
4
              /          \
5
       PostgreSQL        Redis

即使只是一个中等复杂度的项目，也至少涉及 API 服务、数据库和缓存三个组件。如果手动管理这些容器，你需要执行：

1
docker run -d --name postgres -e POSTGRES_PASSWORD=... -v postgres-data:/var/lib/postgresql/data postgres:17
2
docker run -d --name redis redis:8
3
docker run -d --name api -p 3000:3000 -e DATABASE_URL=... -e REDIS_HOST=... --link postgres --link redis fastify-api
4
docker run -d --name nginx -p 80:80 nginx

每次启动都要记住一长串参数，服务之间的网络连通需要手动配置，环境变量散落在各处，新人入职想跑起项目得先背诵这些命令。Docker Compose 正是为解决这个问题而生的——用一个声明式 YAML 文件描述整个应用栈，然后一条命令启动所有服务。

一、Docker Compose 是什么

Docker Compose 是 Docker 官方提供的多容器编排工具。核心用法很简单：在项目根目录下创建一个 docker-compose.yml 文件，描述项目需要哪些服务、每个服务用什么镜像、端口怎么映射、数据怎么持久化、服务之间怎么通信。之后用 docker compose up 一键启动所有服务，用 docker compose down 一键停止并清理。

一个最简单的 Compose 文件长这样：

1
services:
2
  api:
3
    build: .
4
    ports:
5
      - "3000:3000"
6
  postgres:
7
    image: postgres:17
8
    environment:
9
      POSTGRES_PASSWORD: password
10
    volumes:
11
      - postgres-data:/var/lib/postgresql/data
12
  redis:
13
    image: redis:8
14

15
volumes:
16
  postgres-data:

这个文件定义了三个服务——api、postgres、redis——以及一个数据卷用于持久化数据库文件。不需要记命令参数，不需要手动创建网络，所有配置都在文件中，可以直接提交到 Git 仓库和团队共享。

二、Compose 的四个核心概念

在讲核心概念前，先看一张核心该您总览表

1. Service（服务）

Service 是 Compose 中最基本的概念，每个 service 对应一个容器。比如上面的例子中定义了 api、postgres、redis 三个 service。对于自定义镜像的服务，用 build 指定 Dockerfile 的位置；对于使用官方镜像的服务，直接用 image 指定镜像名称和版本。

2. Network（网络）

Compose 默认会创建一个独立的网络，所有服务自动加入这个网络。在这个网络内部，容器之间可以直接通过服务名互相通信，而不需要使用 IP 地址或 --link。

这意味着你的 Fastify API 可以这样配置数据库连接：

1
DATABASE_URL=postgres://postgres:password@postgres:5432/app
2
REDIS_HOST=redis

注意主机名是 postgres 和 redis——就是 Compose 文件中定义的服务名——而不是 localhost。这是很多初学者第一次部署踩坑的地方：在容器内部，localhost 指向容器自己，而数据库运行在另一个容器中，必须用服务名来访问。Compose 内置的 DNS 会自动将服务名解析为对应容器的内部 IP。

3. Volume（数据卷）

默认情况下，容器删除后容器内的所有数据都会丢失。对于数据库容器而言，这意味着删除 Postgres 容器 → 所有数据消失——这在生产环境中是完全不可接受的。

Volume 用于将容器内的目录映射到宿主机上持久化的存储空间：

1
postgres:
2
  image: postgres:17
3
  volumes:
4
    - postgres-data:/var/lib/postgresql/data

即使容器被删除重建，只要 Volume 还在，数据就不会丢失。

4. Environment（环境变量）

Compose 支持多种方式配置环境变量。可以直接在文件中用 environment 声明，也可以通过 env_file 引用外部 .env 文件：

1
api:
2
  environment:
3
    NODE_ENV: production
4
    DATABASE_URL: postgres://postgres:password@postgres:5432/app
5
  # 或者
6
  env_file:
7
    - .env

推荐把非敏感配置写在 Compose 文件中，敏感信息（如数据库密码）通过外部 .env 文件注入，并确保 .env 在 .gitignore 中。

三、一个完整的 Fastify + PostgreSQL + Redis 项目

下面是一个接近真实项目的 Compose 配置：

1
services:
2
  api:
3
    build:
4
      context: .
5
      dockerfile: Dockerfile
6
    ports:
7
      - "3000:3000"
8
    env_file:
9
      - .env
10
    depends_on:
11
      postgres:
12
        condition: service_healthy
13
      redis:
14
        condition: service_started
15

16
  postgres:
17
    image: postgres:17
18
    env_file:
19
      - .env
20
    volumes:
21
      - postgres-data:/var/lib/postgresql/data
22
    healthcheck:
23
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-appuser} -d ${POSTGRES_DB:-appdb}"]
24
      interval: 10s
25
      timeout: 5s
26
      retries: 5
27

28
  redis:
29
    image: redis:8
30
    volumes:
31
      - redis-data:/data
32

33
volumes:
34
  postgres-data:
35
  redis-data:

对应的 .env 文件：

1
POSTGRES_USER=appuser
2
POSTGRES_PASSWORD=apppassword
3
POSTGRES_DB=appdb
4
DATABASE_URL=postgres://appuser:apppassword@postgres:5432/appdb
5
REDIS_HOST=redis
6
REDIS_PORT=6379

注意几个细节：数据库密码等敏感信息没有直接写在 docker-compose.yml 中，而是通过 env_file 引用外部 .env 文件——和第五篇”不要把密钥写进镜像”的原则保持一致；.env 文件需要加入 .gitignore，避免提交到 Git 仓库。

几个值得注意的细节。depends_on 控制的是服务之间的启动依赖顺序——普通 depends_on 只保证”先启动 Postgres，再启动 API”，但不保证 Postgres 已经准备好接受连接（数据库进程启动了不等于初始化完成了）。加上 condition: service_healthy 配合 healthcheck，才能让 Compose 等待 Postgres 达到 healthy 状态后再启动 API，避免 API 启动时连不上数据库。Postgres 服务通过 pg_isready 命令检测自身是否准备好接受连接，这是 Compose 中推荐的等待数据库就绪的方式。

四、常用命令

1
# 启动所有服务
2
docker compose up
3

4
# 后台运行
5
docker compose up -d
6

7
# 后台运行并在代码变更后重新构建 API 镜像
8
docker compose up -d --build
9

10
# 查看所有服务运行状态
11
docker compose ps
12

13
# 查看所有服务日志
14
docker compose logs
15

16
# 只看 API 服务的日志，并持续跟踪
17
docker compose logs -f api
18

19
# 进入 API 容器
20
docker compose exec api sh
21

22
# 停止所有服务并删除容器和网络（保留数据卷）
23
docker compose down
24

25
# 停止并同时删除数据卷
26
docker compose down -v

其中 docker compose down 和 docker compose down -v 的区别非常关键。docker compose down 停止并删除所有容器和 Compose 自动创建的网络，但保留数据卷——数据库数据不会丢失，下次 docker compose up 时数据还在。docker compose down -v 则会在删除容器和网络的同时删除所有声明的 Volume，这意味着 Postgres 中的数据库数据、Redis 中的数据都会被清空。在生产环境或任何需要保留数据的场景中，使用 -v 之前一定要确认数据已经备份。如果不确定，先用不带 -v 的命令。

看完这个图片你就会对上面的代码更理解了

五、Compose 与手动 docker run 的对比

维度	docker run	Docker Compose
管理对象	单个容器	多个服务
配置方式	命令行参数	YAML 文件
网络配置	手动创建和连接	自动创建，服务名直连
配置复用	靠脚本或文档	YAML 文件直接共享
团队协作	新人需背诵命令	clone 后一行 `docker compose up`
版本控制	无法追溯	随代码一起进入 Git

本质区别在于：docker run 是命令式的——你告诉 Docker”做什么”，参数散落在命令行中；Compose 是声明式的——你告诉 Docker”我想要什么状态”，然后 Docker 去达成它。声明式配置天然更适合团队协作和版本管理。

六、总结

Docker Compose 让多容器应用的管理从一个手动的、易出错的过程，变成了一个可版本控制、可一键启动的配置文件。核心概念只有四个——Service 定义容器、Network 处理通信、Volume 持久化数据、Environment 注入配置——但它们组合起来可以描述任意复杂的应用栈。

完成本篇文章后，你应该能够做到：在项目根目录下放一份 docker-compose.yml，新成员 clone 代码后只需执行 docker compose up 就能跑起完整的开发环境——API、数据库、缓存全部就绪。

至此，Docker 工程化实践系列的”Docker 核心能力”部分已经完成。我们从理解 Docker 的基本原理出发，逐步掌握了镜像分层、Build Cache、多阶段构建、生产镜像优化，最后用 Compose 把多个容器编排成一个完整应用。这些知识覆盖了从本地开发到生产部署的完整链路——接下来可以进一步探索 CI/CD 自动构建部署、Kubernetes 容器编排等更高级的工程化实践。

上一篇：Docker 工程化实践（五）：Docker 镜像优化最佳实践

Atopos