首页
/ MinerU企业级离线部署技术指南

MinerU企业级离线部署技术指南

2026-03-30 11:13:13作者：廉皓灿Ida
MinerU
Transforms complex documents like PDFs into LLM-ready markdown/JSON for your Agentic workflows.
项目地址：https://gitcode.com/GitHub_Trending/mi/MinerU

一、环境准备阶段

1.1 部署资源收集

操作目标：获取部署所需的全部资源文件
前置条件：具备联网环境、至少50GB存储空间、管理员权限
执行步骤：

  1. 克隆项目源码

    git clone https://gitcode.com/GitHub_Trending/mi/MinerU
cd MinerU
git checkout v1.5.0  # 使用稳定版本而非main分支

  2. 下载模型文件集合

    python -m mineru.cli.models_download -s modelscope -m all \
  --output-path ./mineru_models_v1.5  # 指定模型存储路径

  3. 缓存依赖包

    # 创建依赖缓存目录
mkdir -p /tmp/mineru_deps

# 导出依赖列表
pip freeze > requirements.txt

# 下载依赖包到本地
pip download -r requirements.txt -d /tmp/mineru_deps \
  --no-cache-dir --no-deps

结果验证：检查资源完整性

# 验证源码完整性
git rev-parse HEAD  # 应显示v1.5.0对应的commit hash

# 验证模型文件大小
du -sh ./mineru_models_v1.5  # 应显示约35GB

# 验证依赖包数量
ls /tmp/mineru_deps | wc -l  # 应显示至少100个文件

⚠️ 注意事项：模型文件较大，建议使用高速网络下载；所有资源需进行MD5校验以确保完整性

1.2 目标环境检查

操作目标：验证离线环境是否满足部署要求
前置条件：已获取目标服务器访问权限
执行步骤：

  1. 创建环境检查脚本

    cat > env_check.sh << 'EOF'
#!/bin/bash
echo "=== 系统环境检查 ==="
echo "操作系统: $(cat /etc/os-release | grep PRETTY_NAME | cut -d= -f2 | tr -d '"')"
echo "CPU核心数: $(nproc)"
echo "内存总量: $(free -h | awk '/Mem:/ {print $2}')"
echo "可用磁盘空间: $(df -h / | awk 'NR==2 {print $4}')"
echo "Python版本: $(python3 --version 2>&1 | cut -d' ' -f2)"
echo "Docker状态: $(systemctl is-active docker)"
echo "Docker Compose版本: $(docker compose version --short 2>/dev/null || echo "未安装")"
EOF

chmod +x env_check.sh

  2. 执行环境检查

    ./env_check.sh > env_check_result.txt

结果验证：检查输出文件，确认满足以下要求：

  • 操作系统：Ubuntu 20.04+/CentOS 8+
  • CPU核心数：至少4核
  • 内存总量：至少16GB（推荐32GB）
  • 可用磁盘空间：至少50GB
  • Python版本：3.10.x
  • Docker状态：active
  • Docker Compose版本：v2.0+

1.3 离线介质准备

操作目标：将部署资源打包并传输到离线环境
前置条件：已完成资源收集和环境检查
执行步骤：

  1. 打包部署资源

    # 创建打包目录
mkdir -p /tmp/mineru_offline_package

# 复制源码
cp -r MinerU /tmp/mineru_offline_package/

# 复制模型文件
cp -r mineru_models_v1.5 /tmp/mineru_offline_package/

# 复制依赖包
cp -r /tmp/mineru_deps /tmp/mineru_offline_package/

# 复制环境检查脚本
cp env_check.sh /tmp/mineru_offline_package/

# 生成校验文件
cd /tmp/mineru_offline_package
find . -type f -print0 | xargs -0 md5sum > checksum.md5

  2. 压缩打包

    tar -czf mineru_offline_v1.5.tar.gz mineru_offline_package/

结果验证：

# 验证压缩包完整性
md5sum mineru_offline_v1.5.tar.gz > mineru_offline_v1.5.tar.gz.md5

# 检查文件大小
du -sh mineru_offline_v1.5.tar.gz  # 应约为35-40GB

1.4 网络隔离策略

操作目标：确保离线环境安全隔离
前置条件：已完成离线介质准备
执行步骤：

  1. 配置防火墙规则

    # 只开放必要端口
sudo ufw allow 22/tcp  # SSH管理端口
sudo ufw allow 8000/tcp  # MinerU API端口
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw enable

  2. 禁用外部网络访问

    # 记录当前网络配置
