WSL2 + Conda 环境下MinerU 4.x GPU 服务部署与 systemd 常驻指南

记录一次在 WSL2 环境中部署 MinerU V1 解析服务（mineru-kit api-server）的完整过程，包括 systemd 用户服务常驻、CUDA 链接问题排障，以及日常维护命令速查。

一、主机环境

项目	配置
系统	Windows 11 + WSL2（Ubuntu）
GPU	NVIDIA 桌面级显卡，显存 8GB （compute capability 8.9 ，对应 `sm_89`，如 RTX 4070/4060 系列）
GPU 驱动	Windows 宿主机驱动，WSL 通过 `/usr/lib/wsl/lib/` 共享 `libcuda.so.1`
Python 环境	Miniconda，独立环境 `mineru`（Python 3.10），位于 `~/miniconda3/envs/mineru`
CUDA	PyTorch/conda 携带的 CUDA 13 运行时（`libcudart.so.13`），无独立系统级 CUDA Toolkit 安装
模型	MinerU standard 档模型已提前下载至本地缓存，模型源为 ModelScope
服务端口	8000（V1 解析 API）

二、部署步骤

1. 安装与模型准备

bash 复制代码

# 创建并激活 conda 环境
conda create -n mineru python=3.10 -y
conda activate mineru
# 安装 mineru-kit（含 V1 API 服务）
pip install -U "mineru-kit"
# 指定国内模型源并预下载模型（终端中执行）
export MINERU_MODEL_SOURCE=modelscope
mineru-models download

8GB 显存跑 standard 档可行，但需要留意并发与上下文长度；日常单任务解析没问题。

2. 前台试运行（验证服务本身可用）

bash 复制代码

conda activate mineru
export MINERU_MODEL_SOURCE=modelscope
mineru-kit api-server --tier standard --port 8000

看到 Uvicorn running on http://127.0.0.1:8000 后，另开终端验证：

bash 复制代码

curl -s http://127.0.0.1:8000/v1/health

浏览器访问 http://localhost:8000/docs 还能看到 FastAPI 自动生成的交互式文档（WSL2 的 localhost 转发使宿主机可直接访问）。

⚠️ 此方式下服务随终端关闭而停止，且 flashinfer JIT 编译已在此时完成并缓存到 ~/.cache/flashinfer/。

3. 配置 systemd 用户服务（常驻）

创建服务文件 ~/.config/systemd/user/mineru-api.service：

ini 复制代码

[Unit]
Description=MinerU V1 API Server
After=network.target
[Service]
ExecStart=%h/miniconda3/envs/mineru/bin/mineru-kit api-server --tier standard --port 8000 --host 0.0.0.0
Environment="PATH=%h/miniconda3/envs/mineru/bin:/usr/local/cuda/bin:/usr/bin:/bin"
Environment="MINERU_MODEL_SOURCE=modelscope"
Environment="LD_LIBRARY_PATH=%h/miniconda3/envs/mineru/lib:/usr/lib/wsl/lib:/usr/local/cuda/lib64"
Environment="LIBRARY_PATH=%h/miniconda3/envs/mineru/lib:%h/miniconda3/envs/mineru/lib/python3.10/site-packages/nvidia/cu13/lib:/usr/lib/wsl/lib"
Environment="CONDA_PREFIX=%h/miniconda3/envs/mineru"
Restart=on-failure
RestartSec=5
WorkingDirectory=%h
StandardOutput=append:%h/.mineru/api-server.log
StandardError=append:%h/.mineru/api-server.err.log
[Install]
WantedBy=default.target

关键环境变量说明：

变量	作用
`LD_LIBRARY_PATH`	运行时动态库加载路径；`/usr/lib/wsl/lib` 是 WSL 驱动库（`libcuda.so.1`）所在位置
`LIBRARY_PATH`	编译链接期 gcc/ld 查找 `-lxxx` 的路径；flashinfer JIT 链接依赖它
`MINERU_MODEL_SOURCE`	强制走 ModelScope 源，国内网络更稳定
`%h`	systemd 用户服务的 home 目录占位符
启用服务：

bash 复制代码

# 若 WSL 未启用 systemd，先在 /etc/wsl.conf 中加入 [boot] systemd=true
systemctl --user daemon-reload
systemctl --user enable --now mineru-api
# 允许用户服务在无登录会话时保持运行（WSL 全部终端关闭后服务不停）
sudo loginctl enable-linger your-username

4. CUDA 链接问题排障（本次部署踩的坑）

systemd 启动时 flashinfer 报错：

复制代码

/home/your-username/miniconda3/envs/mineru/bin/ld: cannot find -lcudart
/home/your-username/miniconda3/envs/mineru/bin/ld: cannot find -lcuda

原因分析：

