计算机视觉 / 系统课时

编写 Docker 镜像

编写 Docker 镜像

本课将把 YOLOv5 推理服务需要的 Python 依赖、系统库、应用代码和模型权重封装进同一个镜像,并通过非 root 用户、多阶段构建和本地运行验证,得到可在服务器重复部署的镜像产物。

学习目标

  • 规划适合推理服务的 Docker 构建上下文
  • 使用多阶段构建减小镜像体积并固定运行环境
  • 完成镜像构建、容器启动和关键内容验证

明确镜像封装边界

镜像应包含运行时不可缺少且需要版本固定的内容:Python 解释器、依赖包、系统动态库、服务代码和默认模型。端口映射、日志目录、CPU 与内存限制等主机相关参数不写死在镜像中,而是在启动容器时注入。

YOLOv5 推理镜像的分层结构

构建目录至少需要包含依赖文件、服务包和模型文件。下面假设 Web 服务入口为 app.main:app,模型位于 models/best.pt。

text
yolov5-service/
├── app/
│   ├── __init__.py
│   └── main.py
├── models/
│   └── best.pt
├── requirements.txt
└── Dockerfile

模型文件通常较大,应确认它没有被 .dockerignore 排除。若生产环境需要频繁替换模型,可以只在基础镜像中封装代码,启动时再以只读卷挂载模型;本课采用“代码与默认模型一起发布”的方式,便于得到不可变版本。

编写多阶段 Dockerfile

第一阶段只负责下载并整理 Python wheel,第二阶段安装 wheel 并复制应用文件。这样不会把编译缓存和多余下载文件带入最终镜像。

dockerfile
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 与镜像内默认值一致,这里显式传入是为了展示运行时可覆盖配置。

bash
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

预期结果

text
镜像 yolov5-api:1.0.0 构建成功。
容器以前台方式启动,服务监听 0.0.0.0:8000。
实际构建步骤编号和启动日志会因 Docker 与服务版本不同而变化。

首次加载模型可能需要数秒,启动日志出现监听地址不代表模型一定可用,因此还要验证镜像中的用户、模型和依赖。

验证镜像内容

下面的命令覆盖默认启动命令,仅执行一次环境检查。它会确认容器不是以 root 身份运行,并检查模型文件是否存在。

bash
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())"

预期输出

text
10001
True

若第二行是 False,优先检查 COPY models ./models 的源目录、文件名大小写和 .dockerignore。若导入 OpenCV 时提示缺少共享库,应根据实际报错补充系统包,而不是把完整桌面环境安装进镜像。

本课总结

  • 镜像负责固定依赖、代码和默认模型,主机相关运行参数留到容器启动阶段配置
  • 多阶段构建可以减少缓存与构建工具进入最终镜像,非 root 用户可降低运行风险
  • 构建成功后还要验证模型文件、依赖和运行用户,不能只看服务启动日志

下一课预告

下一课将把端口、日志轮转、文件描述符限制、健康检查、资源上限和模型挂载路径整理为可直接用于生产环境的运行配置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写 Docker 镜像

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通