ip addr > network_config_backup.txt

# 移除默认网关（根据实际网络接口调整）
sudo ip route del default dev eth0

结果验证：

# 验证网络隔离状态
ping -c 1 8.8.8.8  # 应无法连接外部网络
ufw status  # 应只显示开放的必要端口

⚠️ 注意事项：执行网络隔离前，确保已完成所有必要文件的传输，此操作不可逆

二、部署实施阶段

2.1 文件传输与校验

操作目标：将离线包安全传输到目标环境并验证完整性
前置条件：已准备离线介质（如USB硬盘）、目标环境已隔离网络
执行步骤：

  1. 传输离线包到目标服务器

    # 在目标服务器上创建接收目录
mkdir -p /opt/mineru/deployment

# 从USB设备复制文件（假设USB挂载在/mnt/usb）
cp /mnt/usb/mineru_offline_v1.5.tar.gz* /opt/mineru/deployment/

  2. 验证文件完整性

    cd /opt/mineru/deployment
md5sum -c mineru_offline_v1.5.tar.gz.md5

  3. 解压离线包

    tar -xzf mineru_offline_v1.5.tar.gz
cd mineru_offline_package

  4. 验证内部文件完整性

    md5sum -c checksum.md5

结果验证：所有校验应显示"OK"，无文件损坏或缺失

2.2 依赖环境配置

操作目标：在离线环境中安装所有必要依赖
前置条件：已完成文件传输与校验
执行步骤：

  1. 创建Python虚拟环境

    # 进入项目目录
cd /opt/mineru/deployment/mineru_offline_package/MinerU

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装本地依赖包
pip install --no-index --find-links=../mineru_deps \
  -r requirements.txt \
  --ignore-installed

  2. 安装系统依赖

    # Ubuntu/Debian系统
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  libgl1-mesa-glx libglib2.0-0 poppler-utils tesseract-ocr

# CentOS/RHEL系统
sudo yum install -y mesa-libGL glib2 poppler-utils tesseract

结果验证：

# 验证Python依赖
pip list | grep -E "torch|transformers|pdf2image"

# 验证系统依赖
which pdftotext tesseract

2.3 模型文件部署

操作目标：配置模型文件存储路径并验证可用性
前置条件：已完成依赖环境配置
执行步骤：

  1. 创建模型存储目录

    sudo mkdir -p /opt/mineru/models
sudo chown -R $USER:$USER /opt/mineru/models

