第 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镜像构建蓝图 docker build构建镜像 Docker Image只读模板▶️ docker run启动容器 Container运行的实例 docker-compose.yml多容器编排docker-compose up多个容器协同核心概念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 --frombuilder /app/.venv /app/.venv COPY --frombuilder /app/agent-kit /app/agent-kit COPY --frombuilder /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.8services:# 主应用 app:build:context:.dockerfile:Dockerfileports:-8501:8501environment:-LLM_BACKENDollama-OLLAMA_HOSThttp://ollama:11434-CHROMA_HOSThttp://chromadb:8000depends_on:-ollama-chromadbvolumes:-./data:/app/data# 数据持久化-./logs:/app/logs# 日志持久化restart:unless-stopped# Ollama 本地模型服务 ollama:image:ollama/ollama:latestports:-11434:11434volumes:-ollama_data:/root/.ollama# 模型文件持久化deploy:resources:reservations:devices:-driver:nvidiacount:1capabilities:[gpu]restart:unless-stopped# ChromaDB 向量数据库 chromadb:image:chromadb/chroma:latestports:-8000:8000volumes:-chroma_data:/chroma/chromaenvironment:-IS_PERSISTENTTRUErestart:unless-stoppedvolumes:ollama_data:chroma_data:五、部署实战5.1 构建和启动# 1. 构建镜像dockerbuild-tai-agent-tutorial.# 2. 启动所有服务docker-composeup-d# 3. 查看运行状态docker-composeps# 4. 查看日志docker-composelogs-fapp# 5. 浏览器打开# http://localhost:85015.2 常用管理命令# 停止服务docker-composedown# 重新构建并启动docker-composeup-d--build# 查看资源使用dockerstats# 进入容器调试dockerexec-itai-agent-tutorial-app-1bash# 清理未使用的镜像和容器dockersystem prune-a5.3 GPU 支持配置# 安装 NVIDIA Container ToolkitLinux# Ubuntu/Debian:distribution$(./etc/os-release;echo$ID$VERSION_ID)curl-s-Lhttps://nvidia.github.io/nvidia-docker/gpgkey|sudoapt-keyadd-curl-s-Lhttps://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list|\sudotee/etc/apt/sources.list.d/nvidia-docker.listsudoapt-getupdatesudoapt-getinstall-ynvidia-container-toolkitsudosystemctl restartdocker# 验证 GPU 可用dockerrun--rm--gpusall nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi六、生产环境最佳实践实践说明使用 .dockerignore减少构建上下文加速构建多阶段构建最终镜像只包含运行时依赖健康检查自动检测容器是否正常运行资源限制限制 CPU/内存防止 OOM日志轮转配置 docker 日志大小限制非 root 运行安全最佳实践版本标签不要用 latest用语义化版本健康检查配置HEALTHCHECK --interval30s --timeout10s --retries3 \ CMD curl -f http://localhost:8501/_stcore/health || exit 1七、运行cdcode/lesson-48-docker# 查看 Dockerfile 和 docker-compose.yml# 构建并启动: docker-compose up -d八、本课小结Docker 解决「在我电脑上能跑」的问题保证环境一致Dockerfile 定义镜像构建过程多阶段构建优化大小docker-compose 编排多个服务App Ollama ChromaDBGPU 支持需要安装 NVIDIA Container Toolkit生产环境遵循最佳实践健康检查、资源限制、非 root 运行配套代码code/lesson-48-docker/含完整 Dockerfile 和 docker-compose.yml 「AI Agent 全栈开发 50 讲」——从本地模型部署到多智能体系统，一年省 87 万 第 48 课 | Docker 容器化：一键部署到任何机器
第 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镜像构建蓝图 docker build构建镜像 Docker Image只读模板▶️ docker run启动容器 Container运行的实例 docker-compose.yml多容器编排docker-compose up多个容器协同核心概念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 --frombuilder /app/.venv /app/.venv COPY --frombuilder /app/agent-kit /app/agent-kit COPY --frombuilder /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.8services:# 主应用 app:build:context:.dockerfile:Dockerfileports:-8501:8501environment:-LLM_BACKENDollama-OLLAMA_HOSThttp://ollama:11434-CHROMA_HOSThttp://chromadb:8000depends_on:-ollama-chromadbvolumes:-./data:/app/data# 数据持久化-./logs:/app/logs# 日志持久化restart:unless-stopped# Ollama 本地模型服务 ollama:image:ollama/ollama:latestports:-11434:11434volumes:-ollama_data:/root/.ollama# 模型文件持久化deploy:resources:reservations:devices:-driver:nvidiacount:1capabilities:[gpu]restart:unless-stopped# ChromaDB 向量数据库 chromadb:image:chromadb/chroma:latestports:-8000:8000volumes:-chroma_data:/chroma/chromaenvironment:-IS_PERSISTENTTRUErestart:unless-stoppedvolumes:ollama_data:chroma_data:五、部署实战5.1 构建和启动# 1. 构建镜像dockerbuild-tai-agent-tutorial.# 2. 启动所有服务docker-composeup-d# 3. 查看运行状态docker-composeps# 4. 查看日志docker-composelogs-fapp# 5. 浏览器打开# http://localhost:85015.2 常用管理命令# 停止服务docker-composedown# 重新构建并启动docker-composeup-d--build# 查看资源使用dockerstats# 进入容器调试dockerexec-itai-agent-tutorial-app-1bash# 清理未使用的镜像和容器dockersystem prune-a5.3 GPU 支持配置# 安装 NVIDIA Container ToolkitLinux# Ubuntu/Debian:distribution$(./etc/os-release;echo$ID$VERSION_ID)curl-s-Lhttps://nvidia.github.io/nvidia-docker/gpgkey|sudoapt-keyadd-curl-s-Lhttps://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list|\sudotee/etc/apt/sources.list.d/nvidia-docker.listsudoapt-getupdatesudoapt-getinstall-ynvidia-container-toolkitsudosystemctl restartdocker# 验证 GPU 可用dockerrun--rm--gpusall nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi六、生产环境最佳实践实践说明使用 .dockerignore减少构建上下文加速构建多阶段构建最终镜像只包含运行时依赖健康检查自动检测容器是否正常运行资源限制限制 CPU/内存防止 OOM日志轮转配置 docker 日志大小限制非 root 运行安全最佳实践版本标签不要用 latest用语义化版本健康检查配置HEALTHCHECK --interval30s --timeout10s --retries3 \ CMD curl -f http://localhost:8501/_stcore/health || exit 1七、运行cdcode/lesson-48-docker# 查看 Dockerfile 和 docker-compose.yml# 构建并启动: docker-compose up -d八、本课小结Docker 解决「在我电脑上能跑」的问题保证环境一致Dockerfile 定义镜像构建过程多阶段构建优化大小docker-compose 编排多个服务App Ollama ChromaDBGPU 支持需要安装 NVIDIA Container Toolkit生产环境遵循最佳实践健康检查、资源限制、非 root 运行配套代码code/lesson-48-docker/含完整 Dockerfile 和 docker-compose.yml