先别按人头买电子签名:我在 Linux 上把一份练习 PDF 从上传签到出证

367次阅读
没有评论

共计 5878 个字符,预计需要花费 15 分钟才能阅读完成。

2026 年 11 月 16 日,凯文·罗斯(Kevin Rose)在 X 上公开了一个开源项目 SignuDoc。项目的 README 写着:15 人团队如果按 DocuSign Business Pro 的座位费来买,一年是 8,100 美元;Standard 是 5,400 美元。这两笔账,README 标明引的是 DocuSign 在 2026 年 11 月公布的美国区价目。我没有再去点开他们的结账页复核现价,正文里的数字以这份 README 为准。

SignuDoc 自己的许可证是 MIT,仓库在 NYLLON-SOFTWARE/SignuDoc。官方主推一键部署到你自己的 Vercel 账号;它也写了在电脑上试用的方式:文件落在磁盘,邮件写成本地 JSON,不必申请外部账号。

今天下午我只验收一件事。在 Linux 测试机上,不注册 Vercel,不往真实邮箱发信,能不能把一份写明「非真实合同」的练习 PDF 走完这条路径:

上传 PDF → 填写签署人 → 发出邀请 → 同意电子记录 → 签字 → 核对哈希和印章

先别按人头买电子签名:我在 Linux 上把一份练习 PDF 从上传签到出证

▲ 这次练习走过的六步。后面的命令和结果按这个顺序写。

走完了。练习文件在 2026 年 11 月 18 日 15:11:29(Asia/Shanghai)变成已完成状态,签字页上出现了「林练习」和 November 18, 2026。中间有一处必须讲清楚的报错:组织名用中文时,软件给自己签发的盖章证书会在出证那一步失败。换成本地生成的测试证书之后,才拿到完整文件。

这不是法律意见,也不是在说它可以替代你现在用的电子签名服务。下面按我实际做过的步骤写。

· · ·

PART 01

它能帮你做完哪一段

SignuDoc 做的是日常那种「把一份 PDF 发出去,让对方在链接里签字,然后留下一份可核对的完成件」。官方 README 把这条路径概括成三步:上传并放置字段、签署人打开邮件链接签字、各方拿到盖了章的 PDF 和审计证书。

v0.4.0 是 2026 年 11 月 17 日 18:16 UTC 打的标签,换算成 Asia/Shanghai 是 11 月 18 日 02:16。本文实测 v0.4.0(截至 2026 年 11 月 19 日最新正式版为 v0.5.0;该版本涉及数据库迁移。我没有用 v0.5.0 复测文中的中文组织名证书问题,不能写成新版已修好)。我在当天下午采集时,GitHub 上显示 1,918 个星标,这个数字之后会变。检出的提交是 6c0528e。运行起来以后,页面顶部的框架是 Next.js 16.4.6。

它明确写了自己比不了 DocuSign 的地方,比如还没有对外 API、一次请求只处理一份 PDF、签署顺序是依次签而不是同时签。本地试用默认做出的是简单电子签名;自签或测试证书只能证明「这份文件在盖章之后有没有被改过」,颁发者不会被操作系统预先信任。能不能当法庭证据,要看你所在的司法辖区,也要看你有没有换成正式的证书。我没有做这一步。

🍎 这份练习里用的组织名、人名和邮箱都是虚构的,PDF 首页也写了「不是真实合同,不具有法律效力」。不要拿真实合同、真实身份证号或同事的私人邮箱来试。

· · ·

PART 02

在自己电脑上把服务跑起来

官方 README 写的本地步骤是:准备 Node.js 24 和 Docker,然后:

npm install
cp .env.example .env
npm run db:start
npm run dev

npm run db:start 会用 Docker Compose 拉起 Postgres 17,端口写在 127.0.0.1:5432,再执行迁移。.env.example 里默认的数据库地址就是 postgres://signudoc:signudoc@127.0.0.1:5432/signudoc,APP_URL 是 http://localhost:3000,EMAIL_DRIVER=capture 表示邮件只写到项目目录的 .data/outbox,不会真的发出去。

我的测试机上有 Node.js 24.22.1,但当时没有可用来跑官方 compose 的 Docker 引擎。数据库改用本机已有的 PostgreSQL 16.15,只监听 127.0.0.1:55432。把 .env 里的端口改成 55432 之后,执行 node db/migrate.mjs,18 条迁移全部成功,其中包含 v0.4.0 新增的姓名字段迁移 20261118090000_name_field.sql。

开发服务我没有用默认的 npm run dev 直接监听所有网卡,而是:

npx next dev --hostname 127.0.0.1 --port 3000

日志里写着 Ready in 298ms,ss 看到监听地址确实是 127.0.0.1:3000。用 HTTP 访问 /,返回 307,跳到 /setup;/setup 返回 200,页面里能看到 Organization name、Support email、Your name、Your email、Password 这些标签。这和官方说的「第一次打开会进入初始化页,第一个账号成为管理员」一致。

