kexueadmin
/
paper-burner
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
paper-burner/workers/pb-ocr-proxy/DEPLOY.md

10 KiB
Raw Blame History

PB OCR Proxy (Cloudflare Worker) - 部署与使用指南

单个 Worker 同时支持 MinerU 与 Doc2X 两种 OCR 服务。无需 Vercel 配置，直接在 Cloudflare 控制台部署即可使用。

🚀 Fast Deploy · 快速部署

本节用最短路径告诉你如何上线与如何在 Paper Burner X 里配置。

1) 环境变量一览

  • 必选（至少二选一）：
    • Secret MINERU_API_TOKEN（MinerU 令牌）
    • Secret DOC2X_API_TOKEN（Doc2X 令牌）
  • 可选（推荐生产）：
    • Variable ENABLE_AUTH = true|false（是否开启鉴权）
    • Secret AUTH_SECRET（鉴权密钥，开启 ENABLE_AUTH 时必填）
    • Variable/Secret ALLOWED_ORIGINS = https://your-frontend.com,https://another.com（CORS 白名单）

备注：令牌值只填 Token 本体，不要带 Bearer 前缀。请求头里同理。

2) Cloudflare 控制台 3 步上线

  1. 创建 Worker → Delete 示例代码 → 粘贴 src/index.js → Save & Deploy
  2. Settings → Variables/Secrets：按上面的变量一览添加
  3. 复制你的 URL（如 https://xxx.workers.dev），用于前端配置

3) 常见使用场景与如何配置

场景 A：多人共享 Worker，各自用自己的 Key（推荐“前端透传模式”）

  • Cloudflare Worker：
    • 可不配置 MINERU_API_TOKEN / DOC2X_API_TOKEN
    • 建议开启鉴权：ENABLE_AUTH=true，配置 AUTH_SECRET，并设置 ALLOWED_ORIGINS
  • Paper Burner X：
    • 打开“模型与Key管理” → MinerU / Doc2X：
      • Worker URL：填你的 Worker 地址
      • Worker Auth Key：填 AUTH_SECRET（若开启鉴权）
      • Token 模式：选择“前端透传模式”，在 PBX 内填入各自的服务 Token
    • OCR 引擎：在主界面 OCR 设置里选择 MinerU / Doc2X
    • 点击“测试连接”确认可达

场景 B：个人 Worker（或你提供统一 Key 给他人使用）

  • Cloudflare Worker：
    • 配置 MINERU_API_TOKEN / DOC2X_API_TOKEN
    • 开启鉴权：ENABLE_AUTH=true + AUTH_SECRET
    • 配置 ALLOWED_ORIGINS（只允许你的前端域）
  • Paper Burner X：
    • 打开“模型与Key管理” → MinerU / Doc2X：
      • Worker URL：填你的 Worker 地址
      • Worker Auth Key：填 AUTH_SECRET
      • Token 模式：选择“Worker 配置模式”（前端不再填 Token）
    • OCR 引擎：在主界面 OCR 设置里选择 MinerU / Doc2X
    • 点击“测试连接”确认可达

优先级说明（两服务一致）：如果同时提供了“请求头 Token（前端透传）”与“Worker 环境变量”，请求头优先。

一、功能概览

Worker 提供以下统一端点（均基于你的 workers.dev 子域或自定义域）：

  • MinerU
    • POST /mineru/upload 上传文件（表单）并发起处理
    • GET /mineru/result/{batch_id} 轮询处理结果（含 __health__ 测活）
    • GET /mineru/zip?url=... 代理下载 ZIP（解决浏览器跨域）
  • Doc2X
    • POST /doc2x/upload 预上传并上传文件
    • GET /doc2x/status/{uid} 轮询处理状态（含 __health__ 测活）
    • POST /doc2x/convert 触发导出（可选）
    • GET /doc2x/convert/result/{uid} 查询导出结果（可选）
    • GET /doc2x/zip?url=... 代理下载 ZIP（解决浏览器跨域）
  • 通用
    • GET /health 健康检查（不校验 Token）