# 复制模型文件
cp -r ../mineru_models_v1.5/* /opt/mineru/models/

  2. 配置模型路径

    # 创建配置文件目录
mkdir -p ~/.mineru

# 生成配置文件
cat > ~/.mineru/config.json << 'EOF'
{
  "config_version": "1.5.0",
  "models-dir": {
    "pipeline": "/opt/mineru/models/pipeline",
    "vlm": "/opt/mineru/models/vlm"
  },
  "model-source": "local",
  "logging-level": "INFO",
  "performance": {
    "batch-size": 2,
    "max-workers": 4
  }
}
EOF

结果验证：

# 验证模型文件结构
tree -L 2 /opt/mineru/models | grep -E "pipeline|vlm"

# 验证配置文件
cat ~/.mineru/config.json | jq .  # 需要安装jq

2.4 Docker容器化部署

操作目标：使用Docker部署MinerU服务
前置条件：已完成模型文件部署
执行步骤：

  1. 构建Docker镜像

    # 进入项目目录
cd /opt/mineru/deployment/mineru_offline_package/MinerU

# 构建镜像
docker build -f docker/china/Dockerfile \
  --build-arg MODEL_PATH=/opt/mineru/models \
  --build-arg DEPS_PATH=../mineru_deps \
  -t mineru:v1.5.0 .

  2. 启动服务

    # 创建数据目录
mkdir -p /opt/mineru/data/input /opt/mineru/data/output

# 使用compose启动
docker compose -f docker/compose.yaml up -d

结果验证：

# 检查容器状态
docker compose -f docker/compose.yaml ps

# 查看服务日志
docker compose -f docker/compose.yaml logs -f --tail=100

⚠️ 注意事项：首次启动时会初始化模型，可能需要5-10分钟，期间服务不可用

三、质量验证阶段

3.1 基础功能验证

操作目标：验证MinerU核心功能是否正常工作
前置条件：Docker容器已成功启动
执行步骤：

  1. 执行基本转换测试

    # 复制测试文件
cp tests/unittest/pdfs/test.pdf /opt/mineru/data/input/

# 执行转换命令
docker compose -f docker/compose.yaml exec mineru \
  mineru -p /data/input/test.pdf \
  -o /data/output/test_output.md \
  --device cpu

  2. 验证输出结果

    # 检查输出文件是否生成
ls -l /opt/mineru/data/output/test_output.md

# 检查输出内容
head -n 20 /opt/mineru/data/output/test_output.md

结果验证：输出文件应包含PDF内容的Markdown格式转换结果，无明显乱码或格式错误

3.2 性能基准测试

操作目标：建立系统性能基准，验证处理效率
前置条件：基础功能验证通过
执行步骤：

  1. 准备测试数据集

    # 创建测试数据集目录
mkdir -p /opt/mineru/data/test_docs

# 复制不同类型的测试文档（假设已准备）
cp /path/to/test_docs/*.pdf /opt/mineru/data/test_docs/

  2. 执行性能测试

    # 创建性能测试脚本
cat > performance_test.sh << 'EOF'
#!/bin/bash
INPUT_DIR="/data/test_docs"
OUTPUT_DIR="/data/test_output"
LOG_FILE="/data/performance_log.csv"

# 创建输出目录
mkdir -p $OUTPUT_DIR

# 写入CSV表头
echo "filename,page_count,processing_time,status" > $LOG_FILE

# 处理每个PDF文件
for file in $INPUT_DIR/*.pdf; do
  filename=$(basename "$file")
  start_time=$(date +%s)
  
  # 执行转换
  mineru -p "$file" -o "$OUTPUT_DIR/${filename%.pdf}.md" --device cpu
  status=$?
  
  end_time=$(date +%s)
  processing_time=$((end_time - start_time))
  
  # 获取页数
  page_count=$(pdftotext "$file" - | wc -l)
  
  # 记录结果
  echo "$filename,$page_count,$processing_time,$status" >> $LOG_FILE
  echo "Processed $filename in $processing_time seconds"
done
EOF

chmod +x performance_test.sh

# 执行测试
docker compose -f docker/compose.yaml exec mineru ./performance_test.sh

  3. 生成性能报告

    # 复制日志文件到宿主机
docker compose -f docker/compose.yaml cp mineru:/data/performance_log.csv /opt/mineru/data/

# 简单分析
awk -F ',' 'NR>1 {sum+=$3; count++} END {print "平均处理时间: " sum/count "秒/文件"}' /opt/mineru/data/performance_log.csv

结果验证：生成的性能日志应包含所有测试文件的处理时间，平均处理时间应符合预期（文本PDF约1-2秒/页，复杂PDF约3-5秒/页）

3.3 稳定性测试

操作目标：验证系统在持续负载下的稳定性
前置条件：性能基准测试通过
执行步骤：

  1. 配置批处理任务

    # 创建批处理脚本
cat > batch_process.sh << 'EOF'
#!/bin/bash
INPUT_DIR="/data/test_docs"
OUTPUT_DIR="/data/batch_output"
LOG_FILE="/data/batch_log.txt"
ERROR_FILE="/data/error_log.txt"

mkdir -p $OUTPUT_DIR
> $LOG_FILE
> $ERROR_FILE

# 连续处理文件10次
for i in {1..10}; do
  echo "=== 第 $i 轮处理开始 ===" >> $LOG_FILE
  date >> $LOG_FILE
  
  for file in $INPUT_DIR/*.pdf; do
    filename=$(basename "$file")
    echo "Processing $filename" >> $LOG_FILE
    mineru -p "$file" -o "$OUTPUT_DIR/${filename%.pdf}_${i}.md" --device cpu
    if [ $? -ne 0 ]; then
      echo "Error processing $filename in round $i" >> $ERROR_FILE
      date >> $ERROR_FILE
    fi
  done
  
  echo "=== 第 $i 轮处理结束 ===" >> $LOG_FILE
  echo "----------------------------------------" >> $LOG_FILE
  sleep 60  # 每轮之间休息60秒
done
EOF

chmod +x batch_process.sh

  2. 执行稳定性测试

    docker compose -f docker/compose.yaml exec mineru ./batch_process.sh &

  3. 监控系统资源

    # 在宿主机上执行
docker stats --no-stream > /opt/mineru/data/resource_usage.txt

结果验证：

  • 错误日志应无记录或仅有个别错误
  • 系统资源使用应保持稳定，无内存泄漏迹象
  • 所有输出文件应成功生成

3.4 数据完整性验证

操作目标：确保转换结果的数据准确性和完整性
前置条件：稳定性测试通过
执行步骤：

  1. 准备验证数据集

    # 创建验证目录
mkdir -p /opt/mineru/data/validation

  2. 执行完整性检查

    # 创建验证脚本
cat > validation_check.sh << 'EOF'
#!/bin/bash
INPUT_DIR="/data/validation/input"
EXPECTED_DIR="/data/validation/expected"
OUTPUT_DIR="/data/validation/output"
REPORT_FILE="/data/validation/report.txt"

mkdir -p $OUTPUT_DIR
> $REPORT_FILE

echo "数据完整性验证报告" > $REPORT_FILE
echo "生成时间: $(date)" >> $REPORT_FILE
echo "========================================" >> $REPORT_FILE

# 处理验证文档
for file in $INPUT_DIR/*.pdf; do
  filename=$(basename "$file")
  base_name="${filename%.pdf}"
  
  echo "处理文档: $filename" >> $REPORT_FILE
  
  # 执行转换
  mineru -p "$file" -o "$OUTPUT_DIR/$base_name.md" --device cpu
  
  # 比较结果（简单比较字数）
  expected_words=$(wc -w "$EXPECTED_DIR/$base_name.md" | awk '{print $1}')
  actual_words=$(wc -w "$OUTPUT_DIR/$base_name.md" | awk '{print $1}')
  word_diff=$((expected_words - actual_words))
  word_diff_percent=$(echo "scale=2; ($word_diff / $expected_words) * 100" | bc)
  
  echo "  预期字数: $expected_words" >> $REPORT_FILE
  echo "  实际字数: $actual_words" >> $REPORT_FILE
  echo "  差异: $word_diff ($word_diff_percent%)" >> $REPORT_FILE
  
  # 检查表格数量
  expected_tables=$(grep -c "| " "$EXPECTED_DIR/$base_name.md")
  actual_tables=$(grep -c "| " "$OUTPUT_DIR/$base_name.md")
  echo "  表格数量: 预期 $expected_tables, 实际 $actual_tables" >> $REPORT_FILE
  
  echo "----------------------------------------" >> $REPORT_FILE
done
EOF

chmod +x validation_check.sh

  3. 执行验证

    docker compose -f docker/compose.yaml exec mineru ./validation_check.sh

结果验证：验证报告中字数差异应在10%以内，表格数量应与预期一致

四、效能优化阶段

4.1 硬件资源调优

操作目标：根据硬件配置优化资源分配
前置条件：已完成质量验证
执行步骤：

  1. 分析系统瓶颈

    # 在容器内安装性能分析工具
apt-get update && apt-get install -y htop iostat

# 运行性能分析
htop > /data/htop.log &
iostat -x 5 12 > /data/iostat.log &

# 同时运行处理任务
mineru -p /data/test_docs/large_document.pdf -o /data/output/large_output.md

  2. 优化配置文件

    # 创建不同档次的配置文件

# 基础配置（适用于8GB内存，4核CPU）
cat > ~/.mineru/config_basic.json << 'EOF'
{
  "config_version": "1.5.0",
  "models-dir": {
    "pipeline": "/opt/mineru/models/pipeline",
    "vlm": "/opt/mineru/models/vlm"
  },
  "model-source": "local",
  "logging-level": "INFO",
  "performance": {
    "batch-size": 1,
    "max-workers": 2,
    "ocr-threads": 2,
    "table-recognition": {
      "accuracy-mode": "speed",
      "merge-threshold": 0.4
    }
  }
}
EOF

# 标准配置（适用于16GB内存，8核CPU）
cat > ~/.mineru/config_standard.json << 'EOF'
{
  "config_version": "1.5.0",
  "models-dir": {
    "pipeline": "/opt/mineru/models/pipeline",
    "vlm": "/opt/mineru/models/vlm"
  },
  "model-source": "local",
  "logging-level": "INFO",
  "performance": {
    "batch-size": 2,
    "max-workers": 4,
    "ocr-threads": 4,
    "table-recognition": {
      "accuracy-mode": "balanced",
      "merge-threshold": 0.3
    }
  }
}
EOF

# 高性能配置（适用于32GB内存，16核CPU，GPU）
cat > ~/.mineru/config_high.json << 'EOF'
{
  "config_version": "1.5.0",
  "models-dir": {
    "pipeline": "/opt/mineru/models/pipeline",
    "vlm": "/opt/mineru/models/vlm"
  },
  "model-source": "local",
  "logging-level": "INFO",
  "device": "gpu",
  "performance": {
    "batch-size": 4,
    "max-workers": 8,
    "ocr-threads": 8,
    "gpu-memory-limit": "16G",
    "table-recognition": {
      "accuracy-mode": "accuracy",
      "merge-threshold": 0.2
    }
  }
}
EOF

  3. 应用优化配置

    # 根据实际硬件选择合适的配置
ln -sf ~/.mineru/config_standard.json ~/.mineru/config.json

# 重启服务使配置生效
docker compose -f docker/compose.yaml restart

结果验证：

# 重新运行性能测试并比较结果
./performance_test.sh

不同配置档次性能对比：

配置档次 纯文本PDF(秒/页) 含表格PDF(秒/页) 含公式PDF(秒/页) 内存占用
基础配置 1.8-2.2 4.5-5.0 6.0-6.5 <6GB
标准配置 1.0-1.3 2.8-3.2 4.0-4.5 <12GB
高性能配置 0.5-0.7 1.5-1.8 2.2-2.5 <20GB

4.2 处理流程优化

操作目标：优化文档处理流程，提高吞吐量
前置条件：已完成硬件资源调优
执行步骤：

  1. 配置批处理模式

    # 创建批处理配置文件
cat > batch_config.json << 'EOF'
{
  "input_dir": "/data/input",
  "output_dir": "/data/output",
  "processed_dir": "/data/processed",
  "error_dir": "/data/error",
  "file_pattern": "*.pdf",
  "recursive": false,
  "parallel_jobs": 4,
  "priority_levels": 3,
  "retry_count": 2,
  "output_formats": ["md", "json"],
  "log_file": "/var/log/mineru/batch.log"
}
EOF

  2. 设置定时任务

    # 创建批处理脚本
cat > /opt/mineru/scripts/auto_process.sh << 'EOF'
#!/bin/bash
CONFIG_FILE="/opt/mineru/batch_config.json"
LOG_FILE=$(jq -r '.log_file' $CONFIG_FILE)

echo "=== 批处理任务开始: $(date) ===" >> $LOG_FILE

# 运行批处理命令
mineru batch --config $CONFIG_FILE

echo "=== 批处理任务结束: $(date) ===" >> $LOG_FILE
echo "----------------------------------------" >> $LOG_FILE
EOF

chmod +x /opt/mineru/scripts/auto_process.sh

# 添加到crontab
(crontab -l 2>/dev/null; echo "*/30 * * * * /opt/mineru/scripts/auto_process.sh") | crontab -

  3. 启用缓存机制

    # 修改配置文件启用缓存
