自打开始接电商、供应链这块的项目，合同这事儿就一直绕不开。以前图省事，直接用第三方电子签SaaS，按份数付费，一年下来账单挺吓人。后来接到一个客户需求，要求合同签署能力要嵌到他们的小程序、公众号、APP、H5里，而且数据得留在自己手上，我就意识到不能再单纯依赖外部SaaS了，得有一套基于JAVA的电子合同电子签名系统源码，自己掌握核心，支持多端接入。这篇文章就是把我从选型到落地、从踩坑到稳定的完整过程梳理一遍，给正准备干同样事情的兄弟一个参考。
这套系统解决的核心问题其实很朴素：把线下“盖章签字”这件事变成线上“身份认证+意愿确认+行为存证”。适合谁看？主要是Java技术栈的开发者、项目负责人，或者正在做OA、ERP、供应链平台想集成合同签署能力的朋友。内容会涉及到技术选型、签名链路设计、多端适配、部署运维这些硬骨头，我尽量把当时真实遇到的问题和解决办法都交代清楚。
1. 为什么我在电商项目里选择自研电子合同系统而不是继续用SaaS
先聊点决策层面的东西。很多人一听电子合同，第一反应是“直接用某某签不就行了”。确实，对于小微企业、合同量不大的场景，SaaS是最省事的路子，注册个账号、上传模板、发个链接就能签。但一旦业务量上来，或者合同数据涉及核心商业机密，SaaS方案的短板就很明显了。
1.1 自研 vs SaaS的成本账与数据主权
我这边当时算过一笔账。客户公司是做B2B供应链的，每月合同签署量在两万份左右，第三方平台的单价算下来大概每份几块钱，加上实名认证、短信、存证这些增值服务，一年下来几十万的成本。而且合同数据全部沉淀在第三方平台，想导出到自己数据库做二次分析、想跟自己的ERP系统做深度打通，接口文档看得脑壳疼，限制还多。
自研系统前期投入主要在人力，一个后端、一个前端，再加上我抽时间盯架构，大概一个半月把核心链路跑通。后续维护成本主要就是服务器和几个基础服务的费用，跟按份付费比起来，边际成本几乎可以忽略。更重要的是，数据在自己手里，合同原文、签署记录、操作日志全部落库，客户要审计要追溯，随时能查。
1.2 业务场景驱动：不止是“签个字”那么简单
客户的实际业务里，合同签署不是孤立的。采购订单审核通过后要自动生成合同，合同要同步到财务系统做付款依据，签署完成后要通知物流部门备货。这里面涉及大量的系统对接和状态流转。用SaaS的话，你得把外部回调接到自己系统里，再转发给各个内部服务，链路长、延迟高、排错麻烦。
自研之后，合同模块直接长在自己的业务系统里，生成、审批、签署、归档、通知是一条完整的内链，任何一环出问题都能直接看日志定位。对于需要频繁定制合同模板、对接多种签署方式（个人单签、企业双签、骑缝章）的团队来说，自研的灵活性是SaaS没法比的。
2. JAVA技术栈下电子合同系统的整体架构设计
定下自研方向之后，第一个问题就是技术选型。我们团队主栈是Java，Spring Boot + MyBatis Plus这套组合比较熟，所以整体架构沿这个方向走，没有引入太花哨的东西，稳定性优先。
2.1 核心服务模块划分
我把系统拆成几个核心模块，每个模块职责单一，减少耦合：
| 模块 | 职责说明 | 关键依赖 |
|---|---|---|
| 合同模板服务 | 模板上传、变量解析、PDF渲染 | FreeMarker、iText、OpenPDF |
| 签署流程服务 | 发起签署、签署顺序控制、状态机流转 | Redis、RabbitMQ |
| 实名认证服务 | 个人/企业认证、人脸核身、运营商三要素 | 第三方认证API、MinIO |
| 证书与签名服务 | 数字证书签发、哈希签名、验签 | 国密算法库、HSM/软密钥 |
| 存证归档服务 | 合同文件存储、操作日志、时间戳 | OSS/MinIO、MySQL |
模块之间通过REST API和MQ异步消息通信。比如发起签署之后，流程服务发个消息出去，证书服务异步准备签名参数，模板服务渲染合同PDF，最后归档服务把成品存起来。这样链路不会阻塞在某一环，高峰期也能扛得住。
2.2 数据库设计与文件存储的取舍
合同系统的数据主要分三类：用户数据、模板数据、签署凭证数据。用户数据直接复用业务系统的用户表，加一个实名信息扩展表。模板数据单独建表，存模板文件ID、变量定义、版本号。签署凭证数据是核心，一张sign_record表记录每一次签署的唯一ID、合同ID、签署人、证件类型、签名图片URL、证书序列号、时间戳。
文件存储方面，合同PDF和签名图片必须用对象存储，不要扔MySQL里，也别放本地磁盘。我们用MinIO做私有化部署，小规模跑起来很轻松。如果客户那边有阿里云OSS或者腾讯云COS，配置S3协议接口就行，代码层面做一层FileStorage接口抽象。
public interface FileStorageService { String upload(InputStream is, String fileName, String contentType); InputStream download(String fileId); void delete(String fileId); }这样底层存储随便换，不影响业务代码。我在MinIO和OSS两个实现之间切换过，只要配置一个bucket和accessKey，其他都没动。
3. 电子签名的核心链路：实名、意愿、生成与存证
这一块是整个系统含金量最高的地方。外行人以为电子合同就是把合同图片贴上去，再画个签名图。实际上，要保证电子签名具备法律认可的有效性，必须满足几个条件：签署身份真实、签署意愿真实、签名不可篡改、签署时间可信。
3.1 实名认证：三层校验缺一不可
实名认证决定了“签字的这个人是不是他本人”。我们做了三层校验，根据业务风险级别灵活组合：
- 基础层：身份证号 + 姓名 + 人脸核身。个人身份信息提交后调用身份证OCR，然后活体检测。
- 增强层：银行卡四要素校验，用于涉及资金往来的合同。
- 企业层：营业执照信息 + 法人实名 + 企业对公账户打款验证，这套流程周期长一点，但企业级合同必须走完。
人脸核身和银行卡校验要接第三方服务。这里有个经验：不要把第三方返回的证件照片直接存下来做展示，涉及个人隐私，存一个hash值或者脱敏后的身份证号就够了。很多合同纠纷最后都是因为过度收集信息反而惹麻烦。
// 实名认证结果统一封装 public class CertifyResult { private Boolean passed; private String certNo; // 身份证号脱敏存储 private String name; private String certType; private LocalDateTime certifiedTime; }3.2 意愿确认与数字证书签名
意愿确认常见做法是短信验证码 + 签署页展示全文 + 手写签名原笔迹采集。这一步不是为了技术上多难，是为了事后有证据链：用户自主输入验证码、主动点击签署按钮、亲手绘制签名图片，这些行为数据都会被记录到日志里。
技术上是这么走的：前端把用户手写签名生成为一张透明背景的PNG，同时把签名数据和签署参数（合同ID、签署页码、坐标）一起打包，传给后端。后端用私钥对这个请求的哈希值做一次签名，生成一段signValue。这段签名Value能证明“这个请求确实是持有关键私钥的服务发出的”，再配合时间戳服务，形成完整的签名数据包。
加密这块，我们优先用了国密算法（SM2/SM3/SM4），银行和国企客户认这个。内部对接老系统时也保留了RSA的兼容模式。实测下来国密算法在Java里跑性能没啥压力，就是用第三方加密机的时候要注意，不同厂商的接口文档写法差别挺大。
关键点：前端传给后端的内容，后端必须先做完整性校验。比如合同ID、签署页码、坐标点、签名图片尺寸，任何一项对不上都要拒绝，防止有人通过篡改参数把签名贴到别的页面上。3.3 合同PDF渲染与签章定位策略
合同模板我们用FreeMarker写HTML，然后用OpenPDF渲染成PDF。这么做的好处是模板维护方便，变量替换清晰。HTML模板里用占位符如${buyerName}，后端拿到签署人的信息直接灌进去，最后统一渲染。
签章定位是个细节活儿。个人签名一般是浮在指定坐标上，企业公章则要加上骑缝章效果。骑缝章的做法是：把合同PDF每一页计算出一个hash值，再用私钥签名，把签名值拼成一个横跨页边界的图片，让章的一部分落在当前页边缘、一部分延伸到下一页。这样只要有任何一页被替换或修改，骑缝章的连续性就会被破坏，一眼就能看出来。
// 生成骑缝章图片的简化思路 BufferedImage sealImage = createSealImage("公司公章内容"); // 按页切分pdf，在页边叠加印章影像，使用PDFBox的addImage逐页处理 for (int i = 0; i < pageCount; i++) { addOverlayImage(doc, sealImage, i, SealPosition.RIGHT_EDGE); }4. 多端适配踩坑：小程序、公众号、APP与H5的差异处理
这是我花时间最多、也是最有收获的一块。标题里的“支持小程序＋公众号＋APP＋H5”看着轻飘飘的，真做起来每个端都有自己一堆毛病。
4.1 小程序端的限制与处理方式
微信小程序的坑主要在两个地方。第一是签名图片的临时文件路径不能用，必须调用wx.getFileSystemManager().readFile转成base64再传给后端，不然后端拿不到可用的图片。第二是小程序里跳转签署页不能直接用浏览器window.open，要用wx.navigateTo跳到web-view页面，而且web-view的域名必须在小程序后台配置业务域名白名单，否则直接白屏。
另外，小程序的web-view不支持键盘弹起时页面高度自适应，合同详情页在手机上体验特别怪异。我的解决办法是签名页面不用web-view，直接用原生小程序页面实现，签名板固定定位在底部。这样最稳。
4.2 公众号与H5的浏览器兼容性问题
公众号和H5本质上都是在浏览器里跑，统一用H5技术栈。但公众号有一个特殊点——它运行在微信内置浏览器（X5内核）里，老版本的X5对CSS的position: fixed支持时好时坏，签名板偶尔会飘到页面中间去。排查了半天，最后给签名板容器加了一个transform: translateZ(0)强制开启硬件加速，问题解决。
H5端还有个大坑是PDF预览。PC浏览器直接用window.open没问题，手机端尤其是iOS Safari对PDF预览支持很差。我们最后用了pdf.js在页面里渲染，虽然要引入额外的依赖，但兼容性真的稳很多。另外手机浏览器会拦截自动打开的下载窗口，签署完成后引导用户“点击链接下载合同”，比强制弹出右键保存靠谱。
4.3 APP内嵌WebView与原生能力的打通
APP端我们用的是混合方案，壳子原生，核心签署流程走WebView。这样意味着原本在H5里实现的人脸核身，必须通过JsBridge调用APP原生的人脸识别SDK，否则在WebView里调摄像头会有权限问题。
打通方式是挂一个全局的JS对象，H5端通过window.AndroidNative.invokeCamera调用原生方法。iOS那边用WKScriptMessageHandler处理。注意回调的时序问题，原生识别完成之后要主动调JS回调函数，否则H5会一直等。这个接口协议一开始就要设计好，最好是Promise风格的异步调用，不然代码会越写越乱。
下表列一下我在多端适配过程中遇到的高频问题及最终处理方案：
| 端 | 卡点问题 | 处理方案 |
|---|---|---|
| 小程序 | web-view业务域名白名单 | 后台配置，另加备用域名 |
| 小程序 | 图片临时文件失效 | readFile转base64传输 |
| 公众号 | fixed定位漂移 | 强制开启GPU加速 |
| H5 | PDF预览兼容 | 接入pdf.js渲染 |
| APP | WebView调原生相机 | JsBridge + Promise回调 |
5. 源码交付后的部署与二次开发要点
系统跑通不是终点，交付源码给客户之后，他们一定会改需求、接新场景。这块提前做好规划，后面能省很多事。
5.1 部署架构与服务器规划
我那边部署是这样的：两台应用服务器做集群，一台MySQL，一台Redis，一台MinIO。所有服务用Docker Compose编排，数据库有独立的持久化卷。
Java应用启动时JVM参数一定要根据服务器内存调整，别用默认值。我碰到过一次客户那边服务器只有2G内存，默认堆大小直接把机器干崩了。后来在部署文档里明确要求，Xmx不要超过物理内存的一半。
java -Xms512m -Xmx1024m -jar contract-server.jar另外，MQ在单机部署时可以用RabbitMQ的单节点模式，但如果客户那边业务量不大，建议直接去掉MQ层，把异步任务改用Spring的@Async+ 线程池。部署复杂度降一个档次，问题也少很多。
5.2 二次开发常见需求与扩展点
交付源码后，客户问得最多的几个需求我列一下：
- 合同模板想支持富文本编辑器上传，而不是写死HTML文件。这个可以在模板服务里加一个H5编辑器，保存时转成HTML模板。
- 想对接自己的CA证书系统。这块预留了证书服务接口，只要实现一个适配器就能切换CA渠道。
- 企业内部想走审批流。合同发起后要先经过OA系统审批再进入签署流程，这里的对接方式是暴露一个发起合同的API，由外部系统传入审批结果。
- 批量签署需求，比如同一份框架协议要发给多个供应商分别签署。这个需要在流程服务里加一个子签署人数组，循环生成签署链接。
所有需求里，我建议提前把“签署回调通知”的机制做好。无论什么业务系统，都希望合同状态变化时能及时感知。我们用RabbitMQ广播通知，业务系统订阅消息做后续处理。消息体里带上contractId、signRecordId、status、signTime，其他细节业务系统自己查。
{ "contractId": "CT20250109001", "signRecordId": "SIGN_20250109001", "status": "COMPLETED", "signTime": "2025-01-09 14:23:11" }5.3 合规性提醒：别让技术背锅
最后聊句实在话。电子合同能不能被司法认可，关键不在你的代码多漂亮，而在于整个签署过程的证据链是否完整、是否符合电子签名法里“可靠电子签名”的条件。这部分如果把握不准，一定要在系统里保留好所有原始操作日志，并且建议在有条件的情况下做第三方存证。技术上我们能做的，是把每个环节都设计得透明、可追溯，至于司法认定的标准，那是法律专业人士的战场，系统提供数据支撑就足够。
拿我自己来说，经历过一次合同纠纷仲裁，当时对方否认签过合同。因为我们系统记录了签署人完整的实名认证信息、短信验证码下发记录、签名时的IP地址、设备指纹、PDF哈希值，仲裁员当庭验证了所有数据链路，最后认定合同有效。那一刻我才真切感受到，当初在日志和存证上较真的劲没白费。
6. 这套源码系统目前的能力边界与后续迭代方向
没有哪套系统是完美的，这套电子合同签名系统也踩了不少边。我最后把当前的能力边界和后续打算做的方向捋一捋，给有同样需求的朋友一个参考。
6.1 当前已经稳定的能力
项目里跑得最稳的几个功能模块包括：个人和企业实名认证、合同模板变量渲染、合同PDF生成、手写签名采集、数字签名加密、骑缝章生成、签署状态机管理、签署记录存储、多端页面接入。尤其是签署状态机管理，我们定义了DRAFT、PENDING_SIGN、PARTIAL_SIGNED、COMPLETED、TERMINATED、CANCELLED六个状态，流转关系清晰，后端代码可维护性高。
6.2 还做得不够好的地方
第一，手写签名的笔迹识别防伪我们没做太深，目前只是采集图片并记录行为日志，如果需要更高强度的防抵赖，需要接入专业笔迹识别引擎，成本会上去。
第二，企业证书申请流程还没有完全线上自动化，涉及企业对公打款验证的环节，还是半人工审核。主要是考虑到金额变动异常时的风险控制，这块保留了人工兜底，不符合全自动化的预期。
第三，存证服务目前是自建的时间戳和文件hash记录，如果客户对司法鉴定要求特别高，建议再对接外部的区块链存证平台，把合同hash和签署信息登记到链上。
6.3 后续迭代计划
下一步我打算做两件事。一是把合同模板编辑器做成Web可视化拖拽模式，省得每次改模板都让后端改HTML代码，效率太低。二是引入AI辅助审核，比如自动识别合同里的关键风险条款，把异常条款标识出来推送给法务，这能大大减少人工审阅成本。这两块做完，整个系统的完整度和竞争力还能再上一个台阶。
另外，针对多租户SaaS场景也在调研。现在的源码版偏私有化部署，如果多个分公司独立使用，可以通过增加租户ID字段做数据隔离。表结构已经预留了tenant_id列，只是页面权限和路由还没完全按租户维度改造，这块工作量不小数，但确实是大客户高频问的需求。
最后分享一个小技巧。不管客户要不要，我都会在合同详情页放一个“下载签署报告”的按钮，报告里汇总了合同基本信息、双方实名认证信息、签署时间、签署设备、证书序列号、PDF校验值。真正遇到纠纷时，这页报告比什么技术文档都好使。相当于给合同系统留了一个“黑匣子”，平时不占地方，关键时刻保命。
