Dockerfile 与 Docker Compose 核心知识笔记

一、核心概念与区别

Dockerfile 负责构建镜像,Docker Compose 负责组织和运行容器。

对比 Dockerfile compose.yaml
本质 镜像构建说明书 容器服务编排配置文件
核心作用 定义项目的运行环境、依赖、代码及默认启动命令 定义服务的镜像、端口、环境变量、网络及运行策略
执行阶段 镜像构建阶段 服务部署与运行阶段
核心命令 docker build docker compose up
是否依赖对方 不依赖 Compose 不一定需要 Dockerfile,可以直接使用已有镜像

整体流程:

Dockerfile
    ↓ docker build
Docker Image(镜像)
    ↓ docker run / docker compose up
Docker Container(容器)
    ↓
应用服务运行

注意:Docker Compose 可以调用 Dockerfile 构建镜像,也可以直接拉取和使用已有镜像。

二、Dockerfile 的书写规则

1. 标准编写模板(FastAPI + uv)

# 1. 基础镜像
FROM ghcr.io/astral-sh/uv:0.11.12-python3.12-trixie-slim

# 2. 工作目录
WORKDIR /app

# 3. 环境变量
ENV PYTHONUNBUFFERED=1 \
    UV_PYTHON_DOWNLOADS=0 \
    PATH="/app/.venv/bin:$PATH"

# 4. 复制依赖声明
COPY pyproject.toml uv.lock ./

# 5. 安装项目依赖
RUN uv sync --locked --no-dev --no-install-project

# 6. 复制项目代码
COPY . .

# 7. 同步项目本身
RUN uv sync --locked --no-dev

# 8. 声明端口
EXPOSE 8000

# 9. 默认启动命令
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

假定项目包含有效的 pyproject.toml、uv.lock、app/main.py,且运行依赖中包含 Uvicorn。若项目打包配置要求先读取 README.md 等文件,需要在安装阶段一并复制。

2. 最常用的 Dockerfile 指令

指令 核心作用 书写规则
FROM 选择基础镜像 FROM 镜像:版本
WORKDIR 设置容器工作目录 WORKDIR /app
ENV 设置环境变量 ENV KEY=VALUE
COPY 复制文件到镜像 COPY 源路径 目标路径
RUN 构建镜像时执行命令 RUN 命令
EXPOSE 声明服务端口 EXPOSE 8000
CMD 设置容器默认启动命令 CMD ["命令","参数"]
ENTRYPOINT 设置容器主执行程序 ENTRYPOINT ["命令"]

3. 核心编写规律

FROM → WORKDIR → ENV → COPY 依赖声明 → RUN 安装依赖 → COPY 代码 → CMD 启动

重点掌握三个规则:

规则一:区分构建和运行

RUN 在 docker build 时执行,通常用来安装依赖;CMD 在容器启动时执行,用来启动应用服务。

规则二:充分利用构建缓存

先 COPY 依赖声明,再 RUN 安装依赖,最后 COPY 项目代码。

这样仅修改 Python 代码时,通常可以复用依赖安装层,提高构建效率。

规则三:镜像构建与容器运行环境不是一回事

Dockerfile 的 ENV 可以设置镜像默认环境变量,Compose 可以在容器运行时覆盖这些变量。不要把生产密钥直接写进 Dockerfile。

另外,多个 FROM 代表多个构建阶段,不是将基础镜像依次叠加。

三、Docker Compose 的书写规则

1. 标准编写模板

services:
  api:
    # 1. 镜像配置
    image: crime-message-demo:0.1.0
    build:
      context: .
      dockerfile: Dockerfile

    # 2. 容器运行配置
    restart: unless-stopped
    ports:
      - "8000:8000"

    # 3. 环境变量
    env_file:
      - .env

    # 4. 退出管理
    stop_grace_period: 200s

    # 5. 健康检查
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health/', timeout=3).close()"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

    # 6. 日志管理
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

这里的健康检查要求 FastAPI 实现了 /health/ 接口。

2. 最常用的 Compose 配置

字段 核心作用
services 定义一个或多个服务
image 指定镜像名称和版本
build 配置镜像构建方式
ports 宿主机与容器端口映射
env_file 从文件读取容器环境变量
environment 直接配置容器环境变量
volumes 挂载目录或数据卷,实现数据持久化
networks 配置容器网络
depends_on 声明服务之间的启动依赖
restart 容器退出后的重启策略
healthcheck 定期检测容器服务是否健康
logging 配置容器日志驱动及轮转策略
stop_grace_period 设置容器的优雅退出宽限期

3. 核心书写规律

推荐按照以下逻辑组织配置:

services → image/build → ports → env_file → volumes/networks → depends_on → restart/healthcheck/logging

这是一种推荐组织方式,并不是 YAML 的强制执行顺序。

规则一:YAML 用缩进表示层级关系

services:
  api:
    image: my-api:1.0
    ports:
      - "8000:8000"

  redis:
    image: redis:7

api 和 redis 是两个并列服务。建议统一使用两个空格缩进,不能使用 Tab 缩进。

规则二:明确镜像来源

# 本地构建
build:
  context: .
  dockerfile: Dockerfile
# 使用指定镜像
image: redis:7

image 与 build 可以同时出现。需要明确重新构建时,使用 docker compose up -d --build。

规则三:区分容器内部和宿主机

ports:
  - "8080:8000"

左侧 8080 是宿主机端口,右侧 8000 是容器端口。

在同一个 Compose 默认网络中,服务之间通常通过服务名进行访问,例如 FastAPI 连接 Redis 可以使用 redis:6379。

四、最常用的操作命令

命令 作用
docker build -t myapp:1.0 . 构建镜像
docker images 查看镜像
docker run -d -p 8000:8000 myapp:1.0 通过镜像启动容器
docker ps 查看运行中的容器
docker compose config -q 校验 Compose 配置
docker compose up -d --build 构建并启动所有服务
docker compose ps 查看 Compose 服务
docker compose logs -f api 查看指定服务日志
docker compose restart api 重启指定服务,不重新构建镜像
docker compose down 停止并移除 Compose 容器及默认网络

五、最终记忆总结

Dockerfile:解决怎么打包的问题。

选择运行环境、安装依赖、复制项目代码、设置默认启动命令,最终生成可复用的 Docker 镜像。

Docker Compose:解决怎么部署和管理服务的问题。

定义镜像来源、运行参数、端口、环境变量、网络、数据卷以及多服务之间的关系。

在实际开发中,建议采用下面的习惯:

开发一个 FastAPI / Agent 项目时,先编写 Dockerfile,确保镜像能够独立运行;再编写 compose.yaml,将 FastAPI、Redis、PostgreSQL 等服务统一管理。

这是 Python 后端项目容器化最基础、也是最常用的一套实践。