MinerU部署指南：Docker一键部署最佳实践

还在为PDF文档结构化提取的环境配置而烦恼吗？MinerU的Docker部署方案让您5分钟内搭建完整的PDF转Markdown/JSON生产环境，无需担心CUDA版本、Python依赖、模型下载等繁琐问题！

通过本文，您将获得：

• ✅ Docker一键部署MinerU的完整流程
• ✅ 多架构GPU兼容性解决方案
• ✅ 生产环境最佳配置实践
• ✅ 性能优化与故障排除指南
• ✅ 国内网络环境加速方案

🚀 环境准备与系统要求

在开始部署前，请确保您的系统满足以下基本要求：

组件	最低要求	推荐配置
Docker	20.10+	24.0+
NVIDIA驱动	470+	535+
GPU架构	Turing+	Ampere+
显存	8GB	16GB+
系统内存	16GB	32GB+

验证GPU环境

# 检查NVIDIA驱动
nvidia-smi

# 验证Docker GPU支持
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

📦 Docker镜像构建最佳实践

MinerU提供两种Dockerfile选择，针对不同网络环境优化：

全球网络环境（推荐海外用户）

# docker/global/Dockerfile
FROM lmsysorg/sglang:v0.4.9.post6-cu126
# 对于Blackwell架构GPU使用：
# FROM lmsysorg/sglang:v0.4.9.post6-cu128-b200

国内网络环境优化

# docker/china/Dockerfile  
FROM docker.m.daocloud.io/lmsysorg/sglang:v0.4.9.post6-cu126
# 对于Blackwell架构GPU使用：
# FROM docker.m.daocloud.io/lmsysorg/sglang:v0.4.9.post6-cu128-b200

构建镜像命令

# 国内用户使用中国区优化版本
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/Dockerfile
docker build -t mineru-sglang:latest -f Dockerfile .

# 全球用户使用标准版本  
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/global/Dockerfile
docker build -t mineru-sglang:latest -f Dockerfile .

🏗️ 容器部署策略

方案一：交互式开发环境

docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 -p 7860:7860 -p 8000:8000 \
  --ipc=host \
  -v /path/to/your/data:/data \
  -it mineru-sglang:latest \
  /bin/bash

端口映射说明：

• 30000: sglang-server服务端口
• 7860: Gradio WebUI服务端口
• 8000: FastAPI服务端口

方案二：Docker Compose生产部署

# docker/compose.yaml 核心配置解析
version: '3.8'

services:
  mineru-sglang-server:
    image: mineru-sglang:latest
    profiles: ["sglang-server"]
    ports: ["30000:30000"]
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]

启动特定服务：

# 下载compose配置文件
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml

# 启动sglang-server服务
docker compose -f compose.yaml --profile sglang-server up -d

# 启动Web API服务
docker compose -f compose.yaml --profile api up -d

# 启动Gradio WebUI服务
docker compose -f compose.yaml --profile gradio up -d

⚡ 性能优化配置

GPU资源分配策略

# 多GPU负载均衡配置
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ["0", "1"]  # 使用GPU 0和1
          capabilities: [gpu]

内存与缓存优化

# 共享内存和IPC配置
ulimits:
  memlock: -1        # 无内存锁定限制
  stack: 67108864    # 64MB栈大小

ipc: host           # 使用主机IPC命名空间
shm_size: 32g       # 32GB共享内存

SGLang加速参数调优

# 启用torch.compile加速（约15%性能提升）
--enable-torch-compile

# 多GPU数据并行（提高吞吐量）
--dp-size 2

# 张量并行（扩展可用显存）
--tp-size 2

# KV缓存大小调整（解决显存不足）
--mem-fraction-static 0.5

🔧 故障排除与诊断

常见问题解决方案

flowchart TD
    A[部署问题] --> B{GPU检测失败}
    A --> C[端口冲突]
    A --> D[显存不足]
    
    B --> E[检查nvidia-docker2安装]
    B --> F[验证驱动版本兼容性]
    
    C --> G[修改compose端口映射]
    C --> H[检查防火墙设置]
    
    D --> I[调整mem-fraction-static参数]
    D --> J[减少并发处理数量]

