计算机视觉 / 系统课时
编写 Docker 镜像
编写 Docker 镜像
本课将把 YOLOv5 推理服务需要的 Python 依赖、系统库、应用代码和模型权重封装进同一个镜像,并通过非 root 用户、多阶段构建和本地运行验证,得到可在服务器重复部署的镜像产物。
学习目标
- 规划适合推理服务的 Docker 构建上下文
- 使用多阶段构建减小镜像体积并固定运行环境
- 完成镜像构建、容器启动和关键内容验证
明确镜像封装边界
镜像应包含运行时不可缺少且需要版本固定的内容:Python 解释器、依赖包、系统动态库、服务代码和默认模型。端口映射、日志目录、CPU 与内存限制等主机相关参数不写死在镜像中,而是在启动容器时注入。

构建目录至少需要包含依赖文件、服务包和模型文件。下面假设 Web 服务入口为 app.main:app,模型位于 models/best.pt。
yolov5-service/
├── app/
│ ├── __init__.py
│ └── main.py
├── models/
│ └── best.pt
├── requirements.txt
└── Dockerfile模型文件通常较大,应确认它没有被 .dockerignore 排除。若生产环境需要频繁替换模型,可以只在基础镜像中封装代码,启动时再以只读卷挂载模型;本课采用“代码与默认模型一起发布”的方式,便于得到不可变版本。
编写多阶段 Dockerfile
第一阶段只负责下载并整理 Python wheel,第二阶段安装 wheel 并复制应用文件。这样不会把编译缓存和多余下载文件带入最终镜像。
FROM python:3.11-slim AS builder
ENV PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /build
COPY requirements.txt .
# 先生成 wheel,运行阶段无需再次访问软件仓库
RUN python -m pip install --upgrade pip \
&& python -m pip wheel --wheel-dir /wheels -r requirements.txt
FROM python:3.11-slim AS runtime
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
MODEL_PATH=/app/models/best.pt \
PORT=8000 \
WORKERS=1
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
curl \
libgl1 \
libglib2.0-0 \
&& rm -rf /var/lib/apt/lists/* \
&& useradd --create-home --uid 10001 appuser
WORKDIR /app
COPY --from=builder /wheels /wheels
COPY requirements.txt .
RUN python -m pip install --no-index --find-links=/wheels -r requirements.txt \
&& rm -rf /wheels
COPY app ./app
COPY models ./models
RUN chown -R appuser:appuser /app
USER appuser
EXPOSE 8000
CMD ["sh", "-c", "exec python -m uvicorn app.main:app --host 0.0.0.0 --port ${PORT} --workers ${WORKERS}"]如果使用 NVIDIA GPU,基础镜像、宿主机驱动和 PyTorch CUDA 版本必须匹配,不能直接把 CPU 镜像中的 Python 依赖复制到任意 CUDA 镜像。无论选择 CPU 还是 GPU,都应在 requirements.txt 中固定关键依赖版本,避免同一 Dockerfile 在不同日期构建出不同环境。
构建并启动容器
在项目根目录执行构建,再把容器的 8000 端口映射到主机 8000 端口。MODEL_PATH 与镜像内默认值一致,这里显式传入是为了展示运行时可覆盖配置。
docker build -t yolov5-api:1.0.0 .
docker run --rm \
--name yolov5-api \
-p 8000:8000 \
-e MODEL_PATH=/app/models/best.pt \
yolov5-api:1.0.0预期结果
镜像 yolov5-api:1.0.0 构建成功。
容器以前台方式启动,服务监听 0.0.0.0:8000。
实际构建步骤编号和启动日志会因 Docker 与服务版本不同而变化。首次加载模型可能需要数秒,启动日志出现监听地址不代表模型一定可用,因此还要验证镜像中的用户、模型和依赖。
验证镜像内容
下面的命令覆盖默认启动命令,仅执行一次环境检查。它会确认容器不是以 root 身份运行,并检查模型文件是否存在。
docker run --rm \
--entrypoint python \
yolov5-api:1.0.0 \
-c "import os, pathlib; print(os.getuid()); print(pathlib.Path(os.environ['MODEL_PATH']).is_file())"预期输出
10001
True若第二行是 False,优先检查 COPY models ./models 的源目录、文件名大小写和 .dockerignore。若导入 OpenCV 时提示缺少共享库,应根据实际报错补充系统包,而不是把完整桌面环境安装进镜像。
本课总结
- 镜像负责固定依赖、代码和默认模型,主机相关运行参数留到容器启动阶段配置
- 多阶段构建可以减少缓存与构建工具进入最终镜像,非 root 用户可降低运行风险
- 构建成功后还要验证模型文件、依赖和运行用户,不能只看服务启动日志
下一课预告
下一课将把端口、日志轮转、文件描述符限制、健康检查、资源上限和模型挂载路径整理为可直接用于生产环境的运行配置。