初始化我是向 /api/setup 提交 JSON 完成的,没有用浏览器点按钮。组织名写成「练习工作台」,管理员邮箱用 practice-admin@example.com,支持邮箱用 practice-help@example.com。接口返回 201 之后,再访问 / 会跳到 /login,已登录会话访问 /dashboard 返回 200。密码只留在本机,不写进这篇文章。

🍎 如果这套程序以后要放到公网,README 建议设置 SETUP_TOKEN,避免第一个打开网址的人把管理员抢走。本地只绑 127.0.0.1 时,这个风险小很多,但初始化一旦做完就不能再走一遍,第二次请求 /api/setup 会返回 409。

· · ·

PART 03

用一份练习 PDF 走完签字

我做了一份两页的 A4 PDF,标题是「练习样本:设备领用确认单(非真实合同)」,文件大小 13,687 字节,创建时间是 15:09:58(Asia/Shanghai)。第一页有领用说明和签名栏,第二页只用来确认软件能处理多页文件。

先别按人头买电子签名:我在 Linux 上把一份练习 PDF 从上传签到出证

▲ 练习 PDF 第一页。这是我在测试机上生成后用 pdftoppm 渲染的页面,不是软件界面截图。

把它作为表单字段 file 发到 /api/envelopes,标题字段写成上面那句。接口返回 201,信封编号是 7eef0d11-2d1b-434b-a2e5-8ce9108067d9,页数 2,源文件大小仍是 13,687 字节。

接着用 PUT /api/envelopes/{id}/signers 写入一名签署人:姓名「林练习」,邮箱 practice-signer@example.com。再用 PUT /api/envelopes/{id}/fields 放了三个字段:签名、日期、姓名。坐标是我按页面大概估的,没有在网页上拖放。后面会看到,姓名栏的位置估偏了。

发送时必须带上 "permittedUseConfirmed": true,否则接口返回 400,提示先确认这是一份普通商务协议。我把截止日期设成 14 天。15:10:08(Asia/Shanghai)发送成功,返回里的签署人姓名是「林练习」。

邮件没有出网。.data/outbox 里出现第一封 JSON,模板是 signing_invitation,主题是:

张练习 requested your signature on "练习样本:设备领用确认单(非真实合同)"

发件显示名是「练习工作台」,回复地址是刚才填的支持邮箱。正文里有一条本地签字链接。打开这条链接对应的接口,能读到签名、日期、姓名三个字段。然后向同意接口提交 disclosureVersion 为 2026-11-13(这是当前代码里写死的电子记录说明版本),15:10:11 记录到同意。

签字提交本身只要把签名字段写成「林练习」、输入方式选 typed。日期和姓名由程序自己填,不必在提交体里再写一遍。

先别按人头买电子签名:我在 Linux 上把一份练习 PDF 从上传签到出证

▲ 完成后的签字页。签名和日期落在预留的位置附近;姓名栏因为坐标估偏,压到了「领用人确认」那一行。网页上拖放字段会比这样估坐标更准。页面由已签名 PDF 渲染,时间是 15:11:29(Asia/Shanghai)。

· · ·

PART 04

组织名用中文时,出证这一步会报错

第一次提交签字,接口在 15:10:13 返回 500,正文是 Unable to finish signing. 服务日志里的原因更具体:

Error: Too few bytes to read ASN.1 value.

堆栈指向盖章模块 pdf-seal.ts,发生在程序读取自己签发的证书时。信封状态当时仍是 sent,签署人仍是 notified,说明这次失败被回滚了,文件还没有写成「已完成」。

我在同一份代码里单独复现了证书生成。组织名用「练习工作台」、证书通用名用「练习工作台 document seal」时,node-forge 解析证书会报同样的错误。改成英文组织名 Practice Bench,或没有组织名、只用 SignuDoc document seal,就能正常解析。也就是说,问题出在软件给自己签发证书时,还经不住中文组织名,不是练习 PDF 本身坏了。

先别按人头买电子签名:我在 Linux 上把一份练习 PDF 从上传签到出证

▲ 左侧是默认自签发证书在中文组织名下失败,右侧是换成测试证书后才完成盖章。这只说明流程能走完,不是在说它已有法律效力。

官方环境变量允许改用自己的 PKCS#12 证书:SEAL_P12_BASE64 和 SEAL_P12_PASSWORD。我用 OpenSSL 生成了一张仅供这次测试的证书,通用名是 Practice Desk document seal,写进环境变量后重启服务,再次提交刚才那条签字。15:11:29(Asia/Shanghai)返回 200,信封状态变成 completed,签署人状态变成 signed。

.data/outbox 随后又多了两封完成通知,主题都是:

"练习样本:设备领用确认单(非真实合同)" is fully signed

一封给管理员,一封给签署人。三封邮件始终只写在本地目录里。

