企业官网建设流程全解析

第11篇：Agent应用的部署与运维 —— Docker、Dev Container与云平台实战

从开发环境到生产环境，Agent应用需要面对容器化、持久化、CI/CD等一系列挑战。本文以RAG知识库问答系统为例，详细讲解Docker Compose编排前后端服务（FastAPI + Next.js）、Dev Container配置实现一致的开发环境、ChromaDB在云平台上的持久化方案、以及Vercel前端部署与Railway后端部署的全流程，提供可直接复用的配置模板。

一、为什么Agent应用需要容器化？

Agent应用与传统Web应用在部署上有一个关键差异：依赖复杂度更高。

容器化（Docker）正是解决这些问题的标准方案。它通过将应用及其所有依赖打包成一个不可变镜像，彻底消除了“在我机器上能跑”的问题。

二、Docker Compose编排前后端服务

2.1 项目结构

project-root/ ├── backend/ │ ├── app/ │ │ ├── main.py │ │ ├── database.py │ │ └── rag_chain.py │ ├── requirements.txt │ └── Dockerfile ├── frontend/ │ ├── app/ │ │ ├── layout.tsx │ │ └── page.tsx │ ├── package.json │ └── Dockerfile ├── docker-compose.yml └── .env

2.2 后端Dockerfile

# backend/Dockerfile FROM python:3.11-slim WORKDIR /workspace # 系统依赖（ChromaDB需要sqlite3，sentence-transformers需要gcc） RUN apt-get update && apt-get install -y --no-install-recommends \ gcc g++ sqlite3 libsqlite3-dev curl \ && rm -rf /var/lib/apt/lists/* # 使用清华镜像加速pip RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

关键点说明：

• 使用slim镜像减少体积（约150MB，full镜像约1GB）
• 安装编译工具（gcc）是为了chromadb和sentence-transformers的编译依赖
• 使用镜像源加速国内下载

2.3 前端Dockerfile

# frontend/Dockerfile FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm install COPY . . CMD ["npm", "run", "dev"]

2.4 Docker Compose配置

# docker-compose.yml services: # ---- 后端服务 ---- backend: build: ./backend container_name: rag-backend ports: - "8000:8000" env_file: - .env volumes: - ./backend:/workspace # 代码挂载，支持热重载 - ./backend/chroma_db:/workspace/chroma_db # 持久化向量数据 - /workspace/__pycache__ # 防止pycache污染 environment: - PYTHONPATH=/workspace command: > sh -c "uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload" restart: unless-stopped networks: - rag-network # ---- 前端服务 ---- frontend: build: ./frontend container_name: rag-frontend ports: - "3000:3000" volumes: - ./frontend:/app - /app/node_modules - /app/.next environment: - CHOKIDAR_USEPOLLING=true # Docker内热重载必需 - WATCHPACK_POLLING=true # Webpack轮询 - NEXT_PUBLIC_API_BASE=http://backend:8000 command: sh -c "npm install && npm run dev" restart: unless-stopped depends_on: - backend networks: - rag-network networks: rag-network: driver: bridge

volumes挂载的三种模式：

2.5 环境变量管理

# .env DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5

重要提醒：.env文件包含API Key，永远不要提交到Git仓库。确保.gitignore包含.env。

三、Dev Container：统一的开发环境

Dev Container让团队成员（或在不同机器上）使用完全一致的开发环境，彻底消除“环境不一致”问题。

3.1 devcontainer.json配置

{ "name": "RAG Dev Container", "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04", "features": { "ghcr.io/devcontainers/features/python:1": { "version": "3.11" }, "ghcr.io/devcontainers/features/node:1": { "version": "20" }, "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {} }, "mounts": [ "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached" ], "postCreateCommand": "cd /workspace && docker compose up -d", "customizations": { "vscode": { "extensions": [ "ms-python.python", "ms-python.vscode-pylance", "ms-vscode.vscode-typescript-next", "ms-azuretools.vscode-docker", "bradlc.vscode-tailwindcss" ] } }, "forwardPorts": [3000, 8000], "workspaceFolder": "/workspace" }

三个关键特性：

3.2 Apple Silicon（ARM64）兼容性

Dev Container的通用镜像（如universal）可能不支持ARM64。推荐使用明确的镜像组合：

✅ 推荐：mcr.microsoft.com/devcontainers/base:ubuntu-22.04 + features ✅ 可选：ghcr.io/devcontainers/universal:2 ❌ 避免：mcr.microsoft.com/devcontainers/universal:2（ARM64镜像缺失）

四、云平台部署

4.1 后端部署到Railway（含ChromaDB持久化）

第一步：准备配置文件

// railway.json { "build": { "builder": "NIXPACKS" }, "deploy": { "numReplicas": 1, "startCommand": "uvicorn app.main:app --host 0.0.0.0 --port $PORT" } }

第二步：创建Volume（持久化关键）

1. 在Railway项目 → Settings → Volumes
2. 创建Volume，名称chroma_data，挂载路径/workspace/chroma_db
3. 注意：免费层Volume需要付费（约$1/月），但相比数据丢失的风险，这是一笔必要的投资

第三步：环境变量配置

在Railway的Variables中添加：

第四步：部署

git add . git commit -m "deploy: prepare for railway" git push origin main

Railway会自动检测railway.json并执行部署。

4.2 前端部署到Vercel

// next.config.js /** @type {import('next').NextConfig} */ const nextConfig = { output: 'standalone', // 关键：生成独立的构建产物 async rewrites() { return [ { source: '/api/:path*', destination: `${process.env.NEXT_PUBLIC_API_BASE}/api/:path*`, }, ]; }, };

Vercel环境变量配置：

4.3 CORS配置（关键）

部署后前端跨域请求需要后端允许：

# backend/app/main.py app.add_middleware( CORSMiddleware, allow_origins=[ "http://localhost:3000", "https://your-frontend.vercel.app", # 添加前端部署域名 ], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], )

五、部署检查清单

在部署到生产环境前，逐项确认：

• 环境变量已配置（DEEPSEEK_API_KEY）
• ChromaDB持久化卷已创建并挂载
• CORS允许前端域名
• 前端NEXT_PUBLIC_API_BASE指向正确的后端地址
• 健康检查端点/health可访问
• 上传一个测试文档并验证向量存储成功
• 提问验证RAG功能正常
• API限流已配置（防止成本失控）

六、常见部署问题与排查

思考与动手建议：

1. 使用本地的docker-compose.yml验证完整的开发环境，确保前后端都能正常交互。
2. 在Railway上部署你的RAG后端，注意配置Volume持久化ChromaDB。
3. 记录从git push到服务可访问的完整时间，建立部署效率基线。