EsignHelper

Appearance

2026-04-20
2218
9.5m

Server ​

esign-helper-server 是独立可部署的 e签宝服务模块。

它的定位不是重复造一套 e签宝逻辑，而是把自身内置的核心能力服务化输出，让多个业务系统通过统一 HTTP 接口共享同一套能力。

1. 模块定位 ​

这个模块主要面向两类团队：

  • 想把 e签宝能力做成统一微服务的平台团队
  • 不希望每个业务系统都各自重复接入 e签宝 的组织

它适合：

  • 单实例部署
  • 多实例集群部署
  • 接在网关、SLB、Ingress 后统一暴露

它不适合：

  • 当作核心能力研发模块继续堆业务逻辑
  • 在这里继续堆叠业务系统私有逻辑

2. 产品价值 ​

从产品角度看，esign-helper-server 的意义在于：

  • 统一对外接口
  • 统一回调入口
  • 统一数据库口径
  • 统一升级节奏
  • 统一日志与运维边界
  • 统一管理面板与巡检入口

这对多系统组织特别重要，因为平台一旦形成，后续新增系统就不需要再在每个系统里重新接一次 e签宝。

3. 模块结构 ​

text
esign-helper-server
├─ README.md
├─ pom.xml
└─ src
   ├─ main
   │  ├─ java/top/qnmdmyy/server
   │  └─ resources
   └─ test

关键类：

4. 当前提供的接口 ​

server 现在对外同时暴露两层接口：

  • 集成层接口：面向“业务系统通过 businessId / tenantCode / systemCode 发起并归档流程”
  • 能力层接口：面向“直接把 server 内置能力域 HTTP 化输出”

4.1 集成层流程接口 ​

  • POST /api/esign/flows/file
  • POST /api/esign/flows/template
  • GET /api/esign/flows/{signFlowId}
  • GET /api/esign/flows?tenantCode=...&systemCode=...&businessId=...

4.2 能力域 HTTP 接口 ​

已补齐的主要能力域：

  • auth
  • account
  • seal
  • member
  • contractFile
  • flowTemplate
  • contractManagement
  • enterpriseConsole
  • catalog
  • raw

代表性接口：

  • POST /api/esign/auth/person-auth-url
  • GET /api/esign/auth/persons/identity-info
  • POST /api/esign/accounts/persons
  • POST /api/esign/seals/organization-template
  • GET /api/esign/organizations/{orgId}/members
  • POST /api/esign/files/upload-url
  • POST /api/esign/sign-flows/create-by-file
  • POST /api/esign/sign-flows/create-by-sign-template
  • POST /api/esign/sign-flows/{signFlowId}/signers/sign-fields
  • POST /api/esign/evidence/reports
  • GET /api/esign/workspaces/{orgId}
  • GET /api/esign/catalog/capability-groups
  • POST /api/esign/raw/invoke

4.3 回调入口 ​

  • POST /esign/callback/sign-notify
  • POST /esign/auth/notify
  • GET /esign/auth/redirect
  • POST /esign/auth/redirect

4.4 服务信息与管理面板 ​

  • GET /api/esign/service/info
  • GET /admin/esign
  • GET /admin/esign/dashboard

管理面板基于 thymeleaf 构建，当前展示：

  • 服务实例信息
  • 流程总量、运行中、已完成统计
  • 任务总量
  • API 调用成功/失败统计
  • 最近流程
  • 最近任务
  • 最近 API 调用日志

5. 为什么 server 必须用共享持久化 ​

这是本模块最重要的设计前提。

5.1 原因 ​

服务化以后，流程和资源都是“共享状态”：

  • 回调可能打到 A 节点
  • 查询可能落到 B 节点
  • 某些资源归档可能在 C 节点执行

如果你还用内存仓储，就会出现：

  • 数据在不同实例之间不一致
  • 节点重启后数据丢失
  • 集群下状态漂移

5.2 保护机制 ​

server 启动时会通过 ServerPersistenceGuard.java 强制校验：

  • 流程仓储不能是内存实现
  • 任务仓储不能是内存实现
  • 主体、资源、账号、授权、出证相关仓储也不能是内存实现

也就是说，server 的定位就是：

必须基于共享数据库运行

6. 如何运行 ​

6.1 Maven 运行 ​

bash
mvn -q -f esign-helper-server/pom.xml spring-boot:run

6.2 打包 ​

bash
mvn -q -f esign-helper-server/pom.xml package

6.3 最小配置 ​

通常至少需要：