jq '.cache.enabled=true | .cache.dir="/opt/mineru/cache" | .cache.ttl="7d"' \
  ~/.mineru/config.json > ~/.mineru/config_with_cache.json

mv ~/.mineru/config_with_cache.json ~/.mineru/config.json

# 创建缓存目录
mkdir -p /opt/mineru/cache
chmod 777 /opt/mineru/cache

# 重启服务
docker compose -f docker/compose.yaml restart

结果验证：

# 检查批处理日志
tail -f /var/log/mineru/batch.log

# 验证缓存是否生效
ls -l /opt/mineru/cache

4.3 监控告警配置

操作目标：配置系统监控和告警机制
前置条件：已完成处理流程优化
执行步骤：

  1. 配置日志管理

    # 创建日志轮转配置
cat > /etc/logrotate.d/mineru << 'EOF'
/var/log/mineru/*.log {
  daily
  missingok
  rotate 14
  compress
  delaycompress
  notifempty
  create 0640 root adm
}
EOF

# 配置集中式日志
mkdir -p /var/log/mineru
chmod 777 /var/log/mineru

# 修改MinerU日志配置
jq '.logging.file-path="/var/log/mineru" | .logging.max-size="100MB" | .logging.max-backup=14 | .logging.format="json"' \
  ~/.mineru/config.json > ~/.mineru/config_with_log.json

mv ~/.mineru/config_with_log.json ~/.mineru/config.json

  2. 设置系统监控

    # 安装监控工具
sudo apt-get install -y prometheus node-exporter

# 配置Prometheus
cat > /etc/prometheus/prometheus.yml << 'EOF'
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'node'
    static_configs:
      - targets: ['localhost:9100']
  - job_name: 'mineru'
    static_configs:
      - targets: ['localhost:8000']
EOF

# 启动监控服务
sudo systemctl enable prometheus node-exporter
sudo systemctl restart prometheus node-exporter

  3. 配置告警脚本

    # 创建告警脚本
cat > /opt/mineru/scripts/alert.sh << 'EOF'
#!/bin/bash
# 简单告警脚本，可扩展为邮件、短信等方式

LOG_FILE="/var/log/mineru/alert.log"
THRESHOLD_CPU=80
THRESHOLD_MEM=85
THRESHOLD_DISK=85

# 检查CPU使用率
cpu_usage=$(top -bn1 | grep "Cpu(s)" | awk '{print $2 + $4}')
if (( $(echo "$cpu_usage > $THRESHOLD_CPU" | bc -l) )); then
  echo "[$(date)] 告警: CPU使用率过高 - $cpu_usage%" >> $LOG_FILE
  # 可添加实际告警通知代码
fi

# 检查内存使用率
mem_usage=$(free | awk '/Mem:/ {printf "%.2f", $3/$2 * 100}')
if (( $(echo "$mem_usage > $THRESHOLD_MEM" | bc -l) )); then
  echo "[$(date)] 告警: 内存使用率过高 - $mem_usage%" >> $LOG_FILE
  # 可添加实际告警通知代码
fi

# 检查磁盘使用率
disk_usage=$(df -h / | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $disk_usage -gt $THRESHOLD_DISK ]; then
  echo "[$(date)] 告警: 磁盘使用率过高 - $disk_usage%" >> $LOG_FILE
  # 可添加实际告警通知代码
fi
EOF

chmod +x /opt/mineru/scripts/alert.sh

# 添加到crontab
(crontab -l 2>/dev/null; echo "*/5 * * * * /opt/mineru/scripts/alert.sh") | crontab -

