MBE Docker 配置指南

文档版本: v1.0
更新日期: 2026-01-31
适用范围: 所有 Docker 部署环境

一、配置文件概览

MBE 提供多个 Docker Compose 配置文件，适用于不同的部署场景：

配置文件	用途	适用场景
`docker-compose.yml`	本地开发	开发调试，源代码热重载
`docker-compose.dev.yml`	远程开发	开发服务器，独立端口
`docker-compose.prod.yml`	生产环境	线上部署，Cloudflare Tunnel
`docker-compose.cpu.yml`	CPU 版本	无 GPU 环境
`docker-compose.gpu.yml`	GPU 版本	有 NVIDIA GPU 环境
`docker-compose.monitoring.yml`	监控服务	Prometheus + Grafana

二、环境配置对比

2.1 主要配置差异

特性	docker-compose.yml (开发本地)	docker-compose.dev.yml (开发远程)	docker-compose.prod.yml (生产)
环境变量	`MBE_ENV=development`	`MBE_ENV=development`	`MBE_ENV=production`
API 端口	8000	8001	8000
数据库端口	5432	5433	内部网络
Redis 端口	6380	6381	内部网络
源代码挂载	✅ `./src:/app/src`	❌ 打包进镜像	❌ 打包进镜像
文档存储	✅ `./documents`	✅ `./documents`	✅ `./documents`
GPU 支持	✅ 可选	❌	❌
Cloudflare Tunnel	❌	✅	✅
DEBUG 模式	true	false	false
重启策略	unless-stopped	unless-stopped	always
健康检查	基础	基础	增强（120s 启动时间）

2.2 数据卷挂载

所有环境共享的数据卷：

volumes:
  - ./training:/app/training           # 训练模型和检查点
  - ./knowledge_bases:/app/knowledge_bases  # 知识库向量数据
  - ./documents:/app/documents         # 文档生成模块存储

开发环境额外挂载：

volumes:
  - ./src:/app/src                     # 源代码（支持热重载）
  - ./cache:/app/cache                 # 缓存文件

三、Dockerfile 版本

3.1 可用的 Dockerfile

文件	基础镜像	大小	适用场景
`Dockerfile`	nvidia/cuda:12.1.0	~8GB	GPU 开发/生产
`Dockerfile.cpu`	python:3.11-slim	~2GB	CPU 开发
`Dockerfile.gpu`	nvidia/cuda:12.1.0	~8GB	GPU 专用
`Dockerfile.deploy`	python:3.11-slim	~2-3GB	生产部署（轻量）

3.2 系统依赖

所有 Dockerfile 包含文档生成模块所需的系统依赖：

# WeasyPrint 依赖 (PDF 生成)
RUN apt-get install -y \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    libgdk-pixbuf2.0-0 \
    libffi-dev \
    shared-mime-info \
    # 中文字体支持
    fonts-noto-cjk \
    fonts-wqy-microhei

四、构建命令

4.1 构建镜像

# GPU 版本（开发/生产）
docker build -t mbe-api:latest -f Dockerfile .

# CPU 版本（开发）
docker build -t mbe-api:cpu -f Dockerfile.cpu .

# CPU 版本（开发标签）
docker build -t mbe-api:dev -f Dockerfile.cpu .

# 生产部署版（轻量）
docker build -t mbe-api:prod -f Dockerfile.deploy .

# GPU 专用版
docker build -t mbe-api:gpu -f Dockerfile.gpu .

4.2 启动服务

# 本地开发（默认）
docker compose up -d

# 远程开发环境
docker compose -f docker-compose.dev.yml up -d

# 生产环境
docker compose -f docker-compose.prod.yml up -d

# CPU 环境
docker compose -f docker-compose.cpu.yml up -d

# 带监控
docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

4.3 常用操作

# 查看日志
docker compose logs -f mbe-api

# 重启服务
docker compose restart mbe-api

# 停止所有服务
docker compose down

# 清理数据卷（谨慎操作）
docker compose down -v

# 更新镜像并重启
docker compose pull && docker compose up -d

五、环境变量

5.1 必需环境变量

