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
4.5 KiB
4.5 KiB
e签宝电子签署连接器运维手册
日期：2026-08-25
1. 模式与配置
本地验收：
ELECTRONIC_SIGNATURE_PROVIDER=development_mock
ELECTRONIC_SIGNATURE_ENVIRONMENT=sandbox
ELECTRONIC_SIGNATURE_LEGAL_EFFECT_ENABLED=false
ELECTRONIC_SIGNATURE_RETURN_URL=http://localhost:3000/contracts
生产配置至少包括：
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. 上线顺序
- 备份数据库并执行
alembic upgrade head，确认 head 为20260825_0064。 - 先以
legal_effect=false启动，检查提供方状态、健康检查与回调公网连通性。 - 在隔离租户完成一个个人签署和一个企业经办人签署，覆盖拒签与过期。
- 对已签文件计算 SHA-256，确认页面存证记录的
local_hash_verified=true。 - 验证重复回调只产生一个业务状态变化；停用回调后以“同步状态与证据”完成补偿。
- 由法务、安全和业务负责人共同签署发布记录，再启用法律效力开关并滚动重启。
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. 回退
- 先设置
ELECTRONIC_SIGNATURE_LEGAL_EFFECT_ENABLED=false并滚动重启，停止新流程改变合同状态。 - 若需完全停止发起，设置
ELECTRONIC_SIGNATURE_PROVIDER=disabled；保留数据库和已下载证据供查询。 - 不删除进行中流程，不撤销已产生的第三方签署与存证；按企业制度在提供方控制台处理撤销或终止。
- 数据库降级只允许在确认三张新表为空且完成备份后执行；常规故障不要执行 downgrade。
- 故障恢复后先在隔离租户使用
legal_effect=false重验，再逐步恢复生产开关。
6. 审计证据清单
- 应用和环境配置审批记录（不含 secret）
- 合同 ID、版本 ID、发起时正文 SHA-256
- 提供方流程 ID、状态事件摘要、验签结果与时间戳
- 脱敏签署人快照及身份验证状态
- 已签文件/证书 SHA-256、存证交易标识、哈希比对结果
- 主动补偿、失败处置、密钥轮换和发布/回退审批记录