鉴权与 CORS：

  • 可选开启 ENABLE_AUTH=true，启用后所有业务端点需携带请求头 X-Auth-Key: <AUTH_SECRET>。
  • Token 传递方式：优先读取请求头（前端透传）→ 若不存在则读取 Worker 环境变量。
  • CORS：支持 ALLOWED_ORIGINS 白名单与标准预检（OPTIONS）。

二、部署步骤（控制台，无需 wrangler）

  1. 登录 Cloudflare Dashboard → Workers & Pages → Create Application → Create Worker
  2. 命名（如 pb-ocr-proxy）→ Deploy → Edit Code
  3. 删除示例代码，粘贴 src/index.js 全部内容 → Save and Deploy
  4. Settings → Variables and Secrets：
    • 必填（至少二选一，根据使用场景）：
      • Secret MINERU_API_TOKEN（MinerU 令牌）
      • Secret DOC2X_API_TOKEN（Doc2X 令牌）
    • 可选（推荐生产）：
      • Variable ENABLE_AUTH = true|false
      • Secret AUTH_SECRET（开启 ENABLE_AUTH 时必填）
      • Variable/Secret ALLOWED_ORIGINS = https://your-frontend.com,https://another.com
    • 注意：令牌值只填 Token 本体，不要带 Bearer 前缀。
  5. 复制你的 Worker URL（如 https://pb-ocr-proxy.yourname.workers.dev）用于前端配置。

兼容日期（Compatibility Date）建议设置为 >= 2024-10-01。

三、环境变量说明

  • MinerU/Doc2X Token
    • MINERU_API_TOKEN（Secret）：MinerU 令牌
    • DOC2X_API_TOKEN（Secret）：Doc2X 令牌
  • 鉴权与 CORS（可选）
    • ENABLE_AUTH（Variable，默认不启用）：true 时开启鉴权
    • AUTH_SECRET（Secret）：开启鉴权后，所有业务端点需携带 X-Auth-Key: <AUTH_SECRET>
    • ALLOWED_ORIGINS（Variable/Secret）：逗号分隔的白名单 Origin；启用后仅白名单域可通过预检

Token 查找顺序（两服务一致）：

  1. 请求头：X-MinerU-Key 或 X-Doc2X-Key
  2. 环境变量：MINERU_API_TOKEN 或 DOC2X_API_TOKEN

四、端点与示例

通用健康：

curl https://your-worker.workers.dev/health

MinerU 测活（含 Token 校验）：

# 成功（200）：带 Token 或 Worker 已配置 Token
curl -i https://your-worker.workers.dev/mineru/result/__health__ \
  -H "X-Auth-Key: <AUTH_SECRET>" \
  -H "X-MinerU-Key: <MINERU_API_TOKEN>"

# 未授权（401）：未提供 Token 且 Worker 未配置 Token
curl -i https://your-worker.workers.dev/mineru/result/__health__

Doc2X 测活：

curl -i https://your-worker.workers.dev/doc2x/status/__health__ \
  -H "X-Auth-Key: <AUTH_SECRET>" \
  -H "X-Doc2X-Key: <DOC2X_API_TOKEN>"

MinerU 工作流：

# 1) 上传
curl -X POST https://your-worker.workers.dev/mineru/upload \
  -H "X-Auth-Key: <AUTH_SECRET>" \
  -H "X-MinerU-Key: <MINERU_API_TOKEN>" \
  -F file=@/path/to/file.pdf \
  -F is_ocr=true -F enable_formula=true -F enable_table=true -F language=ch

# 响应 { success:true, batch_id:"..." }

# 2) 轮询结果
curl https://your-worker.workers.dev/mineru/result/<batch_id> \
  -H "X-Auth-Key: <AUTH_SECRET>"

# 3) ZIP 代理下载（解决浏览器跨域）
curl -L "https://your-worker.workers.dev/mineru/zip?url=<full_zip_url>" \
  -o result.zip

Doc2X 工作流：

# 1) 上传
curl -X POST https://your-worker.workers.dev/doc2x/upload \
  -H "X-Auth-Key: <AUTH_SECRET>" \
  -H "X-Doc2X-Key: <DOC2X_API_TOKEN>" \
  -F file=@/path/to/file.pdf

# 响应 { success:true, uid:"..." }

