MinerU Docker 部署实战：基于 vLLM 镜像构建、容器启动与 Compose 多服务编排

MinerU 提供了便捷的 Docker 部署方式，可帮助你在不手工折腾 Python 环境、CUDA 依赖和模型下载的前提下，快速搭建文档解析服务并规避环境兼容问题。本文以官方文档 docs/zh/quick_start/docker_deployment.md 为主线，完整覆盖"构建镜像 → 启动容器 → Docker Compose 编排四类服务"的全部操作，并结合仓库中的 docker/compose.yaml、Dockerfile 与 CLI 入口源码，说明每个参数背后的实际含义。

适用环境与限制

在开始部署前，先明确 Docker 方案的适用边界（官方文档中的明确警告）：

• Docker 部署仅适用于 Linux，以及支持 WSL2 的 Windows 环境；
• 不要在 macOS 上使用 Docker 部署 MinerU。由于 Docker 环境下无法调用 macOS 上的 MPS 和 MLX 加速能力，Apple Silicon 设备无法通过该方案获得预期加速效果，macOS 用户建议使用本地 pip 安装方式。

使用 Dockerfile 构建镜像

国内网络环境下的官方构建步骤为：

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/Dockerfile
docker build -t mineru:latest -f Dockerfile .

这条命令拉取的是仓库中的 docker/china/Dockerfile。为了理解构建产物里到底包含什么，下面逐段解读该 Dockerfile 的关键指令：

# 基础镜像：vLLM 官方镜像（国内版走 DaoCloud 镜像源）
# 支持 x86_64 与 ARM(AArch64) 架构
FROM docker.m.daocloud.io/vllm/vllm-openai:v0.21.0
# FROM docker.m.daocloud.io/vllm/vllm-openai:v0.21.0-cu129   # CUDA 12.9 环境请切换为此镜像

