🎯 MBE Docker部署 - 数据管理策略

📋 概述

MBE系统包含大量数据文件（PDF、训练数据、备份等），不应全部打包到Docker镜像中。本文档说明如何正确管理这些数据。

🚫 不应包含在镜像中的文件

1. PDF文档 (~6GB)

❌ docs/expert/          23个PDF (烹饪、健康等专家知识)
❌ docs/lawyer/          42个PDF (法律文档)
❌ docs/systemdesigninterview/  系统设计PDF
❌ docs/zhengquan/       75个PDF (证券相关)
❌ docs/Modelbuilder/    AI模型论文PDF

原因:

已转换为向量索引（knowledge_bases/*_chunks.json）
运行时不需要原始PDF
大幅增加镜像体积

替代方案:

保留在开发环境本地
生产环境使用对象存储（OSS/S3）

2. 备份文件 (~42GB+)

❌ backups/              数据库备份
❌ *.bak                 各种备份文件
❌ *.backup
❌ *.old

原因:

备份应使用专门的备份策略
不应随应用部署

正确做法:

# 使用Docker volume备份
docker exec mbe-postgres pg_dump -U mbe mbe > backup.sql

# 或使用专门的备份服务
docker run --rm \
  --volumes-from mbe-postgres \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/pgdata.tar.gz /var/lib/postgresql/data

3. 训练数据 (~10GB+)

❌ training/datasets/    120+ JSON训练数据文件
❌ training/logs/        训练日志
❌ training/checkpoints/moe_step_*.pt  中间检查点
❌ *.pkl                 大型pickle文件

保留项:

✅ training/checkpoints/best/  最终模型
✅ training/*.py               训练脚本

原因:

中间训练数据可以重新生成
只需保留最终模型

4. 日志和报告

❌ reports/              测试报告
❌ logs/                 历史日志
❌ *.log                 所有日志文件
❌ diagnose_*.txt        诊断文件
❌ *_test_report.json    测试报告

正确做法:

日志写入Docker volume
使用日志收集系统（ELK/Loki）

5. 其他大文件

❌ **/*.doc, *.docx      Word文档
❌ **/*.ppt, *.pptx      PPT文档
❌ **/*.zip, *.rar       压缩包
❌ node_modules/         前端依赖
❌ cache/                缓存目录
❌ __pycache__/          Python缓存

✅ 应该包含在镜像中的文件

1. 核心代码 (~50MB)

✅ src/                  Python核心代码
✅ expert-marketplace/   专家市场
✅ mbe-mcp-server/      MCP服务
✅ requirements.txt      Python依赖清单

2. 配置文件 (~5MB)

✅ config/              配置文件
✅ *.json               JSON配置
✅ *.yml, *.yaml        YAML配置

3. 知识库索引 (~10MB)