yaml
esign:
  enabled: true
  app-id: your-app-id
  app-secret: your-app-secret
  host: https://openapi.esign.cn
  default-tenant-code: DEFAULT_TENANT
  default-system-code: DEFAULT
  callback-endpoint-enabled: true
  callback-path: /esign/callback/sign-notify
  auth-callback-endpoint-enabled: true
  auth-notify-path: /esign/auth/notify
  auth-redirect-path: /esign/auth/redirect

同时你还需要一个共享数据库。

server 启动后会自动自检当前数据源类型，并根据 JDBC 连接识别为：

  • MySQL
  • PostgreSQL
  • Oracle
  • SQL Server

随后加载 server 自带的对应完整 DDL，对缺失的默认表和索引执行补建； 如果对象已经存在，则直接跳过，不会重复创建。

默认情况下，server 已经把 Hibernate 自动建表关闭，改由这套启动自检机制负责默认表初始化。

如果你准备直接使用管理面板，建议保持 API 调用日志开启：

yaml
esign:
  api-log-enabled: true

补充说明：

  • callback-path 用于签署流程回调。
  • auth-notify-path / auth-redirect-path 用于授权 NotifyUrl/RedirectUrl。
  • 如果你只是想换 server 对外暴露的授权回调地址，可以直接改这两个配置，默认归档逻辑仍然会保留。

7. 数据库建议 ​

7.1 新服务初始化 ​

如果是新部署的 server，现在有两种推荐方式：

  • 默认方式：直接依赖 server 启动期自检自动补齐默认表结构
  • 治理方式：在正式生产库里用 Flyway 显式管理表结构升级

其中启动自检适合：

  • 新环境首次落地
  • 本地联调
  • 测试环境快速起服务

它会自动补齐的默认对象包括当前内置的 15 张表，以及对应的常用索引，例如：

  • ESIGN_FLOW
  • ESIGN_FLOW_TASK
  • ESIGN_PSN_IDENTITY
  • ESIGN_ORG_IDENTITY
  • ESIGN_SEAL
  • ESIGN_MEMBER
  • ESIGN_TEMPLATE
  • ESIGN_FILE
  • ESIGN_FLOW_DETAIL
  • ESIGN_PSN_ACCOUNT
  • ESIGN_ORG_ACCOUNT
  • ESIGN_PSN_AUTH
  • ESIGN_ORG_AUTH
  • ESIGN_EVIDENCE_REPORT
  • ESIGN_API_CALL_LOG

需要说明的是：

  • 如果表不存在，会自动创建
  • 如果独立索引不存在，会自动补齐
  • 如果表已经存在，则不会对已有表做侵入式 ALTER
  • 对于生产环境的结构演进，仍然推荐后续接入 Flyway 做显式版本治理

推荐阅读：

7.2 表结构说明 ​

推荐阅读：

8. 单机与集群部署建议 ​

8.1 单机部署 ​

适合：

  • 内部测试
  • 小流量场景
  • 平台试运行

要求：

  • 仍然要有共享数据库

8.2 集群部署 ​

适合：

  • 多业务系统统一接入
  • 流量较大
  • 需要横向扩容

建议：

  • 所有实例使用同一数据库
  • 所有实例使用同一套 e签宝应用配置
  • 统一通过网关暴露签署回调与授权回调入口
  • 配健康检查和实例摘除

9. 产品边界 ​

server 和 starter 是两个互相独立的产品模块。

可以理解为：

  • starter：适合嵌入业务系统的本地集成形态
  • server：适合统一部署、统一运维的远程服务形态

二者的原则是：

  • 常规 e签宝能力尽量保持功能对齐
  • 各自拥有独立源码、独立资源、独立构建与运行链路
  • 只有像 dashboard 这类明显只适合服务端的能力，才允许只存在于 server

10. 面向开发者的推荐阅读顺序 ​

如果你要维护这个模块，建议按下面顺序看：

  1. EsignHelperServerApplication.java
  2. EsignFlowCommandController.java
  3. EsignFlowQueryController.java
  4. ServiceInfoController.java
  5. AdminPanelController.java
  6. ServerPersistenceGuard.java
  7. 最后再回看 ServerDefaultSchemaInitializer.java 和 ServerPersistenceGuard.java，把启动建表与共享持久化约束串起来理解

11. 测试 ​

关键测试：

运行：

bash
mvn -q -f esign-helper-server/pom.xml test

补充说明：

  • server 和 starter 处于同一个仓库，但彼此独立构建。
  • 服务化运行、打包和测试都应直接针对 esign-helper-server/pom.xml 执行。

12. 结论 ​

如果一句话概括：

esign-helper-server 是一个可独立部署、可统一运维、可支撑单机与集群的 e签宝平台服务模块。

最近更新

EsignHelper Portal powered by VitePress Theme Teek

Copyright © 2026 EsignHelper