结果验证：

# 检查日志配置
logrotate -d /etc/logrotate.d/mineru

# 检查Prometheus状态
systemctl status prometheus

# 检查告警日志
tail /var/log/mineru/alert.log

4.4 版本管理与升级策略

操作目标：建立版本控制机制和升级流程
前置条件：已完成监控告警配置
执行步骤：

  1. 配置版本信息管理

    # 创建版本信息文件
cat > /opt/mineru/version_info.sh << 'EOF'
#!/bin/bash
# 版本信息管理脚本

VERSION_FILE="/opt/mineru/version_history.txt"

# 记录当前版本
record_version() {
  local component=$1
  local version=$2
  local notes=$3
  
  echo "[$(date +%Y-%m-%d_%H:%M:%S)] $component: $version - $notes" >> $VERSION_FILE
}

# 查询历史版本
query_version() {
  local component=$1
  grep "$component:" $VERSION_FILE | tail -n 5
}

# 初始化版本记录（首次运行）
if [ ! -f $VERSION_FILE ]; then
  echo "MinerU版本历史记录" > $VERSION_FILE
  echo "====================" >> $VERSION_FILE
fi
EOF

chmod +x /opt/mineru/version_info.sh

# 记录初始版本
/opt/mineru/version_info.sh record_version "MinerU" "v1.5.0" "初始部署"
/opt/mineru/version_info.sh record_version "Models" "v202312" "初始模型包"
/opt/mineru/version_info.sh record_version "Config" "v1" "标准配置"

  2. 制定升级流程

    # 创建升级脚本模板
