ocrbase 是一个免费的自托管 PDF 智能解析服务，基于 PaddleOCR-VL 视觉语言模型，能将 PDF 文档一键转换为 Markdown 文本或结构化 JSON 数据。本文带你用 Docker Compose 一键部署 ocrbase 完整生产环境，并附 PaddleOCR-VL 的 GPU 配置方法，几分钟就能拥有自己的文档解析 API。

📌核心关键词：ocrbase 自托管 / Docker Compose 部署 / PaddleOCR-VL GPU 配置

一、ocrbase 能做什么？

在部署之前，先了解你即将运行的是什么：

整套服务完全异步、基于 BullMQ 队列，可以批量处理上千份文档。

二、部署前环境准备

部署 ocrbase 只需要很少的前置条件：

💡 小贴士：如果你已有云端的 PaddleOCR-VL 服务，直接跳过 GPU 配置章节，把它当作一个外部服务接入即可。

三、克隆代码

git clone https://gitcode.com/gh_mirrors/oc/ocrbase cd ocrbase

项目采用 Monorepo 结构，前后端分别位于 apps/server 和 apps/web 目录，数据库模型定义在 packages/db：

• 后端 API（Elysia + Bun 编译产物）：apps/server/Dockerfile
• 前端界面（TanStack Start）：apps/web/Dockerfile
• 编排总入口：docker-compose.yml

四、Docker Compose 一键启动：三种 profile 用法

打开 docker-compose.yml，可以看到项目通过profiles把服务分成了三组，按需启动：

1️⃣ 仅启动基础设施（开发模式）

docker compose up -d

这一条命令会拉起三个支撑服务并自动初始化存储桶：

2️⃣ 完整生产环境一键部署

docker compose --profile prod up -d

该命令会构建并启动server（API 服务，端口 3000）、web（前端界面，端口 3001）、worker（后台任务处理器）三个容器，它们会自动等待 Postgres 和 Redis 健康检查通过后再启动。参见 docker-compose.yml 生产服务段。

🎯 这就是"一键部署"的含义：一条命令，编译镜像 + 启动全部业务容器，宿主机无需安装 Bun 等运行时。

3️⃣ GPU 模式：启动 PaddleOCR-VL

docker compose --profile gpu up -d

若要生产服务 + GPU OCR 一起跑：

docker compose --profile prod --profile gpu up -d

五、PaddleOCR-VL GPU 配置详解

ocrbase 本身不包含OCR 引擎，它需要指向一个运行中的 PaddleOCR-VL 实例。docker-compose.yml已内置官方 NVIDIA GPU 镜像，关键配置见 docker-compose.yml GPU 段：

paddleocr: image: ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-nvidia-gpu ports: - "8080:8080" deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]

📌配置要点：

• GPU 预留：device_ids: ["0"]表示使用第一块显卡，多卡环境可改为["0", "1"]或用环境变量注入
• 健康检查：容器会每 30 秒探测http://localhost:8080/health，模型加载较慢，预留了 300 秒的启动宽限期，请耐心等待
• 多卡/指定显卡：修改device_ids即可，无需改动其他配置

六、环境变量速查表（.env）

在生产目录根下创建.env文件，完整模板参考 docs/SELF_HOSTING.md 环境变量段：

# ===== 必填 ===== DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ocrbase BETTER_AUTH_SECRET=至少32个字符的随机密钥 BETTER_AUTH_URL=http://localhost:3000 CORS_ORIGINS=http://localhost:3001 REDIS_URL=redis://localhost:6379 # ===== OCR 服务（核心）===== # 本机 GPU 部署时填 http://localhost:8080，外部服务则填对应地址 PADDLE_OCR_URL=http://localhost:8080 PADDLEOCR_VL_API_KEY=local PADDLE_OCR_TIMEOUT_MS=900000 WORKER_CONCURRENCY=1 # ===== 可选：S3/MinIO 存储 ===== S3_ENABLED=true S3_ENDPOINT=http://localhost:9000 S3_BUCKET=ocrbase S3_ACCESS_KEY=minioadmin S3_SECRET_KEY=minioadmin # ===== 可选：LLM（仅 /v1/extract 结构化抽取需要）===== LLM_PROVIDER=openrouter OPENROUTER_API_KEY=your-openrouter-api-key

🔑三个最常踩坑的变量：

七、验证部署是否成功

🩺三步验证法：

第一步：查看容器状态

docker compose ps

所有服务应处于running（或healthy）状态。

第二步：访问健康检查接口

curl http://localhost:3000/v1/health/live # 存活检查 curl http://localhost:3000/v1/health/ready # 就绪检查（确认数据库/队列已连通）

第三步：打开 OpenAPI 交互文档

浏览器访问http://localhost:3000/openapi，即可在 Swagger 风格界面中直接测试所有接口；前端界面在http://localhost:3001。

一切就绪后，发一个测试解析请求：

curl -X POST http://localhost:3000/v1/parse \ -H "Authorization: Bearer 你的API_KEY" \ -F "file=@document.pdf"

八、进阶：开发模式与大文档调优

本地开发（需要安装 Bun）：

bun install # 安装依赖 cp .env.example .env # 复制并编辑环境变量 bun run db:push # 初始化数据库表结构 bun run dev # 启动 API + worker（热重载）

大 PDF 调优建议：

• 调大 OCR 请求超时：PADDLE_OCR_TIMEOUT_MS=900000（15 分钟）
• 降低并发：WORKER_CONCURRENCY=1
• 队列并发数通过QUEUE_CONCURRENCY环境变量控制（默认 3）

日常运维命令：

九、常见问题排查

总结

🎉 回顾一下这条"一键部署"路线：

1. 克隆代码→git clone拿到仓库
2. 配置.env→ 重点设置PADDLE_OCR_URL等 4 个必填变量
3. 一键启动→docker compose --profile prod --profile gpu up -d
4. 验证→/v1/health/ready+/openapi文档页

至此，你就在自家服务器（或一台带 GPU 的机器）上拥有了一个完全可控的免费文档解析平台：PDF 进、Markdown / 结构化 JSON 出，还能通过 WebSocket 实时跟踪每一份文档的处理进度。完整的 API 端点清单与技术栈说明，可继续阅读 docs/SELF_HOSTING.md 官方自托管文档。