🍎 这不是在鼓励你把正式业务建立在自签证书上。它只说明:组织名是中文时,默认自签发的盖章证书会在出证时失败;换成自己准备的证书后,这条练习流程可以走完。正式环境要用哪个证书颁发机构,需要你自己评估。我没有申请公开可信的证书。

· · ·

PART 05

怎么核对自己手里的那份文件

完成后的签字 PDF 是 274,500 字节,PDF 1.7,带 AcroForm,修改时间是 15:11:29(Asia/Shanghai)。文本层里能读到「林练习」和 November 18, 2026。SHA-256 是:

d3d03b09dbefcc39ff4e77146f318472ec0b4cc2c0587c09586c68a30771552d

把这个哈希用 JSON 交给本机的 /api/verify,返回 match 为 true,status 为 completed,fileKind 为 signed-document,信封编号和标题都对得上。注意这个接口要的是 SHA-256 字符串;我先按上传文件的方式试了一次,得到的是 400 和提示 Send the file's SHA-256 value. README 也写了,校验时文件不必离开你的设备,站点只核指纹。

用 pdfsig 看同一份文件,结果是:

  • 签名类型:ETSI.CAdES.detached
  • 哈希算法:SHA-256
  • 签名时间:Nov 18 2026 15:11:29
  • 证书通用名:Practice Desk document seal
  • Signature Validation: Signature is Valid.
  • Certificate Validation: Certificate issuer isn't Trusted.

这一行是预期现象。这张证书是我自己签发的测试证书,操作系统不会预先信任它。「签名有效」说的是文件在盖章之后没有被改过,「颁发者不被信任」说的是它还不是一张被系统预装的公开证书。

先别按人头买电子签名:我在 Linux 上把一份练习 PDF 从上传签到出证

▲ 核验时对上的是文件指纹。测试证书可以通过「签名有效」检查,但颁发者不会被系统预信任。

先别按人头买电子签名:我在 Linux 上把一份练习 PDF 从上传签到出证

▲ 根据本机 pdfsig 和 /api/verify 的真实输出重绘的终端记录,不是对软件界面的截图。中文标题写在正文里,这张图只用英文和哈希,避免字体缺字。

程序还写出了完成证书。接收人版是 72,848 字节,标题为 Audit certificate: 练习样本:设备领用确认单(非真实合同),完成时间写的是 2026-11-18T07:11:29 UTC,也就是上面的 15:11:29(Asia/Shanghai)。证书里记录了签署人「林练习」、同意电子记录的时间、签字方式为 typed,以及从创建、发送、查看、同意到完成的时间线。接收人版没有写 IP 地址。

先别按人头买电子签名:我在 Linux 上把一份练习 PDF 从上传签到出证

▲ 接收人版完成证书,来自程序写到本地磁盘的 PDF,用 pdftoppm 渲染。这是文件内容,不是后台页面截图。

我用 HTTP 下载签字 PDF 是成功的。同一套下载接口取证书时返回了 400,所以证书是从程序写到 .data/storage 的接收人版文件里取出来的。内部版证书还多了测试机回环地址 127.0.0.1,不适合对外展示,这里只引用接收人版。

· · ·

写在后面

这次本地试用的范围可以收成四句话。

Node.js 24、把服务绑在 127.0.0.1、邮件用 capture 模式,足够把一份练习 PDF 签完并得到可核对的完成件。官方更省事的数据库启动方式是 Docker 里的 Postgres 17;我这边用 Postgres 16.15 跑完了全部迁移,但不等于他们保证 16 是支持矩阵里的版本。

组织名使用中文时,默认自签发的盖章证书会在出证时失败。这是我用同一份源码复现过的问题。权宜办法是改用自己准备的证书,或者把用于签发证书的名称改成软件当前能处理的字符。我没有把它交给项目作者确认是不是已经在修。

字段位置如果用接口按估的坐标来放,可能压到正文。要放得准,还是得在准备页上对着渲染出来的 PDF 拖。这一步我没有用浏览器操作,文中的签字页就是估坐标的结果。

它解决的是「把一份 PDF 发出去并留下可核对的完成件」,不是「立刻获得和商业电子签名平台同等的法律或合规地位」。定价对比以项目 README 和它所引的 DocuSign 价目为准;功能边界也以 README 自己写明的限制为准。我没有做 Vercel 一键部署,也没有用真实邮件服务。

如果你在找其他可以自己跑在电脑或服务器上的工具,可以看看这几篇站内记录:Docker 网页面板 Arcane 3.0 实测、开源记账 Sure 自建实测、Uptime Kuma 2.5.11 自托管踩坑清单。

项目地址:https://github.com/NYLLON-SOFTWARE/SignuDoc

正文完
 0

版权声明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。

科技喵仔
版权声明:本站原创文章,由 科技喵仔 于2026-11-18发表,共计5878字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)
验证码
    中文English