AI 内容创作 / 系统课时
Docker 容器化部署
Docker 容器化部署
数字人服务通常依赖 Python 包、系统库、模型文件、GPU 运行时和外部配置,直接在服务器上手工安装容易产生环境漂移。本课构建一个最小 FastAPI 镜像,明确镜像层、配置注入、模型挂载、非 root 运行、健康检查与 GPU 启动边界,并完成可重复的构建和接口验证。
学习目标
- 能够区分应写入镜像的代码依赖与应在运行时挂载的模型、缓存和配置。
- 能够编写包含非 root 用户、健康检查和稳定启动命令的 Dockerfile。
- 能够构建、启动并验证容器,同时理解 GPU 运行时和持久化目录的要求。
镜像与运行时边界
镜像应包含应用代码、确定的 Python 依赖和必要系统库,使同一镜像能够在测试与生产环境中重复启动。模型权重通常体积大、更新频繁,适合通过只读卷或启动时下载到受控缓存;会话缓存、生成结果和日志属于运行数据,应写入可持久化卷或外部服务。密钥不得写入 Dockerfile、镜像层或代码仓库,而应通过环境变量或编排平台的密钥机制注入。

部署时还要保持 CPU 架构、驱动、CUDA 运行时和推理框架兼容。GPU 驱动位于宿主机,容器通常只携带与框架匹配的用户态运行库;启用 GPU 需要宿主机安装可用的容器运行时工具,并在启动时显式授予设备访问权限。镜像能成功构建不代表 GPU 推理一定可用,仍需在目标节点执行设备探测和最小推理验证。
完整容器化示例
示例目录如下。先保留第 01 课的 app/main.py。以下包装器增加就绪探针,检查只读模型目录里的教学标记可读,以及缓存目录可创建临时文件。保存为 app/deploy.py。
import os
from pathlib import Path
from tempfile import TemporaryFile
from fastapi.responses import JSONResponse
from app.main import app
MODEL_DIR = Path(os.getenv("MODEL_DIR", "/models"))
CACHE_DIR = Path(os.getenv("CACHE_DIR", "/data/cache"))
@app.get("/readyz")
def ready():
try:
if len(os.getenv("DEMO_TOKEN", "")) < 16:
raise ValueError
with (MODEL_DIR / "demo.ready").open("rb") as marker:
if marker.read(32).strip() != b"demo-ready-v1":
raise ValueError
with TemporaryFile(dir=CACHE_DIR) as test:
test.write(b"ok")
except (OSError, ValueError):
return JSONResponse({"status": "not_ready"}, status_code=503)
return {"status": "ready"}生产就绪应依据目标模型的加载状态或受控探测。课堂标记只验证目录读写和身份配置,不代表实际模型已经加载。/healthz 是进程存活检查。
在根目录保存 requirements.txt,版本与第 01 课一致。
fastapi==0.162.0
uvicorn==0.54.0.dockerignore 排除运行数据及本地配置。生产还应使用审查过的构建上下文、不可变镜像摘要与完整依赖锁。
.git/
.venv/
**/__pycache__/
.env
models/
data/Dockerfile 使用非 root 用户。命名卷保存缓存,模型由宿主机挂载。运行时要检查容器 UID 对实际挂载路径的权限。
FROM python:3.11-slim
ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
WORKDIR /srv
RUN groupadd --gid 10001 app && useradd --uid 10001 --gid 10001 --no-create-home app \
&& mkdir -p /models /data/cache && chown 10001:10001 /data/cache
COPY requirements.txt ./
RUN python -m pip install --no-cache-dir -r requirements.txt
COPY app ./app
USER 10001:10001
EXPOSE 8000
HEALTHCHECK --interval=10s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=2).close()"
CMD ["python","-m","uvicorn","app.deploy:app","--host","0.0.0.0","--port","8000"]构建与验收
以下为 Bash 演练命令。先停止占用同一端口的本地 Uvicorn,令牌只用于课堂。
mkdir -p models
printf 'demo-ready-v1\n' > models/demo.ready
export DEMO_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(24))')"
docker build -t digital-human-api:demo .
docker run -d --rm --name digital-human-api -e DEMO_TOKEN \
-p 127.0.0.1:8000:8000 \
--mount "type=bind,src=$PWD/models,dst=/models,readonly" \
--mount "type=volume,src=digital-human-cache,dst=/data/cache" \
digital-human-api:demo
curl -fsS --retry 8 --retry-connrefused --retry-delay 1 --max-time 3 \
http://127.0.0.1:8000/healthz
curl -fsS --max-time 3 http://127.0.0.1:8000/readyz
curl -fsS -X POST http://127.0.0.1:8000/sessions \
-H "Authorization: Bearer $DEMO_TOKEN" -H 'Idempotency-Key: container-qa'
docker stop digital-human-api探针分别返回 {"status":"alive"} 和 {"status":"ready"},创建会话返回 201 与新 ID。可移除教学标记后复测,存活仍通过、就绪应失败。已有卷可能保留旧权限,首次或升级后均应以容器 UID 实查缓存可写性。教学命名卷在容器退出后仍保留。
部署 GPU 版本时按宿主驱动、容器工具与 CUDA/框架的兼容矩阵选择镜像,授予所需设备后执行实际小批推理。设备可见只能证明枚举成功。上线前保留上一版镜像摘要与配置,并验证就绪探针、受权业务路径和回滚步骤。