52.Docker部署大模型应用从本地开发到服务化运行

Docker 部署大模型应用：从本地开发到服务化运行

码海寻道 · 大模型、智能体与 RAG 工程组件系列第 52 篇

大模型应用通常包含 API、前端、Worker、PostgreSQL、Redis、对象存储和向量数据库。直接在开发机上逐个安装，换一台机器就可能遇到 Python、Node、系统库和环境变量差异。Docker 的价值是把运行环境和服务边界固定下来。

一、先区分镜像和容器

text 复制代码

Dockerfile → Image 镜像 → Container 容器

镜像是可分发的应用模板，容器是镜像的运行实例。数据库和对象存储的数据不应只存在容器可写层，而要挂载 Volume 或使用外部持久化服务。

二、FastAPI 镜像示例

dockerfile 复制代码

FROM python:3.12-slim

WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

EXPOSE 8000
CMD ["fastapi", "run", "app/main.py", "--port", "8000"]

依赖应在构建阶段安装，容器启动时不要执行 pip install。生产镜像还应使用非 root 用户、固定依赖版本和多阶段构建减少体积。

构建过程还要固定基础镜像摘要或定期重建，生成 SBOM 并扫描系统包和 Python 依赖。容器运行时使用只读根文件系统、丢弃不必要的 Linux capabilities，并通过资源限制防止一次模型请求耗尽整台机器。

三、前端和 Worker 要分开

text 复制代码

frontend：构建静态资源并由 Nginx 提供
api：处理 HTTP、鉴权和流式响应
worker：处理解析、OCR、Embedding 和索引任务

API 和 Worker 可能使用相同代码仓库，但启动命令、资源限制和伸缩方式不同，不建议强行放进同一个进程。

四、Docker Compose 管理本地依赖

yaml 复制代码

services:
  api:
    build: .
    command: fastapi run app/main.py --port 8000
    ports: ["8000:8000"]
    env_file: [.env]
    depends_on:
      postgres:
        condition: service_healthy

  worker:
    build: .
    command: python -m app.worker
    env_file: [.env]

  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: rag
      POSTGRES_USER: rag
      POSTGRES_PASSWORD: change-me
    volumes: ["postgres-data:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U rag -d rag"]

volumes:
  postgres-data:

示例用于本地和测试环境。生产环境应使用密钥管理、备份和明确的数据库版本策略，不要把真实密码提交到仓库。

Compose 中的健康依赖只表示启动顺序，不代表业务已经可用。数据库迁移、索引初始化和 Worker 就绪应由应用或发布流程显式检查；生产环境还要明确谁负责备份、升级、恢复和数据持久化，不要把本地 Compose 文件直接当作高可用方案。

五、环境变量和密钥

text 复制代码

DATABASE_URL
REDIS_URL
MILVUS_URI
S3_ENDPOINT
LLM_API_KEY

配置和密钥分离：普通配置可以通过环境变量注入，敏感凭据应使用 Docker Secrets、云密钥管理或部署平台的 Secret。日志中不要打印完整连接串和 API Key。

六、健康检查不是简单进程检查

建议提供：

http 复制代码

GET /health/live   # 进程是否存活
GET /health/ready  # 是否可以接收流量

ready 可以检查数据库连接、迁移状态和必要依赖，但不应把所有下游短暂波动都变成容器重启。健康检查本身也要设置合理超时。

建议分开 /live 和 /ready：存活检查只判断进程是否还能工作，就绪检查判断是否接收流量。模型供应商短暂不可用时，API 可以保持存活并进入降级，而不是被探针反复重启；Worker 则应通过租约和队列状态判断是否能安全接管任务。

七、构建和发布流程

text 复制代码

提交代码
  ↓
CI：测试、构建镜像、漏洞扫描
  ↓
推送带版本号的镜像
  ↓
部署到测试环境
  ↓
冒烟与回归测试
  ↓
生产滚动更新

镜像应使用 Git SHA、版本号或不可变 Digest，不要在生产环境长期使用 latest。

发布时应记录镜像 Digest、配置版本、数据库迁移版本、Prompt/模型版本和依赖服务地址。回滚前先确认数据库 Schema、对象格式和向量索引仍兼容；代码回滚不等于数据回滚，必要时采用向后兼容迁移和双读/双写过渡。

八、数据和容器生命周期

容器可以随时重建，数据不能依赖容器本身：

PostgreSQL 使用持久卷或托管数据库；
Redis 根据会话和缓存重要性配置持久化；
MinIO 使用持久卷和备份；
Milvus 配置对象存储和元数据存储；
日志输出到标准输出并由平台收集。

容器被删除不应影响业务数据。要验证重启、节点故障、磁盘满、网络分区和备份恢复；临时文件、上传分片和失败任务要有清理策略，避免容器层或持久卷长期堆积。

九、生产检查清单

镜像可重复构建且依赖已锁定；
容器以非 root 用户运行；
API、Worker 和前端职责分离；
密钥不写入镜像和 Git；
有存活、就绪和关闭策略；
数据使用持久化存储和备份；
镜像有漏洞扫描和版本回滚；
日志、指标和 Trace 可关联。

结语

Docker 让大模型应用的运行环境、服务边界和发布流程更加可重复，但它不自动解决数据持久化、密钥、监控和高可用。先用 Compose 固定本地和单机部署，再根据规模决定是否进入 Kubernetes。

下一篇将介绍 Nginx、API Gateway 和鉴权如何保护大模型接口。

参考资料

本文为"码海寻道"原创技术文章。镜像、Compose 和部署方式会随版本变化，生产部署请结合目标环境验证。