cat > /opt/mineru/scripts/upgrade_template.sh << 'EOF'
#!/bin/bash
# MinerU升级脚本模板

# 升级前准备
echo "=== 升级准备 ==="
CURRENT_VERSION=$(mineru --version | awk '{print $2}')
NEW_VERSION="v1.5.1"  # 替换为实际新版本号

echo "当前版本: $CURRENT_VERSION"
echo "目标版本: $NEW_VERSION"

# 备份当前配置
echo "备份配置文件..."
cp ~/.mineru/config.json ~/.mineru/config_${CURRENT_VERSION}_backup.json

# 记录当前版本
/opt/mineru/version_info.sh record_version "MinerU" "$NEW_VERSION" "升级前备份"

# 停止服务
echo "停止服务..."
docker compose -f docker/compose.yaml down

# 执行升级操作（此处为示例，需根据实际升级包修改）
echo "执行升级..."
# 实际升级命令将在此处添加

# 启动服务
echo "启动服务..."
docker compose -f docker/compose.yaml up -d

# 验证升级结果
echo "验证升级结果..."
NEW_VERSION_ACTUAL=$(mineru --version | awk '{print $2}')
if [ "$NEW_VERSION_ACTUAL" == "$NEW_VERSION" ]; then
  echo "升级成功"
  /opt/mineru/version_info.sh record_version "MinerU" "$NEW_VERSION" "升级成功"
