Files
usdt/docs/chain-executor.md
T
2026-11-06 21:32:26 -05:00

125 lines
9.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 内网链上执行服务
## 功能与兼容边界
`usdt-chain-executor` 是独立 JDK 8 进程,复用当前钱包信封解密、HD 派生、TRON 网络选择和资源估算。
支持主钱包/子钱包 TRX 与 USDT 转账、Stake 2.0 质押/取消质押、代理/取消代理、取消全部待解冻、归集、代付。
创建钱包、扩充子账号、轮换配置密码仍走原有人工密码流程,不向执行器开放这些管理能力。
支付后端 `CHAIN_EXECUTOR_ENABLED` 默认 `false`,此时直接执行原密码代码,既不访问内网服务,也不依赖新增表。
启用后,支付后端启动时先调用 `GET /internal/v1/connectivity` 验证传输链路、来源白名单和服务令牌,
再调用 `GET /internal/v1/readiness` 验证数据库钱包网络和配置密码。两项通过时输出服务可用日志;暂时不可用时
支付系统继续启动并输出受控诊断,但所有无密码远程链上操作仍会被拒绝。URL、协议或令牌长度配置非法时仍拒绝启动。
启用后,用户输入密码时本地执行,未输入密码时仅允许交给已就绪的内网服务。两种方式共用执行记录和受控交易构造,
执行前实时校验余额、资源和链上费率。`RESOURCE_ONLY` 缺口拒绝;`DIRECT` 检查燃烧预算及全局 `trx_num` 保留量。
页面仍要求明确确认广播;服务上线不会触发历史业务自动广播。
## 部署顺序
1. 备份并执行 `sql/chain_executor.sql`,只新增执行记录表,不重建原表。
2. 使用 JDK 8 构建:`mvn -pl usdt-chain-executor -am package -DskipTests`。
3. 给独立执行器配置下表环境变量,再启动 `java -jar usdt-chain-executor/target/usdt-chain-executor-3.4.0.jar`。
4. 验证监听地址、来源白名单和服务认证;HTTPS 部署还需验证 Nginx 与证书,再配置支付后端。
5. 首次在 NILE 验证。没有执行过真实交易的构建/隔离测试不能替代实际部署验收。
禁止把真实配置密码写在脚本、命令行参数、Git 文件或支付后端配置中。通过进程管理器的受控环境注入。
### 执行器环境变量
| 变量 | 含义 |
| --- | --- |
| `CHAIN_EXECUTOR_BIND_ADDRESS` | 必填,本机明确 IPv4;只接受 `10/8`、`172.16/12`、`192.168/16` 或 `127/8` |
| `CHAIN_EXECUTOR_PORT` | 必填,HTTP 监听端口;Nginx 模式建议使用回环端口 `9089` |
| `CHAIN_EXECUTOR_ALLOWED_IPS` | 必填,支付后端实际 TCP 来源 IPv4,逗号分隔,逐个精确匹配;不支持通配/CIDR |
| `CHAIN_EXECUTOR_TOKEN` | 必填,至少 32 位的独立随机服务凭据;与后端配置相同,不是钱包密码 |
| `CHAIN_EXECUTOR_CONFIGURATION_PASSWORD` | 必填,当前全局钱包配置密码,仅在执行器进程内存中使用 |
| `CHAIN_EXECUTOR_ALLOWED_NETWORK` | 必填,`NILE` 或 `MAINNET`;与数据库全局配置不同则未就绪 |
| `CHAIN_EXECUTOR_BROADCAST_ENABLED` | 必填,只有明确为 `true` 才启动 |
| `CHAIN_EXECUTOR_DB_URL` | 与支付后端相同数据库;使用 `connectionTimeZone=LOCAL&forceConnectionTimeZoneToSession=true` |
| `CHAIN_EXECUTOR_DB_USER` / `CHAIN_EXECUTOR_DB_PASSWORD` | 独立最小权限数据库账号及密码 |
| `TRON_GRID_API_KEY` / `TRON_SCAN_API_KEY` | 按实际节点配置,沿用共享 TRON 客户端 |
独立执行器数据库权限:`usdt_config`、`wallet_address`、`usdt_payout_order`、
`usdt_aggregation_task`、`usdt_aggregation_task_item` 只需 SELECT;`usdt_chain_execution` 需 SELECT/UPDATE。
执行器不需要创建表、删除表、写业务状态或修改商户余额的权限。
### 支付后端环境变量
| 变量 | 含义 |
| --- | --- |
| `CHAIN_EXECUTOR_ENABLED` | 启用双通道时设 `true` |
| `CHAIN_EXECUTOR_BASE_URL` | 无尾斜杠/路径的 HTTP 或 HTTPS 根地址,例如 `http://192.168.10.20:9088` 或 `https://192.168.10.20:9088` |
| `CHAIN_EXECUTOR_TOKEN` | 独立服务凭据,与执行器一致 |
执行器自身只提供 HTTP。支付后端可使用 HTTP 直连,或使用 HTTPS 调用同机 Nginx,由 Nginx 转发到回环 HTTP。
生产跨机器调用推荐 HTTPS;证书 SAN 必须包含配置的内网 IP,支付后端 JVM 需信任签发 CA,禁止关闭证书校验。
只支持 IPv4 字面地址,不接受域名,避免 DNS 重绑定和意外公网解析。Nginx 示例见
`usdt-chain-executor/nginx/usdt-chain-executor.conf`。
### HTTPS + Nginx 推荐配置
执行器配置为 `CHAIN_EXECUTOR_BIND_ADDRESS=127.0.0.1`、`CHAIN_EXECUTOR_PORT=9089`、
`CHAIN_EXECUTOR_ALLOWED_IPS=127.0.0.1`。Nginx 使用内网 IP 的 `9088` 端口终止 TLS并转发到
`http://127.0.0.1:9089`。支付后端配置 `CHAIN_EXECUTOR_BASE_URL=https://内网IP:9088`。
执行器不读取证书或私钥;`CHAIN_EXECUTOR_TLS_KEYSTORE` 和 `CHAIN_EXECUTOR_TLS_PASSWORD` 已废弃。
## 仅内网访问
- 服务拒绝 `0.0.0.0`、公网、域名、IPv6 和未配置白名单的启动方式。
- 所有 HTTP 路径统一检查真实 TCP 对端 IP 和独立 Bearer 凭据;健康检查也不例外。
- 不信任 `X-Forwarded-For` 或其他代理头。经 Nginx 转发时执行器白名单应配置为 `127.0.0.1`,
Nginx 自身再用 `allow/deny` 限制支付后端真实来源 IP。
- 防火墙/安全组仅允许支付后端指定内网 IP 访问执行端口,其他来源全部拒绝。
- 禁止配置公网 NAT、端口转发、公网反向代理和公网 Ingress;容器部署只发布到宿主机指定内网地址。
- 前端只访问现有支付后端;执行器地址、凭据、密码、信封和签名交易不返回浏览器。
应用只能校验本机监听与实际来源,无法代替基础设施防火墙,也无法检测外部设备上的 NAT/公网转发规则。
## 协议与执行流程
- `GET /internal/v1/connectivity`:鉴权后验证传输链路,成功返回纯文本 `CONNECTED`。
- `GET /internal/v1/readiness`:鉴权后验证当前配置密码和网络,成功返回纯文本 `READY`,未就绪返回 503。
- `POST /internal/v1/executions`:鉴权后接收空正文通知,返回 202;只唤醒数据库扫描,不接收任意交易参数。
- `GET /system/chainExecutor/status`:现有后端登录鉴权入口,返回可用性和当前操作人最近 5 条公开执行记录。
业务指令先写数据库,通知只是加速信号;通知丢失时每 2 秒补扫。队列指令 10 分钟内未开始则拒绝执行。
就绪校验会解密信封但不签名;实际执行再次核对信封版本、网络、钱包启用状态、地址与索引、代付/归集业务状态及金额。
私钥仍由 `WalletSigningService` 在内存中派生,派生地址不匹配时拒绝。
| 状态 | 语义与恢复 |
| --- | --- |
| `QUEUED` | 持久化待执行;REMOTE 可以补扫;PASSWORD 不会在无人输入密码时自动解锁 |
| `RUNNING` | 已原子领取,正在校验/签名;不凭超时自动释放,防止多进程同时签名 |
| `SIGNED` | 签名交易与哈希已落库,广播前的持久化屏障;只查询或重播原字节,不重新构造 |
| `BROADCASTED` | 节点确认接收或按哈希查到原交易;不等同于链上执行成功 |
| `FAILED` | 明确在签名前失败,可以重新输入密码或重试远程执行;旧记录归档保留 |
| `CHAIN_FAILED` | 原代付链上确认任务已确认原哈希执行失败,允许下一次人工尝试;保留旧交易审计 |
广播包含首次最多尝试 4 次,使用同一笔签名交易。`SIGNED` 后响应丢失或数据库断连不改为可重新广播的失败。
恢复任务查原哈希或重播同一交易,不能因交易过期/未查到就自动创建新交易。
代付保留状态 6 直到结果明确;后端每 5 秒同步为已广播,再由原链上确认和账务结算完成。
归集明细保留状态 4,逐明细同步交易哈希与幂等支出流水;全部明细结束后同步主任务。
执行器只写执行记录,不能代替支付系统做审核或结算。
## 维护与异常恢复
- 密码轮换后,旧环境密码无法解密,服务就绪状态立即失败。更新执行器环境变量并重启;不要通过 HTTP 发送新密码。
- 切换全局网络时,必须同步调整执行器允许网络。旧网络 `SIGNED` 记录未处理完前不要切换。
- 存在 QUEUED/RUNNING/SIGNED 未决记录时,不要关闭后端功能开关后改走不受新表约束的旧通道。
- `SIGNED` 长期未确认:核对网络、交易哈希、交易过期时间与链上结果。禁止清空签名记录或直接重新转账。
- `RUNNING` 在进程异常退出后可能保留:先停止所有本地和远程执行进程,确认该记录没有 `signed_transaction`、没有交易哈希,
且签名前持久化屏障确实未通过,再由维护人员将其标记为 FAILED。禁止运行中按时间强制抢占。
- 后端分发归集期间异常退出时,主任务可能保留“正在分发链上执行任务”。先核对已创建指令与未提交明细,
不要直接重跑主任务。明确已提交结果后再恢复业务状态;该保守占位用于避免重复归集。
需要停机维护时先停止新提交,等待已签名交易和业务同步完成,再停执行器、关闭功能开关。
`signed_transaction` 不包含私钥,但具有广播能力,必须限制数据库读取和备份访问,不得公开或写日志。
## 验证
隔离测试覆盖:同业务并发提交/领取只成功一次、签名后不可标记为可重试失败、密码不入库、
广播响应丢失时同一字节重播与恢复不重新签名、真实回环 HTTP 的 IP 白名单/凭据校验、伪造转发头拒绝、密码轮换未就绪。
部署仍须验证公网无法连接、非白名单内网来源拒绝、错误服务凭据拒绝、TLS 验证和实际 NILE 链上确认。