yuqei
1d85329a6a
Build and Test Quality Gate / Contract Web typecheck and build (pull_request) Successful in 9m12s
Build and Test Quality Gate / Isolated Alibaba and Tencent KMS gateway (pull_request) Failing after 4m53s
Build and Test Quality Gate / Python tests and Contract API migration (pull_request) Failing after 24m55s
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 8m42s
91 lines
4.5 KiB
Markdown
91 lines
4.5 KiB
Markdown
# e签宝电子签署连接器运维手册
|
|
|
|
日期：2026-08-25
|
|
|
|
## 1. 模式与配置
|
|
|
|
本地验收：
|
|
|
|
```dotenv
|
|
ELECTRONIC_SIGNATURE_PROVIDER=development_mock
|
|
ELECTRONIC_SIGNATURE_ENVIRONMENT=sandbox
|
|
ELECTRONIC_SIGNATURE_LEGAL_EFFECT_ENABLED=false
|
|
ELECTRONIC_SIGNATURE_RETURN_URL=http://localhost:3000/contracts
|
|
```
|
|
|
|
生产配置至少包括：
|
|
|
|
```dotenv
|
|
ELECTRONIC_SIGNATURE_PROVIDER=esign_saas_v3
|
|
ELECTRONIC_SIGNATURE_ENVIRONMENT=production
|
|
ELECTRONIC_SIGNATURE_LEGAL_EFFECT_ENABLED=true
|
|
ELECTRONIC_SIGNATURE_ESIGN_BASE_URL=https://openapi.esign.cn
|
|
ELECTRONIC_SIGNATURE_ESIGN_APP_ID=<secret-injected-app-id>
|
|
ELECTRONIC_SIGNATURE_ESIGN_APP_SECRET=<secret-injected-app-secret>
|
|
ELECTRONIC_SIGNATURE_CALLBACK_URL=https://<contract-api-host>/api/v1/integrations/electronic-signature/esign/callback
|
|
ELECTRONIC_SIGNATURE_RETURN_URL=https://<web-host>/contracts
|
|
ELECTRONIC_SIGNATURE_IDENTITY_HASH_SECRET=<independent-random-secret-at-least-32-chars>
|
|
```
|
|
|
|
生产中 App Secret 与账号摘要密钥必须由密钥管理服务或只读 secret 文件注入，不得提交到 Git、镜像或工单。切换配置前执行 `/api/v1/runtime/config-check`，任何 electronic-signature 错误都应阻止发布。
|
|
|
|
## 2. 上线顺序
|
|
|
|
1. 备份数据库并执行 `alembic upgrade head`，确认 head 为 `20260825_0064`。
|
|
2. 先以 `legal_effect=false` 启动，检查提供方状态、健康检查与回调公网连通性。
|
|
3. 在隔离租户完成一个个人签署和一个企业经办人签署，覆盖拒签与过期。
|
|
4. 对已签文件计算 SHA-256，确认页面存证记录的 `local_hash_verified=true`。
|
|
5. 验证重复回调只产生一个业务状态变化；停用回调后以“同步状态与证据”完成补偿。
|
|
6. 由法务、安全和业务负责人共同签署发布记录，再启用法律效力开关并滚动重启。
|
|
|
|
## 3. 日常监控
|
|
|
|
建议至少监控：
|
|
|
|
- 按状态与租户统计签署流程数量、`creating/signing` 停留时长和完成率。
|
|
- `esign_transport_error`、上传/转换超时、回调 401、回调 5xx、证据下载失败和哈希不一致。
|
|
- 已完成但 `evidence_status != synced` 的流程。
|
|
- 已完成且 `legal_effect=true`，但合同因正文变化未进入 `signed` 的流程。
|
|
- 回调接收时间与提供方事件时间差、主动查询调用量和提供方限流。
|
|
|
|
告警与日志不得包含原始签署账号、签署 URL、App Secret、回调原文或已签文件正文。
|
|
|
|
## 4. 常见故障
|
|
|
|
### 提供方请求失败
|
|
|
|
保留流程错误码和 trace ID，确认官方服务状态、出口网络、App ID、时钟和签名配置。不要直接在数据库把流程改成完成；恢复后使用主动同步。
|
|
|
|
### 回调验签失败
|
|
|
|
检查 e签宝控制台回调地址、App ID、服务器时钟、代理是否改写请求体或查询参数。401 应保持失败，禁止临时关闭验签。
|
|
|
|
### 签署完成但证据失败
|
|
|
|
点击“同步状态与证据”重拉。若为 `signed_artifact_hash_mismatch`，隔离该证据包，保留提供方流程 ID 与本地摘要，联系供应商核验，不得改成 `synced`。
|
|
|
|
### 合同未进入已签署
|
|
|
|
确认提供方模式为生产且法律效力开关开启、完成状态已经验证、合同发起时为 `approved`，并检查 `contract_version_changed_before_completion`。正文变化时应重新审批并发起新流程。
|
|
|
|
### 签署链接遗失
|
|
|
|
管理员重新输入对应签署人的原始手机号或邮箱。系统只比对带密钥摘要，匹配后向提供方实时获取新链接；禁止从日志或数据库寻找旧链接。
|
|
|
|
## 5. 回退
|
|
|
|
1. 先设置 `ELECTRONIC_SIGNATURE_LEGAL_EFFECT_ENABLED=false` 并滚动重启，停止新流程改变合同状态。
|
|
2. 若需完全停止发起，设置 `ELECTRONIC_SIGNATURE_PROVIDER=disabled`；保留数据库和已下载证据供查询。
|
|
3. 不删除进行中流程，不撤销已产生的第三方签署与存证；按企业制度在提供方控制台处理撤销或终止。
|
|
4. 数据库降级只允许在确认三张新表为空且完成备份后执行；常规故障不要执行 downgrade。
|
|
5. 故障恢复后先在隔离租户使用 `legal_effect=false` 重验，再逐步恢复生产开关。
|
|
|
|
## 6. 审计证据清单
|
|
|
|
- 应用和环境配置审批记录（不含 secret）
|
|
- 合同 ID、版本 ID、发起时正文 SHA-256
|
|
- 提供方流程 ID、状态事件摘要、验签结果与时间戳
|
|
- 脱敏签署人快照及身份验证状态
|
|
- 已签文件/证书 SHA-256、存证交易标识、哈希比对结果
|
|
- 主动补偿、失败处置、密钥轮换和发布/回退审批记录
|