else
  echo "升级失败，正在回滚..."
  # 回滚操作
  docker compose -f docker/compose.yaml down
  # 恢复备份配置
  cp ~/.mineru/config_${CURRENT_VERSION}_backup.json ~/.mineru/config.json
  # 重新启动旧版本
  # 实际回滚命令将在此处添加
  /opt/mineru/version_info.sh record_version "MinerU" "$CURRENT_VERSION" "升级失败，已回滚"
fi
EOF

chmod +x /opt/mineru/scripts/upgrade_template.sh

  3. 建立备份策略

    # 创建备份脚本
cat > /opt/mineru/scripts/backup.sh << 'EOF'
#!/bin/bash
# 系统备份脚本

BACKUP_DIR="/opt/mineru/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/mineru_backup_$TIMESTAMP.tar.gz"

# 创建备份目录
mkdir -p $BACKUP_DIR

echo "创建备份: $BACKUP_FILE"

# 备份关键数据
tar -czf $BACKUP_FILE \
  ~/.mineru/config.json \
  /opt/mineru/models \
  /opt/mineru/data \
  /opt/mineru/scripts \
  /opt/mineru/version_history.txt

# 保留最近10个备份
ls -tp $BACKUP_DIR/*.tar.gz | grep -v '/$' | tail -n +11 | xargs -I {} rm -- {}

# 记录备份
/opt/mineru/version_info.sh record_version "Backup" "$TIMESTAMP" "系统备份"
echo "备份完成"
EOF

chmod +x /opt/mineru/scripts/backup.sh

# 添加到crontab，每周日凌晨3点执行备份
(crontab -l 2>/dev/null; echo "0 3 * * 0 /opt/mineru/scripts/backup.sh") | crontab -

结果验证：

# 检查版本记录
cat /opt/mineru/version_history.txt

# 执行测试备份
/opt/mineru/scripts/backup.sh

# 检查备份文件
ls -l /opt/mineru/backups

五、常见问题速查

5.1 部署阶段问题

问题1：模型文件加载失败

故障现象：启动服务时日志显示"ModelNotFoundError"或"FileNotFoundError"
排查流程：

  1. 检查模型路径配置：cat ~/.mineru/config.json | grep models-dir
  2. 验证模型文件存在性：ls -l /opt/mineru/models/pipeline
  3. 检查文件权限：ls -ld /opt/mineru/models

解决方案：

# 确认模型路径正确
jq '.["models-dir"].pipeline' ~/.mineru/config.json

# 如路径错误，修正配置
jq '.["models-dir"].pipeline="/opt/mineru/models/pipeline"' ~/.mineru/config.json > temp.json && mv temp.json ~/.mineru/config.json

# 检查并修复权限
sudo chown -R $USER:$USER /opt/mineru/models

问题2：依赖包安装失败

故障现象：pip安装依赖时出现"PackageNotFoundError"
排查流程：

  1. 检查依赖包缓存目录：ls /opt/mineru/deployment/mineru_offline_package/mineru_deps
  2. 确认pip命令参数：pip install --no-index --find-links=...
  3. 检查依赖包版本兼容性：grep "torch" requirements.txt

解决方案：

# 检查缺失的依赖包
pip install --no-index --find-links=../mineru_deps -r requirements.txt --dry-run

# 如发现缺失包，从其他来源获取并添加到依赖缓存
# 然后重新安装
pip install --no-index --find-links=../mineru_deps -r requirements.txt

5.2 运行阶段问题

问题3：处理大文件时内存溢出

故障现象：处理大文件时服务崩溃，日志显示"Out Of Memory"
排查流程：

  1. 检查系统内存使用：free -h
  2. 查看处理文件大小：ls -lh /opt/mineru/data/input/large_file.pdf
  3. 检查批处理配置：jq '.performance["batch-size"]' ~/.mineru/config.json

解决方案：

# 降低批处理大小
jq '.performance["batch-size"]=1' ~/.mineru/config.json > temp.json && mv temp.json ~/.mineru/config.json

# 启用内存优化模式
jq '.performance["memory-optimization"]=true' ~/.mineru/config.json > temp.json && mv temp.json ~/.mineru/config.json

# 重启服务
docker compose -f docker/compose.yaml restart

问题4：转换结果乱码或格式错误

故障现象：输出的Markdown文件中出现乱码或格式错乱
排查流程：

  1. 检查源PDF文件：pdftotext input.pdf - | less
  2. 验证字体支持：fc-list | grep -i "simhei\|song"
  3. 检查OCR配置：jq '.ocr' ~/.mineru/config.json

解决方案：

# 安装中文字体
sudo apt-get install -y fonts-wqy-microhei fonts-wqy-zenhei

# 启用OCR增强模式
jq '.ocr.enhance=true' ~/.mineru/config.json > temp.json && mv temp.json ~/.mineru/config.json

# 重新处理文件
mineru -p /data/input/problem_file.pdf -o /data/output/fixed_output.md --force-ocr

5.3 性能优化问题

问题5：处理速度远低于预期

故障现象：文档处理速度明显低于性能基准测试结果
排查流程：

  1. 检查CPU使用率：top | grep mineru
  2. 验证内存使用情况：free -h
  3. 检查磁盘I/O：iostat -x 1
  4. 确认配置是否应用：cat ~/.mineru/config.json

解决方案：

# 检查是否使用了正确的配置
jq '.performance' ~/.mineru/config.json

# 确保使用高性能配置（如适用）
ln -sf ~/.mineru/config_high.json ~/.mineru/config.json

# 检查是否有其他进程占用资源
ps aux --sort=-%cpu | head -10

# 如磁盘I/O高，调整缓存设置
jq '.cache.enabled=true | .cache.size-limit="10GB"' ~/.mineru/config.json > temp.json && mv temp.json ~/.mineru/config.json

# 重启服务
docker compose -f docker/compose.yaml restart

5.4 离线特有问题

问题6：证书过期导致Docker镜像构建失败

故障现象：离线环境中构建Docker镜像时出现证书错误
排查流程：

  1. 检查系统时间：date
  2. 查看证书状态：openssl x509 -in /etc/ssl/certs/ca-certificates.crt -noout -dates
  3. 检查Docker配置：cat /etc/docker/daemon.json

解决方案：

# 同步系统时间（离线环境可能时间不同步）
sudo date -s "2023-12-01 12:00:00"  # 设置为正确日期

# 禁用Docker TLS验证（仅离线环境）
echo '{"insecure-registries": ["localhost:5000"]}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker

问题7：USB传输文件后权限问题

故障现象：从USB传输文件后，服务无法读取文件
排查流程：

  1. 检查文件权限：ls -l /opt/mineru/data/input
  2. 查看文件所有者：ls -ld /opt/mineru/data/input
  3. 检查SELinux/AppArmor状态：sestatus

解决方案：

# 修复文件权限
sudo chown -R $USER:$USER /opt/mineru/data
sudo chmod -R 755 /opt/mineru/data

# 如使用SELinux，调整上下文
sudo chcon -Rt svirt_sandbox_file_t /opt/mineru/data

六、部署架构与流程

下图展示了MinerU离线部署的完整架构和数据流程：

MinerU离线部署数据流程图

该架构包含以下关键组件：

  1. 输入层：处理用户上传的PDF文档
  2. 预处理层：负责文档解析、页面分割和初步分析
  3. 处理引擎层：包含OCR、表格识别、公式提取等核心功能模块
  4. 模型服务层：提供本地部署的AI模型服务
  5. 输出层：生成Markdown和JSON格式的结果文件
  6. 监控层：跟踪系统性能和处理状态

通过这种分层架构，MinerU能够高效处理各种复杂文档，同时保持系统的可扩展性和可维护性。离线部署模式确保了在没有外部网络连接的环境中也能稳定运行，满足企业级数据安全和隐私保护要求。

MinerU
Transforms complex documents like PDFs into LLM-ready markdown/JSON for your Agentic workflows.
项目地址：https://gitcode.com/GitHub_Trending/mi/MinerU
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
27
13
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
642
4.19 K
pytorchpytorch
Ascend Extension for PyTorch
Python
478
579
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
934
841
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
386
272
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.52 K
867
flutter_flutterflutter_flutter
暂无简介
Dart
885
211
cangjie_runtimecangjie_runtime
仓颉编程语言运行时与标准库。
Cangjie
161
922
MindSpeed-LLMMindSpeed-LLM
昇腾LLM分布式训练框架
Python
139
163
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Java
69
21