在 Cloudflare Pages 上部署 BentoPDF:构建配置、安全头与 CORS 代理完整指南

原创2026-09-21 17:37:171,705 阅读
文章标签:前端

在 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 的全部功能。

快速部署:三步接入

  1. 登录 Cloudflare Dashboard 并进入 Pages 面板;
  2. 点击 Create a project(创建项目),选择 Connect to Git;
  3. 授权并选择存放 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 识别。

自定义域名

  1. 进入 Pages 项目的 Custom domains;
  2. 点击 Add custom domain 并输入你的域名;
  3. 若域名托管在 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"

常见原因与对策:

  1. 未配置 CORS 代理:设置 VITE_CORS_PROXY_URL 并重新构建;
  2. 混合内容被浏览器拦截:站点是 HTTPS,而证书颁发机构(CA)的签发者 URL 是 HTTP,需经代理转为 HTTPS;
  3. 代理拒绝了你的 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(设为空字符串即禁用)。

完整部署检查清单

  1. ✅ Pages 项目接入 GitHub 仓库,构建命令 npm run build、输出目录 dist;
  2. ✅ public/_headers 已提交(含 COOP/COEP 头与 WASM 缓存规则);
  3. ✅ public/_redirects 已提交(/* /index.html 200);
  4. ✅ NODE_VERSION=18 及品牌/语言环境变量已配置;
  5. ✅ 若启用数字签名:ALLOWED_ORIGINS 已改、Worker 已部署、VITE_CORS_PROXY_URL 已注入;
  6. ✅ (可选)启用 KV 速率限制与 PROXY_SECRET HMAC;
  7. ✅ 添加自定义域名并验证 HTTPS 生效。

完成以上步骤后,你的 BentoPDF 实例即可在 Cloudflare 全球边缘网络上稳定运行:所有 PDF 处理仍在访客浏览器本地完成,Office 转换依赖的 LibreOffice WASM 也能在正确的安全头下正常初始化,数字签名工具则可借助 CORS 代理拉取任意 CA 的签发者证书链。

登录后查看全文
bentopdf