Docker Compose 怎么用?从验证环境到启动、数据卷与排错
简答:Docker Compose 的用法可以概括为:准备 Docker 环境,创建 compose.yaml,用 docker compose up -d 启动服务,再用 ps、logs、exec 排查运行状态。下面用一个 Web + Redis 示例跑通创建、启动、访问、停止和数据持久化;容器之间通信时使用服务名 redis,不要把 localhost 当成另一个容器。
定义:Docker Compose 是用一个 YAML 配置文件定义并管理多个相关容器、网络、端口和数据卷的命令行工具。
先做这一步:验证 Docker Compose 是否可用
如果你已经安装 Docker Desktop,Compose 通常会随 Docker Engine 和 Docker CLI 一起提供;Linux 也可以在已有 Docker Engine 与 CLI 的情况下单独安装 Compose 插件。安装方式应按系统和现有环境选择,具体可参考 Docker Compose 安装说明。
先打开 PowerShell、CMD、macOS 或 Linux 终端,执行下面的检查命令:
docker version
docker compose version
docker info三条命令中,docker compose version 用来确认 Compose 子命令存在,docker info 用来确认 Docker 引擎正在运行。若提示无法连接 Docker daemon,先启动 Docker Desktop,或检查 Linux 上的 Docker 服务和当前用户权限。
| 检查结果 | 常见原因 | 处理方式 |
|---|---|---|
| 提示 docker 不是命令 | Docker CLI 未安装,或终端没有读取到 PATH | 重新安装 Docker Desktop 或 Docker CLI,关闭并重新打开终端后再试 |
| docker compose 不是有效子命令 | Compose 插件未安装,或使用的是较旧的独立命令环境 | 优先安装 Compose 插件,并使用 docker compose 格式 |
| Cannot connect to the Docker daemon | Docker 引擎未启动 | 启动 Docker Desktop,或检查 Linux Docker 服务状态 |
| 能显示版本但无法拉取镜像 | 网络、DNS、代理或镜像仓库连接异常 | 先执行 docker pull redis:alpine,再查看具体错误信息 |
本文使用当前 Compose 命令格式 docker compose。旧资料中的 docker-compose 是另一种命令写法,不要把两种格式混在同一组排查命令中。
创建第一个项目:Web 加 Redis 的最小示例
Compose 文件通常放在项目目录中,文件名可以使用 compose.yaml 或兼容旧项目的 docker-compose.yaml。如果没有使用 -f 指定路径,Compose 会在当前目录及父目录中查找配置文件;命令行为可参考 docker compose 命令参考。
先创建目录并进入项目目录:
mkdir compose-demo
cd compose-demo下面的示例包含一个由本地 Dockerfile 构建的 Web 服务和一个 Redis 服务。Web 服务通过环境变量读取 Redis 的服务名和端口,Redis 使用命名数据卷保存数据。
创建 .env:
APP_PORT=8000
REDIS_HOST=redis
REDIS_PORT=6379创建 requirements.txt:
flask
redis创建 app.py:
import os
import redis
from flask import Flask
app = Flask(__name__)
client = redis.Redis(
host=os.getenv("REDIS_HOST", "redis"),
port=int(os.getenv("REDIS_PORT", "6379")),
decode_responses=True,
)
@app.route("/")
def index():
count = client.incr("hits")
return f"Hello from Docker Compose. Visits: {count}\n"
创建没有扩展名的 Dockerfile:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 5000
CMD ["python", "-m", "flask", "run", "--host=0.0.0.0", "--port=5000"]最后创建 compose.yaml。代码块请整体复制,YAML 依靠缩进表达层级,不要把它拆成列表或逐行粘贴:
services:
web:
build: .
ports:
- "${APP_PORT}:5000"
environment:
REDIS_HOST: ${REDIS_HOST}
REDIS_PORT: ${REDIS_PORT}
depends_on:
redis:
condition: service_healthy
redis:
image: redis:alpine
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 5
start_period: 10s
volumes:
- redis-data:/data
volumes:
redis-data:这个结构中,services 定义要运行的服务;image 直接使用已有镜像;build 根据 Dockerfile 构建镜像;ports 把主机端口映射到容器端口;environment 注入配置;depends_on 表示启动依赖;volumes 用于保存需要跨容器重建保留的数据。
官方快速入门也采用 Web 与 Redis 的组合来演示服务依赖、环境变量、健康检查和 docker compose exec,可对照 Docker Compose Quickstart。
启动、访问和停止:最常用的 Compose 命令
在包含 compose.yaml 的目录执行配置检查:
docker compose config如果配置可以被解析,再后台启动服务:
docker compose up -dup 会按配置创建网络和容器,并拉取或构建所需镜像;-d 表示后台运行。启动后访问 http://localhost:8000,刷新页面可以看到计数变化。关于 up 的创建、重建、后台运行行为,可查看 docker compose up 参考。
建议按下面顺序检查项目:
docker compose ps
docker compose logs --tail=100
docker compose logs -f web
docker compose images
docker compose volumes常用命令可以这样记:
| 命令 | 作用 | 适合什么时候用 |
|---|---|---|
docker compose up -d | 创建并后台启动服务 | 首次启动或配置变更后运行 |
docker compose ps | 查看容器状态和端口 | 确认服务是否运行 |
docker compose logs -f web | 持续查看 Web 日志 | 页面打不开或应用反复退出 |
docker compose stop | 停止服务但保留容器 | 暂时停止,不想删除当前容器 |
docker compose start | 启动已经存在的停止容器 | 配合 stop 使用 |
docker compose restart web | 重启指定服务 | 只重启一个服务 |
docker compose pull | 拉取配置中引用的镜像 | 更新镜像前先同步内容 |
docker compose build | 重新构建本地服务镜像 | Dockerfile 或构建目录发生变化 |
docker compose down | 停止并删除容器和项目网络 | 结束本次项目运行 |
如果只想在容器中执行一次命令,可以使用 docker compose exec。它要求目标服务已经运行,并且默认分配交互终端;脚本或非交互场景可加 -T。命令格式和参数可参考 docker compose exec 参考。
docker compose exec web python -c "print('web ok')"
docker compose exec redis redis-cli ping
docker compose exec -T web python -c "import os; print(os.getenv('REDIS_HOST'))"
容器网络怎么理解:服务名能通,localhost 不代表另一个容器
Compose 默认会为同一个项目创建网络,并让服务通过服务名互相发现。上面的 Web 容器访问 Redis 时应该使用 redis:6379,而不是 localhost:6379。因为在 Web 容器内部,localhost 指向 Web 容器自己;它不会自动指向 Redis。
Docker 官方网络说明明确区分了容器间端口和主机端口:容器之间使用目标服务的容器端口,主机访问则使用映射后的主机端口。可查看 Compose 网络说明。
| 访问位置 | 正确地址 | 说明 |
|---|---|---|
| 浏览器访问 Web | localhost:8000 | 使用主机端口 8000 |
| Web 容器访问 Redis | redis:6379 | 使用 Compose 服务名和容器端口 |
| 宿主机直接访问 Redis | 默认不需要访问 | 示例没有把 Redis 端口发布到宿主机 |
可以进入 Web 容器查看环境变量:
docker compose exec web sh -c 'echo "$REDIS_HOST:$REDIS_PORT"'也可以从 Redis 容器确认服务本身正常:
docker compose exec redis redis-cli ping如果返回 PONG,说明 Redis 进程已响应。若 Web 仍然报连接错误,继续查看 docker compose logs web,重点检查环境变量、服务名、端口和启动时序。
数据卷、bind mount 与 down -v 的区别
Compose 中常见的持久化方式有两种:命名数据卷和 bind mount。命名数据卷由 Docker 管理,适合数据库、Redis 等应用数据;bind mount 把主机目录挂载到容器,适合本地代码、配置文件或需要直接编辑的内容。
| 方式 | 示例 | 适用场景 | 注意事项 |
|---|---|---|---|
| 命名数据卷 | redis-data:/data | Redis、数据库和应用状态 | 数据不直接出现在项目目录中 |
| bind mount | ./src:/app/src | 本地开发、热更新和编辑配置 | 主机路径、权限和文件共享设置必须正确 |
如果要给 Web 服务增加本地代码挂载,可以使用下面的写法,但它可能覆盖镜像内已有文件,因此应确认主机目录内容完整:
services:
web:
build: .
volumes:
- ./app.py:/app/app.py停止和清理时要分清两个命令:
docker compose stop
docker compose down
docker compose down -v- stop:停止服务,容器仍然保留。
- down:删除项目容器和网络,命名数据卷默认保留。
- down -v:连同 Compose 文件中声明的命名数据卷一起删除,Redis 或数据库数据会被清除。
官方 docker compose down 说明明确列出 -v 的数据卷删除行为;在调试数据持久化时,不要把它当作普通停止命令使用。
启动失败怎么排查:现象→原因→处理
| 现象 | 可能原因 | 处理步骤 |
|---|---|---|
yaml: mapping values are not allowed 或缩进错误 | 空格层级错误、Tab 缩进、冒号后缺少空格 | 执行 docker compose config;用空格替代 Tab;对照完整代码块检查层级 |
| 端口已被占用 | 主机的 8000 端口已有程序监听 | Windows 执行 netstat -ano | findstr :8000;macOS 或 Linux 执行 lsof -i :8000;也可以把 .env 中的 APP_PORT 改为其他端口 |
| Web 容器反复退出 | 应用启动异常、依赖未安装、Redis 尚未就绪 | 执行 docker compose logs web;再执行 docker compose ps 和 docker compose logs redis |
| Web 连接不上 Redis | 把服务名写成 localhost,或变量未加载 | 确认 REDIS_HOST=redis;执行 docker compose exec web sh -c 'echo $REDIS_HOST';不要使用 localhost:6379 |
| 镜像拉取超时或解析失败 | DNS、代理、出口网络或镜像仓库连接问题 | 先执行 docker pull redis:alpine;再检查 Docker 引擎的 DNS 和代理设置,不要只重复运行 up |
| 修改代码后页面没有变化 | 文件没有挂载,或镜像没有重新构建 | 确认 bind mount 路径;需要构建时执行 docker compose up -d --build |
执行 exec 提示服务未运行 | 容器已经退出或服务名写错 | 先执行 docker compose ps -a 和 docker compose logs 服务名,确认服务名称后再进入 |
| 清理后 Redis 计数归零 | 执行了 docker compose down -v,删除了命名数据卷 | 需要保留数据时只使用 down,并在重要环境建立独立备份流程 |
如果命令在 Windows PowerShell、CMD、macOS 或 Linux 上表现不同,先确认当前终端的引号和路径写法。Compose 文件中的容器路径仍使用 Linux 风格,例如 /data;主机 bind mount 的路径则应按实际系统格式填写。
本地开发与长期运行:哪些配置需要加固
上面的示例适合学习和本地开发,不应直接当作长期运行配置。至少检查以下事项:
- 固定镜像版本:开发时可以使用便于更新的标签,长期运行时应根据发布流程固定可追踪的镜像版本,避免同一配置在不同时间拉到不同内容。
- 不要公开数据库端口:服务之间可以通过 Compose 网络通信,只有确实需要从主机访问时才发布数据库端口。
- 不要把密码直接提交:
.env适合管理本地配置,但包含密码的文件不要提交到公共代码仓库。 - 配置健康检查:进程启动不等于服务已经可以接受请求,数据库或缓存应有可执行的健康检查。
- 区分 stop 与 down -v:清理环境前先确认数据是否需要保留。
- 准备恢复方案:命名数据卷能减少容器重建造成的数据丢失,但它不是自动备份;重要数据仍需要定期导出和恢复演练。
Compose 适合把一组有关联的容器放在同一份配置中管理;Dockerfile 负责描述单个镜像如何构建,docker run 适合临时或单容器启动。理解这三者的边界后,遇到启动失败时可以更快判断问题是在镜像构建、容器运行,还是 Compose 编排层。
Docker Compose 命令速查
# 检查环境
docker version
docker compose version
docker info
# 检查并启动
docker compose config
docker compose up -d
docker compose up -d --build
# 查看状态与日志
docker compose ps
docker compose ps -a
docker compose logs --tail=100
docker compose logs -f web
# 进入容器或执行一次性命令
docker compose exec web sh
docker compose exec redis redis-cli ping
docker compose exec -T web python -c "print('ok')"
# 生命周期
docker compose stop
docker compose start
docker compose restart web
docker compose down
docker compose down -v
# 镜像、文件和数据卷
docker compose pull
docker compose build
docker compose images
docker compose volumes如果只记三条,先记 docker compose up -d、docker compose ps 和 docker compose logs。它们分别解决启动、确认状态和查看错误信息三个最常见的步骤。
常见问题
Docker Compose 怎么启动项目?
进入包含 compose.yaml 的目录,先执行 docker compose config 检查配置,再执行 docker compose up -d。启动后用 docker compose ps 查看容器状态。
docker compose 和 docker-compose 有什么区别?
docker compose 是当前推荐的 Docker CLI 子命令格式;docker-compose 是旧的独立命令写法。新项目优先使用 docker compose,旧项目则按实际安装环境处理。
Compose 文件必须叫 compose.yaml 吗?
不一定。Compose 会查找 compose.yaml 或 docker-compose.yaml,也可以用 docker compose -f 文件路径明确指定配置文件。
容器之间为什么不能用 localhost 连接?
因为每个容器都有自己的网络命名空间。容器访问同一 Compose 项目中的其他服务时,应使用服务名和容器端口,例如 redis:6379;localhost 只代表当前容器本身。
docker compose down 会删除数据吗?
默认会删除项目容器和网络,但 Compose 声明的命名数据卷通常保留。docker compose down -v 会删除命名数据卷,可能清空 Redis 或数据库数据。
docker compose exec 和 docker compose run 有什么区别?
exec 在已经运行的容器内执行命令;run 会按服务配置创建一次性容器,适合执行迁移、测试等任务。run 默认不会创建服务中声明的端口映射。
为什么修改 Dockerfile 后容器里还是旧内容?
修改 Dockerfile 或构建目录后,需要执行 docker compose up -d --build 或先执行 docker compose build,再重新启动服务。
Windows、macOS 和 Linux 使用 Compose 命令一样吗?
主要 Compose 子命令一致,但路径、引号、权限和 Docker 引擎启动方式可能不同。YAML 中的容器路径保持 Linux 风格,主机 bind mount 路径按实际系统填写。