链接器查找 -lxxx 用的是 -L 路径和 LIBRARY_PATH，不吃 LD_LIBRARY_PATH（后者只管运行时加载）
conda 环境的 libcudart.so 位于 env/lib/，但 flashinfer 的默认链接命令指向 env/lib64/
WSL 的 /usr/lib/wsl/lib/ 只有运行时文件 libcuda.so.1，缺少无版本号后缀的开发链接文件 libcuda.so
修复：

bash 复制代码

# 补建 libcuda 开链接符号（指到 WSL 驱动库）
ln -sf /usr/lib/wsl/lib/libcuda.so.1 ~/miniconda3/envs/mineru/lib/libcuda.so
# 清理 flashinfer 编译失败的缓存，强制重新编译
rm -rf ~/.cache/flashinfer
# 重启服务
systemctl --user daemon-reload
systemctl --user restart mineru-api

💡 首次启动 flashinfer 会 JIT 编译 CUDA 算子（针对 sm_89 架构），耗时几分钟属正常，编译成功后缓存复用，后续启动秒进模型加载。

5. 验证部署

bash 复制代码

# 服务状态
systemctl --user status mineru-api
# 健康检查
curl -s http://127.0.0.1:8000/v1/health
# 同步解析测试（返回 JSON，内嵌 Markdown）
curl -s 'http://127.0.0.1:8000/v1/file_parse?tier=standard' \
  -F 'files=@test.pdf' -o result.json

宿主机浏览器访问 `http://localhost:8000/docs` 即可使用 Swagger UI 交互调试全部接口；`http://localhost:8000/openapi.json` 可导出 OpenAPI 规范导入 Postman/Apifox。

三、日常维护命令速查

服务管理

bash 复制代码

systemctl --user start mineru-api      # 启动
systemctl --user stop mineru-api       # 停止
systemctl --user restart mineru-api    # 重启
systemctl --user status mineru-api     # 查看状态
systemctl --user disable mineru-api    # 取消开机自启

⚠️ 用户级服务操作一律加 --user，不要加 sudo ------sudo systemctl ... 会切到 root，报 "Unit not found"。

日志查看

bash 复制代码

tail -f ~/.mineru/api-server.log       # 实时跟踪访问日志
tail -f ~/.mineru/api-server.err.log   # 实时跟踪错误日志
journalctl --user -u mineru-api -f     # systemd 侧实时日志
journalctl --user -u mineru-api -b     # 本次开机以来的日志

资源与进程

bash 复制代码

ss -tlnp | grep 8000                   # 确认端口监听
nvidia-smi                             # GPU 显存占用（模型常驻显存）
pgrep -af mineru-kit                   # 查看进程

更新与缓存

bash 复制代码

# 升级 mineru-kit（先停服务）
systemctl --user stop mineru-api
conda activate mineru
pip install -U "mineru-kit"
systemctl --user start mineru-api
# flashinfer/编译缓存出问题时清空重建
rm -rf ~/.cache/flashinfer
systemctl --user restart mineru-api

修改配置后生效

bash 复制代码

nano ~/.config/systemd/user/mineru-api.service
systemctl --user daemon-reload         # 改完 service 文件必做
systemctl --user restart mineru-api

四、注意事项

端口冲突 ：systemd 服务与手动启动的进程不能同时绑 8000，切换启动方式前先 pkill -f "mineru-kit api-server"。
暴露范围 ：当前配置 --host 0.0.0.0 意味着局域网可访问（需宿主机防火墙放行 8000 + portproxy 转发 WSL IP）。若仅本机使用，建议改回 127.0.0.1；若对外提供，务必加 --api-key <secret>。
8GB 显存：standard 档模型常驻显存约 6--7GB，解析期间避免同时跑其他 CUDA 程序；并发解析任务保持 1--2 为宜。
WSL 重启 ：wsl --shutdown 后服务会随 systemd 自动拉起（已 enable + linger），首次启动含 flashinfer 缓存加载，约 1--2 分钟就绪。
至此，一套完整的 GPU 加速 MinerU 解析服务就稳定跑在 WSL2 里了------宿主机浏览器打开 http://localhost:8000/docs 即可用，长期无人值守也不怕 👌

WSL2 + Conda 环境下MinerU 4.x GPU 服务部署与 systemd 常驻指南

一、主机环境

二、部署步骤

1. 安装与模型准备

2. 前台试运行（验证服务本身可用）

3. 配置 systemd 用户服务（常驻）

4. CUDA 链接问题排障（本次部署踩的坑）

5. 验证部署

宿主机浏览器访问 http://localhost:8000/docs 即可使用 Swagger UI 交互调试全部接口；http://localhost:8000/openapi.json 可导出 OpenAPI 规范导入 Postman/Apifox。

三、日常维护命令速查

服务管理

日志查看

资源与进程

更新与缓存

修改配置后生效

四、注意事项

宿主机浏览器访问 `http://localhost:8000/docs` 即可使用 Swagger UI 交互调试全部接口；`http://localhost:8000/openapi.json` 可导出 OpenAPI 规范导入 Postman/Apifox。