✅ knowledge_bases/*.json              配置JSON
✅ knowledge_bases/*_chunks.json       向量索引
✅ knowledge_bases/index.json          索引文件
✅ knowledge_bases/permissions.json    权限配置

注意: 只包含JSON索引，不包含原始PDF

4. 初始化脚本

✅ init.sql             数据库初始化
✅ migrations/*.sql     数据库迁移

🔧 Docker Compose配置

开发环境（挂载源代码）

# docker-compose.complete.yml
volumes:
  # ✅ 挂载源代码（支持热重载）
  - ./src:/app/src
  - ./expert-marketplace:/app/expert-marketplace
  
  # ✅ 挂载知识库配置
  - ./knowledge_bases:/app/knowledge_bases
  
  # ✅ 挂载缓存（运行时生成）
  - ./cache:/app/cache
  
  # ❌ 不要挂载大文件
  # - ./docs/expert:/app/docs/expert
  # - ./backups:/app/backups
  # - ./training/datasets:/app/training/datasets

生产环境（最小镜像）

# docker-compose.complete.yml (production)
environment:
  # 使用环境变量配置外部存储
  - KNOWLEDGE_BASE_PATH=/app/knowledge_bases
  - CACHE_PATH=/app/cache
  - DOCUMENTS_OUTPUT=/app/documents

volumes:
  # 只挂载运行时数据
  - cache:/app/cache
  - documents:/app/documents
  
  # 不挂载源代码和大文件

🌐 生产环境数据管理

方案1: 对象存储（推荐）

使用阿里云OSS、AWS S3等：

# .env.production
OSS_PROVIDER=aliyun
OSS_BUCKET=mbe-knowledge-base
OSS_ENDPOINT=https://oss-cn-shenzhen.aliyuncs.com
OSS_ACCESS_KEY=${OSS_ACCESS_KEY}
OSS_SECRET_KEY=${OSS_SECRET_KEY}

# 如果需要PDF原文
ENABLE_PDF_DOWNLOAD=true
PDF_STORAGE_URL=https://mbe-documents.oss-cn-shenzhen.aliyuncs.com

应用代码：

# src/knowledge/storage.py
import oss2

def get_pdf_content(pdf_id):
    # 从OSS下载PDF（如果需要）
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
    return bucket.get_object(f"pdfs/{pdf_id}.pdf")

方案2: NFS/共享存储

# docker-compose.complete.yml
volumes:
  knowledge_base:
    driver: local
    driver_opts:
      type: nfs
      o: addr=nfs-server.example.com,rw
      device: ":/mnt/mbe/knowledge_bases"

方案3: S3挂载（s3fs）

# Dockerfile
RUN apt-get update && apt-get install -y s3fs

volumes:
  - type: volume
    source: s3-knowledge-base
    target: /app/knowledge_bases
    volume:
      driver: s3fs

📊 镜像大小对比

未优化（包含所有文件）

镜像大小: 64GB
构建时间: 30+ 分钟
部署时间: 长
成本: 高

优化后（只包含必要文件）

镜像大小: ~500MB ✅
构建时间: 5-8 分钟 ✅
部署时间: 短 ✅
成本: 低 ✅

🚀 部署流程

1. 开发环境

# 1. 配置环境变量
编辑 .env.development

# 2. 部署（自动挂载源代码）
.\scripts\deploy_complete_development.ps1

# 3. 访问本地文件
# PDF文件在: d:\Mises\mises-behavior-engine\docs\expert\
# 可以直接修改和访问

2. 生产环境

# 1. 上传大文件到对象存储
# - PDF文档上传到OSS
# - 配置OSS访问凭证

# 2. 配置生产环境变量
编辑 .env.production
# 设置OSS配置

# 3. 部署（精简镜像）
.\scripts\deploy_complete_production.ps1

# 4. 应用自动从OSS读取PDF
# 无需包含在镜像中

💡 最佳实践

1. 数据分层

Layer 1: 镜像层（不可变）
  ├─ 源代码
  ├─ 依赖包
  └─ 配置文件

Layer 2: 数据层（可变）
  ├─ 运行时缓存（volume）
  ├─ 生成的文档（volume）
  └─ 日志（volume）

Layer 3: 外部存储（按需）
  ├─ PDF文档（OSS）
  ├─ 训练数据（OSS）
  └─ 备份（专门备份服务）

2. 环境隔离

开发环境:
  - 挂载所有源代码
  - 访问本地大文件
  - 支持热重载

生产环境:
  - 精简镜像
  - 外部存储
  - 性能优化

3. 成本优化

镜像存储:   500MB × 版本数
对象存储:   6GB × 1份（共享）
总成本:     大幅降低 ✅

🔍 验证配置

检查.dockerignore

# 查看会被包含在镜像中的文件
docker build --no-cache -t test-image .
docker run --rm test-image du -sh /*
docker run --rm test-image find /app -name "*.pdf"

# 应该返回空（没有PDF文件）

检查镜像大小

docker images mbe-api

# 应该显示 ~500MB
# 如果超过1GB，说明包含了不必要的文件

⚠️ 常见问题

Q1: 应用找不到PDF文件？

A: 这是正常的！PDF已转换为向量索引：

# 不要直接读取PDF
with open("docs/expert/bread.pdf") as f:  # ❌

# 应该使用向量索引
from knowledge import search_knowledge
results = search_knowledge("面包制作")  # ✅

Q2: 需要原始PDF怎么办？

A: 配置外部存储：

# .env.production
ENABLE_PDF_STORAGE=true
PDF_STORAGE_TYPE=oss  # 或 s3, nfs

# 应用中
from storage import download_pdf
pdf_bytes = download_pdf("bread_master.pdf")

Q3: 训练模型时需要数据集？

A: 使用单独的训练容器：

# docker-compose.training.yml
services:
  trainer:
    volumes:
      - ./training:/app/training  # 挂载完整训练目录
    command: python training/train_moe.py

📚 相关文档

更新时间: 2026-02-01
优化版本: v2.0
镜像大小: ~500MB（从64GB优化）✅

🎉 合理的数据管理让部署更高效！ 🚀