Files
usdt/docs/chain-executor.md
T

8.8 KiB
Raw Blame History

内网链上执行服务

功能与兼容边界

usdt-chain-executor 是独立 JDK 8 进程,复用当前钱包信封解密、HD 派生、TRON 网络选择和资源估算。 支持主钱包/子钱包 TRX 与 USDT 转账、Stake 2.0 质押/取消质押、代理/取消代理、取消全部待解冻、归集、代付。 创建钱包、扩充子账号、轮换配置密码仍走原有人工密码流程,不向执行器开放这些管理能力。

支付后端 CHAIN_EXECUTOR_ENABLED 默认 false,此时直接执行原密码代码,既不访问内网服务,也不依赖新增表。

启用后,支付后端启动时先调用 GET /internal/v1/connectivity 验证 TLS、来源白名单和服务令牌, 再调用 GET /internal/v1/readiness 验证数据库钱包网络和配置密码。两项必须同时通过,否则支付后端拒绝启动并输出受控诊断日志。 启用后,用户输入密码时本地执行,未输入密码时仅允许交给已就绪的内网服务。两种方式共用执行记录和受控交易构造, 执行前实时校验余额、资源和链上费率。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. 验证监听地址、来源白名单、TLS 和服务认证后,再配置支付后端环境变量并部署前端。
  5. 首次在 NILE 验证。没有执行过真实交易的构建/隔离测试不能替代实际部署验收。

禁止把真实配置密码写在脚本、命令行参数、Git 文件或支付后端配置中。通过进程管理器的受控环境注入。

执行器环境变量

变量 含义
CHAIN_EXECUTOR_BIND_ADDRESS 必填,本机明确 IPv4;只接受 10/8、172.16/12、192.168/16 或 127/8
CHAIN_EXECUTOR_PORT 必填,独立监听端口,例如 9088
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 独立最小权限数据库账号及密码
CHAIN_EXECUTOR_TLS_KEYSTORE 非回环监听必填,PKCS12 证书库的绝对路径
CHAIN_EXECUTOR_TLS_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 无尾斜杠/路径的根地址,例如 https://192.168.10.20:9088
CHAIN_EXECUTOR_TOKEN 独立服务凭据,与执行器一致

仅回环地址允许 HTTP;跨机器强制 HTTPS。证书 SAN 必须包含配置的内网 IP,支付后端 JVM 需信任签发 CA。 使用 JVM trustStore 配置受信 CA,禁止关闭证书校验。只支持 IPv4 字面地址,不接受域名,避免 DNS 重绑定和意外公网解析。

仅内网访问

  • 服务拒绝 0.0.0.0、公网、域名、IPv6 和未配置白名单的启动方式。
  • 所有 HTTP 路径统一检查真实 TCP 对端 IP 和独立 Bearer 凭据;健康检查也不例外。
  • 不信任 X-Forwarded-For 或其他代理头。默认直接从支付后端调用,不经过反向代理。
  • 防火墙/安全组仅允许支付后端指定内网 IP 访问执行端口,其他来源全部拒绝。
  • 禁止配置公网 NAT、端口转发、公网反向代理和公网 Ingress;容器部署只发布到宿主机指定内网地址。
  • 前端只访问现有支付后端;执行器地址、凭据、密码、信封和签名交易不返回浏览器。

应用只能校验本机监听与实际来源,无法代替基础设施防火墙,也无法检测外部设备上的 NAT/公网转发规则。

协议与执行流程

  • 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 链上确认。