# 2) 轮询状态
curl https://your-worker.workers.dev/doc2x/status/<uid> \
  -H "X-Auth-Key: <AUTH_SECRET>"

# 3) （可选）触发导出并查询导出结果
curl -X POST https://your-worker.workers.dev/doc2x/convert \
  -H "X-Auth-Key: <AUTH_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"uid":"<uid>","to":"md","formula_mode":"dollar"}'

curl https://your-worker.workers.dev/doc2x/convert/result/<uid> \
  -H "X-Auth-Key: <AUTH_SECRET>"

# 4) ZIP 代理下载（解决浏览器跨域）
curl -L "https://your-worker.workers.dev/doc2x/zip?url=<zip_url>" -o result.zip

CORS 与预检（OPTIONS）：

  • Worker 自动处理预检请求，允许的请求头：Content-Type, X-Auth-Key, X-MinerU-Key, X-Doc2X-Key
  • 设置 ALLOWED_ORIGINS 后，只有白名单域可通过预检并访问

五、前端集成要点

  • 在前端 UI 中配置 Worker URL（如 https://your-worker.workers.dev）即可，无需 Vercel 侧代理/重写
  • 鉴权启用时，在请求中带 X-Auth-Key: <AUTH_SECRET>
  • Token 传递有两种模式：
    • 前端透传：请求头 X-MinerU-Key / X-Doc2X-Key
    • Worker 持有：在 Cloudflare 环境变量中配置 MINERU_API_TOKEN / DOC2X_API_TOKEN
  • 对于从第三方返回的 ZIP 下载链接，前端应通过 /mineru/zip?url=... 或 /doc2x/zip?url=... 代理，避免浏览器直连跨域

六、wrangler CLI 部署（推荐用于生产）

如需使用 wrangler CLI 进行本地开发和自动化部署，项目已包含 wrangler.toml 配置文件。

1) 安装 wrangler

npm install -g wrangler
# 或使用 pnpm/yarn
pnpm add -g wrangler

2) 登录 Cloudflare

wrangler login

3) 配置环境变量

Secrets（敏感信息）：

# 至少配置一个 OCR Token
wrangler secret put MINERU_API_TOKEN
wrangler secret put DOC2X_API_TOKEN

# 可选：启用鉴权
wrangler secret put AUTH_SECRET

Variables（非敏感配置）：

编辑 wrangler.toml，取消注释需要的变量：

[vars]
ENABLE_AUTH = "true"
ALLOWED_ORIGINS = "https://yourdomain.com,https://another.com"

或使用命令行设置：

wrangler secret put ALLOWED_ORIGINS --env production

4) 本地开发

cd workers/pb-ocr-proxy
wrangler dev

访问 http://localhost:8787/health 测试。

5) 部署到生产

wrangler deploy

部署成功后会显示 Worker URL，如 https://pb-ocr-proxy.yourname.workers.dev。

6) 查看日志

wrangler tail

7) 管理 Secrets

# 列出所有 secrets（不显示值）
wrangler secret list

# 删除 secret
wrangler secret delete MINERU_API_TOKEN

七、与 Vercel 的关系

  • 本仓库前端在 Vercel 部署；Workers 在 Cloudflare 部署，二者独立
  • 已在仓库根添加 .vercelignore 排除 workers/ 目录，避免 Workers 代码被当作静态文件发布
  • 无需在 vercel.json 中为 Workers 写任何配置

八、故障排查

  • 401 未授权：
    • 未携带 X-Auth-Key（在开启鉴权时）或 X-Auth-Key 与 AUTH_SECRET 不一致
    • 未携带服务 Token（请求头或环境变量），X-MinerU-Key / X-Doc2X-Key 均为空
  • 403 预检失败：
    • 设置了 ALLOWED_ORIGINS，但请求来源不在白名单
  • ZIP 跨域：
    • 直接访问第三方下载地址跨域失败；使用 /mineru/zip?url=... 或 /doc2x/zip?url=... 代理
  • 健康与测活：
    • /health 仅测试可达性
    • /mineru/result/__health__ 与 /doc2x/status/__health__ 用于测试 Token/鉴权链路

如需更多示例，请参考 workers/pb-ocr-proxy/examples/test.html。