第 48 课 | Docker 容器化：一键部署到任何机器

将完整项目打包为 Docker 镜像——环境一致、迁移无忧、一条命令启动。从开发环境到生产部署，完成最后一公里。

---

一、业务痛点：环境不一致的噩梦

“在我电脑上能跑啊”——这是软件开发中最常见也最令人头疼的问题。

你的开发环境是 Windows 10 + RTX 3090 + CUDA 12.1，而生产服务器可能是 Ubuntu 22.04 + A100 + CUDA 11.8。Python 版本、CUDA 版本、驱动版本、系统库版本……任何一个差异都可能导致部署失败。

Docker 的解决方案：将应用及其所有依赖（包括系统库、Python 环境、模型文件）打包成一个「镜像」，在任何支持 Docker 的机器上运行，保证环境完全一致。

没有 Docker 的部署流程：
1. 在服务器上安装 Python 3.12
2. 安装 CUDA 和 cuDNN
3. 安装 UV
4. 克隆代码
5. 运行 uv sync
6. 调试各种依赖冲突
7. 配置环境变量
8. 祈祷能跑通 → 通常需要 2-4 小时

有 Docker 的部署流程：
1. docker-compose up -d
2. 完成 → 2 分钟

---

二、Docker 核心概念

核心概念：

• Dockerfile：描述如何构建镜像的文本文件
• Image（镜像）：包含应用和所有依赖的只读模板
• Container（容器）：镜像的运行实例，互相隔离
• docker-compose：编排多个容器（如 App + Ollama + 数据库）

---

三、Dockerfile 详解

3.1 基础 Dockerfile

# 基础镜像：Python 3.12 精简版
FROM python:3.12-slim

# 设置工作目录
WORKDIR /app

# 安装系统依赖（如需要编译的包）
RUN apt-get update && apt-get install -y \
    build-essential \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 安装 UV 包管理器
RUN pip install uv

# 先复制依赖文件（利用 Docker 缓存层）
COPY pyproject.toml uv.lock* ./

# 复制项目代码
COPY agent-kit/ agent-kit/
COPY code/ code/

# 安装 Python 依赖
RUN uv sync --frozen

# 暴露端口
EXPOSE 8501

# 启动命令
CMD ["uv", "run", "streamlit", "run", "code/lesson-46-streamlit-web/streamlit_app.py"]

3.2 多阶段构建（优化镜像大小）

# === 构建阶段 ===
FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install uv
COPY pyproject.toml uv.lock* ./
COPY agent-kit/ agent-kit/
COPY code/ code/
RUN uv sync --frozen --no-dev

# === 运行阶段（更小的镜像）===
FROM python:3.12-slim AS runner
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/agent-kit /app/agent-kit
COPY --from=builder /app/code /app/code
EXPOSE 8501
CMD ["/app/.venv/bin/python", "-m", "streamlit", "run", "code/lesson-46-streamlit-web/streamlit_app.py"]

3.3 .dockerignore（排除不需要的文件）

# .dockerignore
__pycache__/
*.pyc
.git/
.vscode/
.idea/
*.md
.env
.env.local
models/          # 大模型文件不打包进镜像
data/raw/        # 原始数据

---

四、docker-compose.yml 多容器编排

version: '3.8'

services:
  # === 主应用 ===
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8501:8501"
    environment:
      - LLM_BACKEND=ollama
      - OLLAMA_HOST=http://ollama:11434
      - CHROMA_HOST=http://chromadb:8000
    depends_on:
      - ollama
      - chromadb
    volumes:
      - ./data:/app/data          # 数据持久化
      - ./logs:/app/logs          # 日志持久化
    restart: unless-stopped

  # === Ollama 本地模型服务 ===
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama  # 模型文件持久化
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    restart: unless-stopped

  # === ChromaDB 向量数据库 ===
  chromadb:
    image: chromadb/chroma:latest
    ports:
      - "8000:8000"
    volumes:
      - chroma_data:/chroma/chroma
    environment:
      - IS_PERSISTENT=TRUE
    restart: unless-stopped

volumes:
  ollama_data:
  chroma_data:

---

五、部署实战

5.1 构建和启动

# 1. 构建镜像
docker build -t ai-agent-tutorial .

# 2. 启动所有服务
docker-compose up -d

# 3. 查看运行状态
docker-compose ps

# 4. 查看日志
docker-compose logs -f app

# 5. 浏览器打开
# http://localhost:8501

5.2 常用管理命令

# 停止服务
docker-compose down

# 重新构建并启动
docker-compose up -d --build

# 查看资源使用
docker stats

# 进入容器调试
docker exec -it ai-agent-tutorial-app-1 bash

# 清理未使用的镜像和容器
docker system prune -a

5.3 GPU 支持配置

# 安装 NVIDIA Container Toolkit（Linux）
# Ubuntu/Debian:
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
    sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

# 验证 GPU 可用
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

---

六、生产环境最佳实践

实践	说明
使用 .dockerignore	减少构建上下文，加速构建
多阶段构建	最终镜像只包含运行时依赖
健康检查	自动检测容器是否正常运行
资源限制	限制 CPU/内存，防止 OOM
日志轮转	配置 docker 日志大小限制
非 root 运行	安全最佳实践
版本标签	不要用 latest，用语义化版本

健康检查配置

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
    CMD curl -f http://localhost:8501/_stcore/health || exit 1

---

七、运行

cd code/lesson-48-docker
# 查看 Dockerfile 和 docker-compose.yml
# 构建并启动: docker-compose up -d

---

八、本课小结

1. Docker 解决「在我电脑上能跑」的问题，保证环境一致
2. Dockerfile 定义镜像构建过程，多阶段构建优化大小
3. docker-compose 编排多个服务（App + Ollama + ChromaDB）
4. GPU 支持需要安装 NVIDIA Container Toolkit
5. 生产环境遵循最佳实践：健康检查、资源限制、非 root 运行

配套代码：code/lesson-48-docker/（含完整 Dockerfile 和 docker-compose.yml）