# 安装 opencv 依赖 libgl 与中文字体 Noto CJK
RUN apt-get update && \
    apt-get install -y fonts-noto-core fonts-noto-cjk fontconfig libgl1 && \
    fc-cache -fv && apt-get clean && rm -rf /var/lib/apt/lists/*

# 安装最新版 MinerU 核心包
RUN python3 -m pip install -U 'mineru[core]>=3.4.0' -i https://mirrors.aliyun.com/pypi/simple --break-system-packages && \
    python3 -m pip cache purge

# 构建阶段即下载全部模型
RUN /bin/bash -c "mineru-models-download -s modelscope -m all"

# 默认从本地加载模型
ENTRYPOINT ["/bin/bash", "-c", "export MINERU_MODEL_SOURCE=local && exec \"$@\"", "--"]

由此可以得到几个关键结论：

1. 镜像内置 vLLM 推理环境。MinerU 的 Docker 镜像以 vllm/vllm-openai 为基础镜像，因此默认集成了 vllm 推理加速框架和必需依赖，满足条件时可直接使用 vLLM 加速 VLM 模型推理。
2. 国内版与海外版仅差在两处：docker/china/Dockerfile 使用 DaoCloud 镜像源 docker.m.daocloud.io/vllm/vllm-openai 并通过阿里云 PyPI 镜像安装依赖、从 ModelScope 下载模型；docker/global/Dockerfile 则直接拉取官方 vllm/vllm-openai 镜像、走 PyPI 官方源并从 Hugging Face 下载模型。
3. CUDA 版本二选一。当前 Dockerfile 默认基础镜像 v0.21.0 对应 CUDA 13.0 兼容环境；如果你的环境需要 CUDA 12.9 兼容镜像，请将 Dockerfile 顶部的默认 FROM 注释掉，并启用注释中的 v0.21.0-cu129 基础镜像。
4. 模型在构建期完成下载。mineru-models-download -s modelscope -m all 在镜像构建阶段就把全部模型下载到镜像内，配合 ENTRYPOINT 中固定的 MINERU_MODEL_SOURCE=local，容器启动后无需联网拉取模型。这也是 compose.yaml 各服务统一设置 MINERU_MODEL_SOURCE: local 的原因。

使用 vLLM 加速 VLM 推理的前置条件

官方文档明确列出了使用 vllm 加速 VLM 模型推理需要满足的条件：

• 设备包含 Volta 及以后架构的显卡，且可用显存 ≥ 8G（Dockerfile 注释中也标注了支持范围为 Compute Capability 7.0 ~ 12.1，即 Volta、Turing、Ampere、Ada Lovelace、Hopper、Blackwell 架构）；
• 物理机的显卡驱动应支持所选基础镜像对应的 CUDA 运行时版本：默认 v0.21.0 需要 CUDA 13.0 兼容驱动，v0.21.0-cu129 需要 CUDA 12.9 兼容驱动，可通过 nvidia-smi 检查驱动版本；
• Docker 容器能够访问物理机的显卡设备（即宿主机已安装并可用 NVIDIA Container Toolkit，容器启动时通过 --gpus 参数注入）。

启动 Docker 容器（交互式使用）

构建完成后，可用如下命令进入容器的交互式终端：

docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 -p 7860:7860 -p 8000:8000 -p 8002:8002 \
  --ipc=host \
  -it mineru:latest \
  /bin/bash

参数含义与端口规划（结合 compose.yaml 的服务定义可一一对应）：

参数/端口	作用	对应服务
--gpus all	将宿主机全部 GPU 注入容器	所有需要 GPU 的服务
--shm-size 32g	扩大共享内存，满足大模型推理的数据交换需求	—
--ipc=host	共享宿主机 IPC 命名空间，避免 PyTorch 多进程通信时共享内存不足	—
-p 30000:30000	OpenAI 兼容接口（vLLM OpenAI Server）	mineru-openai-server
-p 8000:8000	Web API（FastAPI）	mineru-api
-p 8002:8002	多服务/多 GPU 编排统一入口	mineru-router
-p 7860:7860	Gradio 可视化前端	mineru-gradio

执行该命令后，你将进入容器交互式终端，可以直接运行 MinerU 相关命令（如 mineru -p <input> -o <output>）来使用文档解析功能。

如果你不想进入 shell，也可以直接把命令末尾的 /bin/bash 替换为服务启动命令（例如 mineru-api、mineru-gradio）来直接启动服务，各命令行入口的详细参数请参考官方文档通过命令启动服务。

通过 Docker Compose 直接启动服务

除了交互式容器，官方还提供了 docker/compose.yaml，可以一键拉起 MinerU 的多个服务。下载方式：

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

compose.yaml 中定义了 4 个服务，各自通过 profiles 分组，可按需选择启动：

服务名	profile	端口	入口命令（对应源码）
mineru-openai-server	openai-server	30000	mineru/cli/vlm_server.py
mineru-api	api	8000	mineru/cli/fast_api.py
mineru-router	router	8002	mineru/cli/router.py
mineru-gradio	gradio	7860	mineru/cli/gradio_app.py

上表中四个命令名到源码入口的对应关系，可在 pyproject.toml 的 [project.scripts] 段中确认：mineru-openai-server = "mineru.cli.vlm_server:openai_server"、mineru-api = "mineru.cli.fast_api:main"、mineru-router = "mineru.cli.router:main"、mineru-gradio = "mineru.cli.gradio_app:main"。

[!NOTE]

• compose.yaml 中包含 MinerU 的多个服务配置，你可以根据需要选择启动特定的服务；
• 不同的服务可能有额外的参数配置，可以在 compose.yaml 文件中查看并编辑；
• 由于 vllm 推理加速框架预分配显存的特性，你可能无法在同一台机器上同时运行多个 vllm 服务，因此请确保在启动 vlm-openai-server 服务或使用 vlm-vllm-engine 后端时，其他可能使用显存的服务已停止。

四个服务共享的容器级配置同样值得注意：每个服务都设置了 MINERU_MODEL_SOURCE: local（与镜像 ENTRYPOINT 一致，始终使用镜像内预置模型）、ipc: host、ulimits（memlock: -1 用于 vLLM 显存锁定、stack: 67108864）、NVIDIA GPU 设备预留（device_ids: ["0"]，多卡时改为 ["0", "1"]），并带有基于 curl /health 的健康检查。

启动 OpenAI 兼容接口服务，并通过 vlm-http-client 连接

docker compose -f compose.yaml --profile openai-server up -d

该服务即 mineru-openai-server，在 30000 端口暴露 OpenAI 兼容协议。此时可以在另一个终端（例如一台只有 CPU 与网络的机器）中通过 http client 连接：

mineru -p <input_path> -o <output_path> -b vlm-http-client -u http://<server_ip>:30000

[!TIP] 这种"服务端跑 vLLM、客户端只发 HTTP 请求"的分离部署，客户端侧（vlm-http-client 后端）不要求本地安装 torch/vLLM 环境，适合把推理算力集中到 GPU 服务器上、解析调度分散到多台机器。

启动 Web API 服务

docker compose -f compose.yaml --profile api up -d

服务启动后，可在浏览器中访问 http://<server_ip>:8000/docs 查看 API 文档（由 mineru/cli/fast_api.py 实现的 FastAPI 应用，提供 /health、/tasks、/file_parse 等接口）。

启动 MinerU Router 服务

docker compose -f compose.yaml --profile router up -d

[!TIP]

• 默认配置会以 --local-gpus auto 模式在容器内自动拉起本地 worker，并通过 http://<server_ip>:8002/docs 暴露统一入口；

• 如果你希望聚合已有的 mineru-api 服务而不是启动本地 worker，可直接参考 compose.yaml 中 mineru-router 服务下的注释示例，改为使用 --local-gpus none 加 --upstream-url：

  # To aggregate existing mineru-api services instead of starting local workers:
  # --local-gpus none
  # --upstream-url http://mineru-api:8000
  # --upstream-url http://mineru-api-2:8000
  

从 mineru/cli/router.py 源码结构看，router 对外暴露与 mineru-api 一致的 /health、/tasks、/file_parse、/tasks/{task_id}、/tasks/{task_id}/result 接口，并对本地 worker 与远端 upstream 做健康检查与故障转移（源码中定义了 UPSTREAM_FAILURE_THRESHOLD、WORKER_HEALTH_FAILURE_RESTART_THRESHOLD 等重试/重启阈值），适用于多服务、多 GPU 的统一入口部署场景。

启动 Gradio WebUI 服务

docker compose -f compose.yaml --profile gradio up -d

[!TIP] 在浏览器中访问 http://<server_ip>:7860 使用 Gradio WebUI。

compose.yaml 中值得留意的进阶参数

除了服务启动方式，compose.yaml 的注释中保留了几个生产部署时常用的调优开关（默认均为注释状态）：

• --gpu-memory-utilization 0.5：vLLM 引擎参数。遇到显存不足时，通过它降低 KV cache 占比；如果显存问题依旧，可进一步降到 0.4 或更低。mineru-openai-server、mineru-api、mineru-router、mineru-gradio 四个服务均预留了该参数位。
• --allow-public-http-client：安全开关，默认关闭。当服务绑定到 0.0.0.0 或 :: 时，显式加上它才会重新启用 *-http-client 后端和 server_url 参数——官方提示这属于接受 SSRF 风险的操作，仅在必要时开启。
• --enable-api false（gradio 专用）：禁用 WebUI 内的 API 能力。
• --max-convert-pages 20（gradio 专用）：限制单次转换的页数上限。
• device_ids: ["0"]（GPU 预留）：修改为 ["0", "1"] 即可为容器分配多块 GPU。

小结

MinerU 的 Docker 方案把"环境准备"压缩为两步：一条 docker build（或直接用预构建镜像）加一条 docker compose up。镜像层面通过 vLLM 基础镜像 + 预置模型 + MINERU_MODEL_SOURCE=local 保证了离线可用性；编排层面通过 4 个 profile 覆盖 OpenAI 兼容推理、Web API、多 GPU 路由聚合与可视化前端四类典型部署形态。部署前只需确认三条硬性前提：Linux/WSL2 环境、Volta 及以上架构且显存 ≥ 8G 的 NVIDIA GPU、以及驱动版本与所选基础镜像的 CUDA 版本（13.0 或 12.9）匹配，其余细节均可在 docker/china/Dockerfile、docker/global/Dockerfile 与 docker/compose.yaml 中按需调整。