310 lines
10 KiB
Markdown
310 lines
10 KiB
Markdown
# 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`
|
||
|
||
---
|
||
|
||
## 四、端点与示例
|
||
|
||
通用健康：
|
||
```bash
|
||
curl https://your-worker.workers.dev/health
|
||
```
|
||
|
||
MinerU 测活（含 Token 校验）：
|
||
```bash
|
||
# 成功（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 测活：
|
||
```bash
|
||
curl -i https://your-worker.workers.dev/doc2x/status/__health__ \
|
||
-H "X-Auth-Key: <AUTH_SECRET>" \
|
||
-H "X-Doc2X-Key: <DOC2X_API_TOKEN>"
|
||
```
|
||
|
||
MinerU 工作流：
|
||
```bash
|
||
# 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 工作流：
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
npm install -g wrangler
|
||
# 或使用 pnpm/yarn
|
||
pnpm add -g wrangler
|
||
```
|
||
|
||
### 2) 登录 Cloudflare
|
||
|
||
```bash
|
||
wrangler login
|
||
```
|
||
|
||
### 3) 配置环境变量
|
||
|
||
**Secrets（敏感信息）：**
|
||
```bash
|
||
# 至少配置一个 OCR Token
|
||
wrangler secret put MINERU_API_TOKEN
|
||
wrangler secret put DOC2X_API_TOKEN
|
||
|
||
# 可选：启用鉴权
|
||
wrangler secret put AUTH_SECRET
|
||
```
|
||
|
||
**Variables（非敏感配置）：**
|
||
|
||
编辑 `wrangler.toml`，取消注释需要的变量：
|
||
```toml
|
||
[vars]
|
||
ENABLE_AUTH = "true"
|
||
ALLOWED_ORIGINS = "https://yourdomain.com,https://another.com"
|
||
```
|
||
|
||
或使用命令行设置：
|
||
```bash
|
||
wrangler secret put ALLOWED_ORIGINS --env production
|
||
```
|
||
|
||
### 4) 本地开发
|
||
|
||
```bash
|
||
cd workers/pb-ocr-proxy
|
||
wrangler dev
|
||
```
|
||
|
||
访问 `http://localhost:8787/health` 测试。
|
||
|
||
### 5) 部署到生产
|
||
|
||
```bash
|
||
wrangler deploy
|
||
```
|
||
|
||
部署成功后会显示 Worker URL，如 `https://pb-ocr-proxy.yourname.workers.dev`。
|
||
|
||
### 6) 查看日志
|
||
|
||
```bash
|
||
wrangler tail
|
||
```
|
||
|
||
### 7) 管理 Secrets
|
||
|
||
```bash
|
||
# 列出所有 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`。
|