# LLM 配置
LLM_PROVIDER=deepseek          # deepseek / qwen / doubao / openrouter
LLM_API_KEY=your_api_key       # API 密钥
LLM_MODEL=deepseek-chat        # 模型名称

# 安全配置
SECRET_KEY=your-secret-key     # JWT 签名密钥（生产环境必须修改）

5.2 可选环境变量

# 数据库
DATABASE_URL=postgresql+asyncpg://mbe:password@postgres:5432/mbe
REDIS_URL=redis://redis:6379

# GPU 配置
MBE_DEVICE=auto                # auto / cuda / cpu
NVIDIA_VISIBLE_DEVICES=all

# 弹性 LLM 客户端
MBE_USE_RESILIENT_LLM=true     # 启用熔断器+重试

# 监控
OTEL_ENABLED=false             # OpenTelemetry 追踪
SENTRY_DSN=                    # Sentry 错误追踪

# 语音服务
ASR_PROVIDER=mock              # mock / aliyun / xfyun
TTS_PROVIDER=edge              # mock / edge / aliyun

# 邮件服务
SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_USER=user@example.com
SMTP_PASSWORD=password

5.3 生产环境特有

# 生产环境标识
MBE_ENV=production
DEBUG=false
LOG_LEVEL=INFO

# Cloudflare Tunnel
CLOUDFLARE_TUNNEL_TOKEN=your_tunnel_token

# 数据库密码（强密码）
DB_PASSWORD_PROD=strong_password_here

# OpenRouter（可选）
OPENROUTER_API_KEY=your_key
OPENROUTER_MODEL=anthropic/claude-sonnet-4

六、文档生成模块配置

6.1 存储配置

文档生成模块的文件存储在 ./documents 目录：

# docker-compose.yml
volumes:
  - ./documents:/app/documents

6.2 依赖要求

requirements.txt 中的文档生成相关依赖：

# 文档生成模块
jinja2>=3.1.2          # 模板引擎
weasyprint>=60.0       # PDF 生成
python-docx>=1.1.0     # Word 文档
html2text>=2024.2.26   # HTML 转 Markdown
beautifulsoup4>=4.12.0 # HTML 解析
markdown>=3.5.0        # Markdown 处理
jsonschema>=4.21.0     # JSON Schema 验证

6.3 API 端点

文档生成模块提供的 API：

端点	方法	说明
`/api/v1/document/generate`	POST	生成文档
`/api/v1/document/status/{id}`	GET	查询状态
`/api/v1/document/preview`	POST	预览文档
`/api/v1/document/download/{id}`	GET	下载文档
`/api/v1/document/industries`	GET	支持的行业
`/api/v1/summary/conversation`	POST	对话摘要
`/api/v1/templates`	GET	模板列表

七、故障排查

7.1 常见问题

Q: 容器启动失败，提示找不到模块

# 检查 PYTHONPATH
docker exec mbe-api env | grep PYTHONPATH
# 应该输出: PYTHONPATH=/app

Q: PDF 生成失败

# 检查 WeasyPrint 依赖
docker exec mbe-api python -c "import weasyprint; print('OK')"

# 检查字体
docker exec mbe-api fc-list :lang=zh

Q: 数据库连接失败

# 检查数据库健康状态
docker compose ps postgres
docker compose logs postgres

7.2 日志位置

# API 日志
docker compose logs -f mbe-api

# 数据库日志
docker compose logs -f postgres

# 所有服务日志
docker compose logs -f

八、部署检查清单

8.1 生产部署前检查

修改 SECRET_KEY 为强密码
修改数据库密码 DB_PASSWORD_PROD
配置 LLM_API_KEY
配置 CLOUDFLARE_TUNNEL_TOKEN
创建 ./documents 目录
确认 .env 文件权限（600）
测试健康检查端点 /api/health

8.2 构建部署流程

# 1. 构建生产镜像
docker build -t mbe-api:prod -f Dockerfile.deploy .

# 2. 推送到镜像仓库（可选）
docker tag mbe-api:prod registry.example.com/mbe-api:prod
docker push registry.example.com/mbe-api:prod

# 3. 部署到生产服务器
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

# 4. 验证部署
curl -s http://localhost:8000/api/health | jq

MBE 文档中心