↓ 跳过正文
张帆 | 人工智能与我

🚀 打造零成本、24/7 不关机的企业级 Serverless 电子签名平台 (E-Sign Desk)

·578 字·3 分钟
Cloudflare Workers Serverless PDF Signature PKCS#7 Architecture Hono.js
作者
Frank Zhang
Exploring AI, Network, Insurance, and Life.

摘要：本文将完整分享如何基于 Cloudflare Workers、Cloudflare KV、pdf-lib、@signpdf 以及 Actalis 权威商业级 PKCS#12 数字证书，从零搭建一套媲美 DocuSign / Adobe Sign 的 100% 云端全托管电子签名平台。系统具备 24/7 全天候秒级响应、2048 位 RSA 密码学防篡改签名、自动生成 Certificate of Completion 审计报告、密码访问锁及极速邮件投递能力。

📌 一、 项目背景与痛点
#

在现代商务及高合规行业（如北美保险、金融、税务、法律）中，合同与保单的电子签署是核心环节。然而，使用市面上的主流电子签名服务（如 DocuSign、Adobe Sign、OneSpan）面临以下痛点：

  1. 高昂的按封收费：商业电子签平台通常按封（Envelope）或按年收取高额订阅费（每年数千美元）。
  2. 数据隐私与自主权：敏感的客户信息、合同文本与签名图像存储在第三方服务器上，无法实现数据本地化或自治控制。
  3. 依赖本地服务器的不稳定性：若自建 Node.js / Express 本地服务，需要搭建内网穿透（如 Ngrok）并保持 Mac / Linux 电脑 24 小时开机，一旦断网、断电或系统休眠，服务即告中断。

为此，我们设计并打造了这套 100% 云端全托管 Serverless 电子签名平台。

🏗️ 二、 整体架构设计与技术选型
#

系统采用了 Edge Computing (边缘计算) 架构，前端采用轻量级响应式 UI，后端完全运行在 Cloudflare 全球 300+ 边缘节点上。

graph TD
    User[用户 / 签署人] -->|HTTPS 访问| Domain[docusign.your-domain.com]
    Domain -->|Cloudflare Routing| Worker[Cloudflare Worker / Hono Framework]
    
    subgraph Cloudflare Serverless Edge Environment
        Worker -->|读写数据| KV[(Cloudflare KV - ESIGN_KV)]
        Worker -->|读取证书| KVCert[ACTALIS_P12 2048-bit RSA]
        Worker -->|读取硬件加密密钥| KMS[KMS Secrets - P12_PASSWORD / RESEND_API_KEY]
    end
    
    Worker -->|PDF 合成 & PKCS#7 签名| PDFEngine[@signpdf + pdf-lib]
    Worker -->|事务级邮件投递| Resend[Resend API / Domain Authentic]
    Resend -->|投递| Recipient[收件人 Gmail / Outlook 邮箱]

🛠️ 技术栈清单
#

  • 边缘运行环境：Cloudflare Workers (基于 Google V8 Engine)
  • Web 框架：Hono.js (轻量级高吞吐 Edge Web 框架)
  • 数据库 / 持久化存储：Cloudflare KV Namespace (ESIGN_KV)
  • PDF 渲染与处理引擎：PDF.js (前端动态渲染) + pdf-lib (后端 PDF 合成与页面注入)
  • 密码学与数字签名：@signpdf/signpdf + @signpdf/signer-p12 + node-forge
  • CA 数字证书：Actalis Commercial PKCS#12 (S/MIME Public CA 2048-bit RSA + SHA-256)
  • 邮件发送引擎：Resend REST API (域名验证 noreply@your-domain.com)
  • 前端 UI：HTML5 + Tailwind CSS + HTML5 Canvas 手写签名板

🌟 三、 核心功能与亮点
#

1. ✍️ 媲美 DocuSign 的智能引导签署 (Guided Signing Desk)
#

  • 预设印章框高亮引导：签署人打开链接后，点击 🚀 START 按钮，页面会自动平滑滚动并高亮第 1 个印章框、第 2 个印章框（🖊️ Signature / 🔤 Initials / 📅 Date），降低用户操作门槛。
  • 自由落印模式 (Free Placement)：若发件人未预设位置，签署人可直接点击 PDF 任意位置或点击按钮自动落下一个签名框完成签署。
  • 多终端完美适配：支持 PC 鼠标绘制、手机/平板触摸屏手写、键盘打字花体转换及本地图片签名上传。

2. 🔐 三重云端安全防护与专属访问密码锁
#

  • Master Passcode 密码锁 (可自定义全站主口令)：在网页 DOM 加载的第 0 毫秒嵌入内联 IIFE 模糊锁定层，未解锁前禁止任何内容渲染，顶部 Header 支持一键 🔒 Lock 锁定测试。
  • 硬件级密钥加密 (Cloudflare KMS Secrets)：Actalis 证书解密密码（P12_PASSWORD）与 Resend API Key 通过 Cloudflare KMS 硬件级加密存储，代码及 GitHub 仓库中无任何明文凭证。

