梯子Z 来自巴黎的稳定快速安全ShadowsocksR梯子返回首页

Docker Compose 怎么用?从验证环境到启动、数据卷与排错

更新于 2026-11-22 · zionladderq.shop

简答: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 daemonDocker 引擎未启动启动 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 -d

up 会按配置创建网络和容器,并拉取或构建所需镜像;-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 网络说明。

访问位置正确地址说明
浏览器访问 Weblocalhost:8000使用主机端口 8000
Web 容器访问 Redisredis: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:/dataRedis、数据库和应用状态数据不直接出现在项目目录中
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 路径按实际系统填写。

相关阅读

参考资料

  1. Docker Compose 安装说明
  2. docker compose 命令参考
  3. Docker Compose Quickstart
  4. Compose 网络说明
  5. docker compose exec 参考
  6. docker compose up 参考
  7. docker compose down 参考