在 Cloudflare Pages 上部署 BentoPDF:构建配置、安全头与 CORS 代理完整指南
在 Cloudflare Pages 上部署 BentoPDF:构建配置、安全头与 CORS 代理完整指南
BentoPDF 是一个完全客户端运行的开源 PDF 工具包,所有文件处理都在浏览器本地完成,不上传任何数据。本指南将说明如何把 BentoPDF 部署到 Cloudflare Pages:从项目接入、构建参数、环境变量,到 LibreOffice WASM 所必需的跨源隔离安全头(COOP/COEP)、SPA 重定向规则,以及为数字签名工具配套的 Cloudflare Workers CORS 代理的完整部署与安全配置。读完本文,你将能够独立在 Cloudflare 免费套餐上跑起一个功能完整、带自定义域名、支持数字签名链拉取的 BentoPDF 实例。
为什么选择 Cloudflare Pages 托管 BentoPDF
BentoPDF 采用"隐私优先"的架构:PDF 的合并、拆分、编辑、转换、签名全部在浏览器内通过 WASM 完成,README.md 明确说明"no server-side processing is required"。因此它本质上是一组静态文件,非常适合 Cloudflare Pages 这类静态托管平台。原文档总结的优势包括:
- 免费无限带宽,无需为流量付费;
- 全球 CDN,覆盖 300+ 边缘节点,静态资源就近分发;
- 自动 HTTPS,默认提供 TLS 证书;
- Pull Request 预览部署,每个 PR 自动生成独立预览环境,便于测试;
- 构建速度快,Pages 构建流水线开箱即用。
由于不需要任何服务器端逻辑,只要正确配置构建命令、环境变量和响应头,Cloudflare Pages 就能完整承载 BentoPDF 的全部功能。
快速部署:三步接入
- 登录 Cloudflare Dashboard 并进入 Pages 面板;
- 点击 Create a project(创建项目),选择 Connect to Git;
- 授权并选择存放 BentoPDF 源码的 GitHub 仓库,保存后首次构建会自动触发。
首次构建完成后,Cloudflare 会分配一个 https://<project>.pages.dev 域名,站点即刻可用。
构建配置:关键参数一览
在 Pages 项目的 Settings → Builds & deployments → Build configurations 中,按下表填写:
| 设置项 | 值 |
|---|---|
| Framework preset | None |
| Build command | npm run build |
| Build output directory | dist |
| Root directory | / |
几点说明:
- Framework preset 选择
None:BentoPDF 使用 Vite 构建(见 package.json 中的"build": "node scripts/generate-blog.mjs && ... && vite build && ..."),但不需要 Pages 内置的框架预设,直接执行原始构建命令即可。 - 构建产物目录必须是
dist:Vite 默认输出到dist/,Pages 需要从该目录发布静态文件。 - Root directory 保持
/:仓库根目录即项目根目录;若你的 BentoPDF 位于 monorepo 子目录,才需要调整此项。
提示:构建链中会依次执行博客生成、静态工具链接生成、TypeScript 类型检查(
tsc)、Vite 打包、i18n 多语言页面生成、sitemap 与安全头生成等步骤,请确保在本地先跑通npm run build再接入 Pages,便于区分环境问题与代码问题。
环境变量:品牌、语言与构建开关
在 Settings → Environment variables 中添加如下变量(均在构建时被 Vite 注入):
| 变量 | 值 | 说明 |
|---|---|---|
NODE_VERSION |
18 |
指定 Pages 构建环境的 Node.js 版本(v18 或更高) |
SIMPLE_MODE |
false(可选) |
是否使用去营销化的 Self-Hosted 精简版页面 |
VITE_BRAND_NAME |
自定义品牌名(可选) | 页面头部与底部显示的品牌名称 |
VITE_BRAND_LOGO |
相对 public/ 的 Logo 路径(可选) |
例如 images/my-logo.svg |
VITE_FOOTER_TEXT |
自定义页脚版权文案(可选) | 例如 © 2026 Acme Corp. |
VITE_DEFAULT_LANGUAGE |
默认界面语言,如 fr(可选) |
仅影响初始默认语言,用户仍可切换 |
这些变量与 README.md 中的"Custom Branding"一节完全对应:品牌类变量(VITE_BRAND_NAME、VITE_BRAND_LOGO、VITE_FOOTER_TEXT)在构建时通过 Handlebars 注入页面模板(见 vite.config.ts 中 handlebars({ context: { brandName: ... } }) 的配置)。VITE_DEFAULT_LANGUAGE 支持的语言包括 en、ar、be、fr、de、es、zh、zh-TW、vi、tr、id、it、pt、nl、da 等,对应 public/locales 下的语言目录。
配置文件:_headers 与 _redirects
Cloudflare Pages 通过仓库内的 _headers 和 _redirects 文件控制 HTTP 响应头与路由规则。请在 public/ 目录下创建 _headers:
# Required security headers for SharedArrayBuffer (used by LibreOffice WASM)
/*
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: cross-origin
# Pre-compressed LibreOffice WASM binary
/libreoffice-wasm/soffice.wasm.gz
Content-Type: application/wasm
Content-Encoding: gzip
Cache-Control: public, max-age=31536000, immutable
# Pre-compressed LibreOffice WASM data
/libreoffice-wasm/soffice.data.gz
Content-Type: application/octet-stream
Content-Encoding: gzip
Cache-Control: public, max-age=31536000, immutable
# Cache WASM files aggressively
/*.wasm
Cache-Control: public, max-age=31536000, immutable
Content-Type: application/wasm
# Service worker
/sw.js
Cache-Control: no-cache
为什么 COOP/COEP 头是必须的
::: warning 重要
Cross-Origin-Embedder-Policy 与 Cross-Origin-Opener-Policy 这两个头是 Word/ODT/Excel/PowerPoint 转 PDF 功能正常工作的前提。缺少它们时,浏览器将不再提供 SharedArrayBuffer,LibreOffice WASM 引擎会初始化失败。
:::
底层原因在 README.md 中有明确说明:Office 文件转换使用 LibreOffice WASM,它依赖 SharedArrayBuffer,因此应用必须处于 cross-origin isolated 状态且运行在安全上下文(HTTPS)中。COOP: same-origin 保证窗口与同源文档隔离,COEP: require-corp 要求所有跨域子资源显式声明 CORP 头,两者共同打开 SharedArrayBuffer。开发环境下这一行为由 vite.config.ts 中的 server.headers / preview.headers 配置复现(同样设置 Cross-Origin-Opener-Policy: same-origin 与 Cross-Origin-Embedder-Policy: require-corp),生产环境则由 _headers 承担。
与此同时,Cross-Origin-Resource-Policy: cross-origin 允许 CDN 或其他来源正确加载资源;对 libreoffice-wasm 目录下预压缩的 .gz 文件显式声明 Content-Type: application/wasm 和 Content-Encoding: gzip,可以避免浏览器把它们当作普通 gzip 文档下载。WASM 文件使用 max-age=31536000, immutable 长期缓存,而 sw.js 使用 no-cache,保证 Service Worker 能及时更新。
SPA 路由回退
在 public/ 下创建 _redirects:
/* /index.html 200
该规则把所有未命中的路径重写到 /index.html 并返回 200(软 200 重写),确保多语言路由与工具页面在直接刷新或深链接时不会 404。
说明:
_headers与_redirects位于public/目录时,会被 Vite 原样复制到dist/构建产物中,从而被 Pages 识别。
自定义域名
- 进入 Pages 项目的 Custom domains;
- 点击 Add custom domain 并输入你的域名;
- 若域名托管在 Cloudflare,系统会自动配置 DNS 记录,几秒内完成生效。
之后访问你的域名即可使用 HTTPS,Pages 会自动续期证书。
故障排查
大文件上传限制
Cloudflare Pages 对单文件上传上限为 25 MB。BentoPDF 的 WASM 模块通常不触及该限制,但如果你的部署包含超大静态资源,可以在构建阶段拆分大文件(例如使用 npm run build 后对产物按需拆分)。若超过限制,需要改用支持更大文件的托管方式。
Worker 大小限制
如果使用 Cloudflare Workers 做高级路由(而非仅用 Pages 的 _redirects),注意免费套餐对 Worker 脚本体积有 1 MB 上限。仓库附带的 cors-proxy-worker.js 体积远小于该限制,可直接部署。
数字签名报 "Failed to fetch"
常见原因与对策:
- 未配置 CORS 代理:设置
VITE_CORS_PROXY_URL并重新构建; - 混合内容被浏览器拦截:站点是 HTTPS,而证书颁发机构(CA)的签发者 URL 是 HTTP,需经代理转为 HTTPS;
- 代理拒绝了你的 Origin:检查
cors-proxy-worker.js中ALLOWED_ORIGINS是否包含你的域名。
更详细的排查方法见 docs/self-hosting/cors-proxy.md。
CORS 代理 Worker(数字签名必需)
为什么需要代理
数字签名工具使用 zgapdfsigner 库(见 package.json 依赖列表)构建完整证书链:它从证书的 AIA(Authority Information Access)扩展中提取签发者证书 URL 并抓取。问题在于,许多 CA 服务器(如 www.cert.fnmt.es)既不返回 CORS 头,还常以纯 HTTP 提供服务——HTTPS 站点下的浏览器会因混合内容策略直接拦截。CORS 代理通过一个 HTTPS 端点转发请求并附加正确的 Access-Control-Allow-Origin 头,一举解决两个问题。
前端侧的实现位于 src/js/logic/digital-sign-pdf.ts:源码中通过 import.meta.env.VITE_CORS_PROXY_URL 读取代理地址,并在 createCorsAwareFetch 中包装 window.fetch,将匹配 .crt、.cer、.pem 等特征的证书请求路由到代理;未配置代理时,需要外部链拉取的证书(如 FNMT 或部分企业 CA)会直接失败。
部署代理 Worker
仓库的 cloudflare 目录下已包含现成的 Worker 源码与配置,部署步骤如下:
cd cloudflare
npx wrangler login
npx wrangler deploy
部署前有两处必须按你的实际情况调整:
1. 更新允许的 Origin——打开 cors-proxy-worker.js,把 ALLOWED_ORIGINS 改为你自己的域名:
const ALLOWED_ORIGINS = [
'https://your-domain.com',
'https://www.your-domain.com',
];
::: warning 重要
不做这一步,代理会以 403 拒绝来自你站点的所有请求——默认白名单只放行 bentopdf.com。
:::
2. 确认 Worker 配置——wrangler.toml 已预置 RATE_LIMIT_KV 的 KV 命名空间绑定与 PROXY_SECRET 说明注释,按需取消注释或替换 ID 即可。
代理的安全特性
cors-proxy-worker.js 内置了多层防护,原文档将其归纳如下:
| 特性 | 说明 |
|---|---|
| URL 限制 | 只允许证书相关 URL:*.crt、*.cer、*.pem、/certs/、/ocsp、/crl 等路径模式(对应源码 ALLOWED_PATH_PATTERNS) |
| 文件大小限制 | 每个请求最大 10 MB,流式读取、超限即中断(源码 MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024) |
| 速率限制 | 每 IP 每分钟 60 次请求(RATE_LIMIT_MAX_REQUESTS = 60、窗口 60 秒),需要 KV 存储 |
| 私网 IP 阻断 | 阻止 localhost、10.x、172.16-31.x、192.168.x、链路本地地址、CGNAT、IPv6 私网段及云元数据地址(isPrivateOrReservedHost) |
从源码看还有两项补充防护值得一提:
- TSA 主机白名单:对于 RFC 3161 时间戳请求(POST +
application/timestamp-query),仅允许timestamp.digicert.com、timestamp.sectigo.com、ts.ssl.com、freetsa.org、tsa.mesign.com这几个已知时间戳服务器(ALLOWED_TSA_HOSTS)。 - 响应类型白名单:上游响应 Content-Type 只允许安全证书 MIME 类型(
SAFE_CONTENT_TYPES),其余一律降级为application/octet-stream,防止上游注入恶意类型;同时设置X-Content-Type-Options: nosniff与Cache-Control: no-store。
启用速率限制(推荐)
速率限制依赖 Cloudflare KV:
# 创建 KV 命名空间
npx wrangler kv namespace create "RATE_LIMIT_KV"
# 将返回的 ID 写入 wrangler.toml:
# [[kv_namespaces]]
# binding = "RATE_LIMIT_KV"
# id = "YOUR_ID"
npx wrangler deploy
注意免费套餐的 KV 配额:每天约 10 万次读取、1 千次写入,大约对应每天 300–500 次签名操作。需要说明的是,wrangler.toml 中已预置了 KV 绑定示例(RATE_LIMIT_KV),若使用仓库自带的配置直接部署,速率限制默认即为开启状态。
在构建时接入代理地址
代理部署完成后会得到形如 https://your-worker.workers.dev 的地址,需在构建 BentoPDF 时通过环境变量注入:
VITE_CORS_PROXY_URL=https://your-worker.workers.dev npm run build
使用 Docker 构建时,由于该变量属于构建期敏感信息,采用 BuildKit secret 方式传入:
export VITE_CORS_PROXY_URL="https://your-worker.workers.dev"
DOCKER_BUILDKIT=1 docker build \
--secret id=VITE_CORS_PROXY_URL,env=VITE_CORS_PROXY_URL \
-t your-bentopdf .
在 Cloudflare Pages 上则把它加入环境变量列表,重新部署即可。
可选:HMAC 签名校验
为抵御随意滥用,Worker 支持可选的客户端 HMAC 签名(HMAC-SHA256)。前端在 src/js/logic/digital-sign-pdf.ts 中用 VITE_CORS_PROXY_SECRET 对 url + timestamp 计算签名,随请求附带 t(时间戳)与 sig(签名)参数;Worker 端在配置了 PROXY_SECRET 时校验签名,并要求时间戳在 5 分钟窗口内。
# 生成随机密钥
openssl rand -hex 32
# 配置到 Cloudflare Worker
npx wrangler secret put PROXY_SECRET
# 构建时注入同一密钥
VITE_CORS_PROXY_SECRET=your-secret npm run build
::: warning 安全边界
客户端密钥可从打包后的 JavaScript 中提取,因此 HMAC 只是"防止随意滥用"的威慑手段,并非真正的认证边界。Worker 源码中的注释也明确说明:真正防 SSRF 的关键是私网/保留 IP 解析检查(hostnameResolvesToPrivate);对于高敏生产环境,更稳妥的做法是自建后端服务转发证书请求,密钥只保存在服务端。
:::
自托管在 Cloudflare 之外的注意事项(DNS rebinding)
Worker 会拒绝任何解析到私网/内网 IP 的 URL。由于证书链指向的 CA(FNMT、企业 CA 等)事先未知,无法使用固定主机白名单,这留下一个很小的 DNS rebinding 窗口:攻击者可以在安全检查和真实请求之间切换 DNS 解析结果。在 Cloudflare 上这不可利用——Workers 无法访问私网 IP 或 169.254.169.254 元数据端点。但如果你把代理跑在 Cloudflare 之外的 VPC 内(workerd、Node 等),运行时可以触达内网 IP,必须在代理前加 egress 防火墙,阻断 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.0/8、169.254.0.0/16 及对应 IPv6 网段。完整论述见 docs/self-hosting/cors-proxy.md。
不需要代理的情况
并非所有证书都需要代理。若证书在 P12/PFX 文件中已包含完整证书链,或使用自签名证书、已手动拼好完整链的证书,则无需外部链拉取,可以不配置 VITE_CORS_PROXY_URL(设为空字符串即禁用)。
完整部署检查清单
- ✅ Pages 项目接入 GitHub 仓库,构建命令
npm run build、输出目录dist; - ✅
public/_headers已提交(含 COOP/COEP 头与 WASM 缓存规则); - ✅
public/_redirects已提交(/* /index.html 200); - ✅
NODE_VERSION=18及品牌/语言环境变量已配置; - ✅ 若启用数字签名:
ALLOWED_ORIGINS已改、Worker 已部署、VITE_CORS_PROXY_URL已注入; - ✅ (可选)启用 KV 速率限制与
PROXY_SECRETHMAC; - ✅ 添加自定义域名并验证 HTTPS 生效。
完成以上步骤后,你的 BentoPDF 实例即可在 Cloudflare 全球边缘网络上稳定运行:所有 PDF 处理仍在访客浏览器本地完成,Office 转换依赖的 LibreOffice WASM 也能在正确的安全头下正常初始化,数字签名工具则可借助 CORS 代理拉取任意 CA 的签发者证书链。