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 后端项目容器化最基础、也是最常用的一套实践。