健康检查与监控

# 检查sglang-server健康状态
curl http://localhost:30000/health

# 查看容器日志
docker logs mineru-sglang-server

# 监控GPU使用情况
docker exec mineru-sglang-server nvidia-smi

# 资源使用统计
docker stats mineru-sglang-server

🎯 生产环境最佳实践

1. 资源限制与保障

# 防止资源耗尽
deploy:
  resources:
    limits:
      cpus: '8'
      memory: 32G
    reservations:
      cpus: '4' 
      memory: 16G

2. 高可用性配置

# 自动重启策略
restart: unless-stopped

# 健康检查配置
healthcheck:
  test: ["CMD-SHELL", "curl -f http://localhost:30000/health || exit 1"]
  interval: 30s
  timeout: 10s
  retries: 3

3. 数据持久化方案

# 模型数据卷
volumes:
  mineru-models:
    driver: local

# 服务配置
services:
  mineru-sglang-server:
    volumes:
      - mineru-models:/root/.cache/mineru

📊 性能基准测试

基于不同硬件配置的性能对比：

硬件配置	处理速度（页/分钟）	显存占用	推荐场景
RTX 4090 + SGLang	120-150	12-16GB	生产环境
RTX 3080 + Transformers	40-60	8-10GB	开发测试
CPU Only	5-10	2GB	轻量使用

🚨 安全注意事项

网络隔离策略

# 创建专用网络
networks:
  mineru-net:
    driver: bridge
    internal: true  # 内部网络，不暴露到主机

# 服务网络配置
services:
  mineru-sglang-server:
    networks:
      - mineru-net

访问控制配置

# 环境变量安全配置
environment:
  MINERU_API_KEY: ${API_KEY}
  MINERU_AUTH_ENABLED: "true"

🔄 版本升级与维护

平滑升级流程

# 1. 拉取最新镜像
docker pull mineru-sglang:latest

# 2. 停止旧服务
docker compose down

# 3. 启动新服务
docker compose up -d

# 4. 验证升级
docker logs mineru-sglang-server

数据备份策略

# 备份模型数据
docker run --rm -v mineru-models:/source -v /backup:/backup alpine \
  tar czf /backup/mineru-models-$(date +%Y%m%d).tar.gz -C /source .

# 恢复模型数据
docker run --rm -v mineru-models:/target -v /backup:/backup alpine \
  tar xzf /backup/mineru-models-20250101.tar.gz -C /target

💡 高级使用技巧

多模型并行处理

# 启动多个sglang-server实例
services:
  mineru-sglang-server-1:
    extends: mineru-sglang-server
    device_ids: ["0"]
    
  mineru-sglang-server-2:
    extends: mineru-sglang-server  
    device_ids: ["1"]

自定义模型配置

# 使用自定义模型路径
docker run -e MINERU_MODEL_SOURCE=local \
  -v /path/to/custom/models:/models \
  mineru-sglang:latest

🎉 部署成功验证

完成部署后，通过以下方式验证服务状态：

# 测试sglang-server
curl http://localhost:30000/health

# 测试API服务
curl http://localhost:8000/docs

# 测试WebUI服务
curl http://localhost:7860

📈 性能监控仪表板

建议集成以下监控工具：

• Prometheus + Grafana: 资源使用监控
• cAdvisor: 容器性能分析
• NVIDIA DCGM: GPU深度监控
• Elasticsearch + Kibana: 日志分析

总结

通过本文的Docker部署指南，您已经掌握了MinerU在生产环境中的最佳实践方案。从基础的单机部署到高级的多GPU优化，从性能调优到故障排除，这套方案能够帮助您快速构建稳定高效的PDF文档处理流水线。

记住关键要点：

1. 选择正确的Dockerfile适配您的网络环境
2. 合理配置GPU资源避免显存瓶颈
3. 使用Docker Compose简化多服务管理
4. 实施监控告警确保服务稳定性
5. 定期备份数据防止意外丢失

现在就开始您的MinerU之旅，体验高效的PDF文档结构化提取吧！