MinerU 生产级部署实战：基于 Docker Compose 与 vLLM 的高可用解析服务搭建

1. 从开发到生产：为什么需要高可用的MinerU解析服务？

如果你用过MinerU，肯定会被它强大的PDF解析能力惊艳到。无论是复杂的学术论文、满是表格的财务报表，还是图文混排的技术手册，它都能给你整得明明白白，输出结构清晰的Markdown或JSON。在开发测试阶段，我们可能就简单跑个容器，能用就行。但一旦要把它交给一个研发团队，或者集成到某个业务系统里，事情就完全不一样了。

想象一下这个场景：你的团队正在做一个智能知识库项目，每天有上百份PDF文档需要自动解析入库。突然，负责解析的MinerU服务因为内存溢出挂掉了，所有文档处理流程中断，业务方电话直接打爆。或者，某个同事上传了一个超大文件，直接把服务卡死，其他人全都得等着。又或者，你想升级一下版本，结果发现配置散落在各处，根本不敢动。这些，都是“玩具级”部署转向“生产级”部署时必须解决的问题。

生产环境的核心诉求就三个词：稳定、可扩展、易维护。稳定意味着服务要7x24小时在线，不能动不动就崩；可扩展意味着当业务量上来时，我们能平滑地增加处理能力；易维护则要求我们的部署清晰、配置集中、监控到位，出了问题能快速定位和恢复。

这就是为什么我们不能满足于一个简单的 docker run 命令。我们需要一套完整的方案，把MinerU的vLLM后端、API服务、Web界面，以及周边的监控、日志、数据持久化等，像搭积木一样有机地组合起来。而 Docker Compose 正是实现这一目标的利器。它用一个YAML文件就能定义和管理多个相互关联的容器，清晰地描述服务间的依赖和配置，让我们的部署从“手工脚本”升级为“声明式编排”。结合vLLM的高性能推理后端，我们就能构建出一个既强大又可靠的生产级PDF解析服务集群。

接下来，我就带你一步步搭建这个高可用服务。我会分享我实际踩过的坑、调优的参数，以及如何让整个系统在生产环境中稳稳地跑起来。

2. 环境准备与Docker化基石

工欲善其事，必先利其器。在开始编排我们的豪华服务舰队之前，得先把基地建好。这里没有太多黑科技，但每一步的扎实程度，都决定了后续运维的幸福感。

2.1 系统与硬件要求

首先看看你的“地基”是否牢固。MinerU虽然提供了轻量化的体验，但在生产环境下，尤其是启用vLLM和AI增强功能时，对资源还是有一定要求的。

• 操作系统：主流的Linux发行版是首选，比如 Ubuntu 20.04 LTS 或 CentOS 7/8。我强烈推荐在服务器环境使用Linux，无论是稳定性还是社区支持都最好。当然，如果你在macOS上做开发测试，或者用Windows 10/11配合WSL2，也完全没问题。
• 硬件配置：这是决定性能的关键。
  • CPU：至少4核，建议8核或以上。PDF解析，尤其是OCR和版面分析，是计算密集型任务。
  • 内存：最低8GB。这是硬门槛，低于这个值服务可能都起不来。对于生产环境，16GB是起步建议，如果处理大量或复杂文档，32GB会更从容。
  • 存储：至少预留20GB可用空间。主要用于存放Docker镜像、模型文件（如果本地加载）以及临时缓存。强烈建议使用SSD，能极大提升模型加载和文档读取速度。
  • GPU（可选但推荐）：如果你需要用到MinerU的AI增强解析功能（比如基于视觉语言模型的复杂表格理解），那么一块NVIDIA GPU会带来质的飞跃。显存建议8GB起步，例如RTX 3070、RTX 4080，或者Tesla T4/V100这类计算卡。没有GPU也能运行，部分高级功能会回退到CPU模式。

2.2 一站式搞定Docker环境

现在，我们开始安装Docker和Docker Compose。别去官网一个个找包了，我习惯用一个经过验证的一键脚本，快速又省心。

打开你的终端，执行下面这条命令：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

这个脚本会自动检测你的系统，然后安装或更新Docker Engine、Docker CLI和Docker Compose插件。全程自动化，你只需要看着它跑完就行。

安装完成后，为了以后不用每次都 sudo，把当前用户加入 docker 组：

sudo usermod -aG docker $USER

重要提示：执行完上面这条命令后，你需要完全退出当前终端会话，然后重新登录，这个组权限变更才会生效。你可以直接关闭终端窗口再打开，或者输入 exit 退出当前shell再重新连接。

最后，验证一下安装是否成功：

docker --version
docker compose version

如果两行命令都正确输出了版本号，那么恭喜你，Docker地基已经打好了。

2.3 配置GPU支持（如果可用）

如果你有NVIDIA GPU并且打算使用，那么还需要安装 NVIDIA Container Toolkit。这相当于让Docker容器能直接调用宿主机的GPU驱动。

对于Ubuntu系统，可以按以下步骤操作：

# 添加NVIDIA容器工具包仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 更新并安装
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 重启Docker服务
sudo systemctl restart docker

安装完成后，运行一个测试容器来验证GPU是否可以被Docker识别：

docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-s