3. 📜 法律级防篡改与完整 Certificate of Completion 审计报告
#

  • 满足北美保险及金融机构（如 Canada Life、Sun Life、Manulife）Head Office 的严格审核标准：
    • 自动生成最后一页审计报告：详细记录每个签署人的 Name、Email、IP 地址（Cloudflare Connecting IP）、UTC 时间戳及完整链式事件日志。
    • PKCS#7 2048 位 RSA 密码学加签：对最终合并 PDF 注入数字证书哈希块，任何后期的文本修改、增删页面或另存为都会触发 Adobe Acrobat Reader 的篡改报警。

4. 🔗 顺序流转与见证人签署 (Sequential Chain & Witness Support)
#

  • 支持 Recipient Index（0 ➔ 1 ➔ 2）链式流转，上一位签署完成后，云端自动触发下一位的邮件通知与链接激活。

🛠️ 四、 核心攻坚与踩坑排雷实录 (Engineering Insights)
#

在从传统 Node.js (Express) 本地服务器迁移至 Cloudflare Worker 边缘架构的过程中，我们攻克了一系列踩坑难题：

坑点 1：Mailchannels / Resend 邮件域名防伪与 401 / 403 拦截
#

  • 现象：Worker 端调用发信接口返回 401 Authorization Required 或 403 validation_error。
  • 排查与解决：
    1. Mailchannels 启用了 Domain Lockdown，要求在域名 DNS 中添加 _mailchannels TXT 记录（v=mc1 cfid=your-account.workers.dev）以验证 Workers所有权。
    2. Resend 的默认测试发件人 onboarding@resend.dev 只允许发送至注册人邮箱，向外部 Gmail 发信会触发 403。将发件人无缝升级为绑定认证域名 E-Sign Platform <noreply@your-domain.com> 后，彻底实现 200 OK 秒级投递。

坑点 2：Cloudflare WAF 机器人盾拦截与 API 报错 Just a moment...
#

  • 现象：前端在点击 Resend 或请求 /api/envelopes 时返回 <!DOCTYPE html><html...Just a moment... 网页文本，导致 JSON 解析失败。
  • 解决：在 Cloudflare Dashboard 中配置 WAF Custom Skip Rule：
    • 设定规则 Hostname equals docusign.your-domain.com ➔ 动作选择 Skip（跳过 WAF Managed Rules、Bot Fight Mode 及 Security Level），完美解封 API 通道。

坑点 3：FormData 提交解析引发的 No number after minus sign in JSON 报错
#

  • 现象：签署人提交印章时提示 JSON 语法错误。
  • 排查：前端使用 FormData 格式提交数据，数据包开头为连字符 --------------------------12345...。后端误调用了 c.req.json()，V8 JSON 解析器将开头的 - 误认为格式错误的数字而抛错。
  • 解决：重构 /api/sign/:id 路由，按 Content-Type 标头动态识别 application/json 与 multipart/form-data（c.req.parseBody()），实现 100% 兼容。

坑点 4：前端与后端字段名不匹配导致预设签名框不显示
#

  • 现象：发件人在准备页面摆放了签名框，收件人打开却提示 No pre-assigned fields found。
  • 排查：前端发信页面保存的印章属性名是 recipientIndex，而 Worker 后端逻辑仅校验了 signerIndex，导致数组被过滤清空。
  • 解决：升级 Worker 端的 assignedFields 过滤逻辑，同时识别 recipientIndex 与 signerIndex，使预设框 100% 精确渲染。

🚀 五、 快速部署与使用指南
#

1. 配置 wrangler.toml
#

name = "esign-platform"
main = "worker.mjs"
compatibility_date = "2026-08-28"
assets = { directory = "./public", binding = "ASSETS" }

[[kv_namespaces]]
binding = "ESIGN_KV"
id = "你的Cloudflare_KV_Namespace_ID"

2. 上传证书与设置云端加密 Secret
#

# 1. 上传 Actalis P12 二进制证书至 KV
npx wrangler kv key put --binding=ESIGN_KV "ACTALIS_P12" --path=actalis.p12 --remote

# 2. 设置证书解密密码与 Resend API Key
echo "你的P12解密密码" | npx wrangler secret put P12_PASSWORD
echo "你的Resend_API_Key" | npx wrangler secret put RESEND_API_KEY

3. 一键部署上线
#

npx wrangler deploy

📊 六、 总结与展望
#

通过将架构 100% 迁移至 Cloudflare Workers，我们不仅实现了真正的 0 成本、24/7/365 全天候不间断运行，更在安全性、合规性与响应速度上达到了商业级产品的标准。

未来展望
#

  • 接入多吉字（DigiCert / GlobalSign）原生 AATL HSM 硬件签名接口，实现 Adobe 打开即显默认绿勾。
  • 增加文本框智能 OCR 识别与保单号自动套打功能。

欢迎在评论区探讨 Serverless 架构与 PDF PKCS#7 数字签名相关的技术细节！