11 KiB
内网链上执行服务
功能与兼容边界
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 保留量。
页面仍要求明确确认广播;服务上线不会触发历史业务自动广播。
部署顺序
- 备份并执行
sql/chain_executor.sql,只新增执行记录表,不重建原表。 - 使用 JDK 8 构建:
mvn -pl usdt-chain-executor -am package -DskipTests。 - 给独立执行器配置下表环境变量,再启动
java -jar usdt-chain-executor/target/usdt-chain-executor-3.4.0.jar。 - 验证监听地址、来源白名单和服务认证;HTTPS 部署还需验证 Nginx 与证书,再配置支付后端。
- 首次在 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 |
独立服务凭据,与执行器一致 |
CHAIN_EXECUTOR_TLS_CERTIFICATE |
HTTPS时可配置 file:/.../rent-cert.pem 或 classpath: 证书/CA;HTTP忽略 |
CHAIN_EXECUTOR_HEALTH_CHECK_INTERVAL_MS |
后端健康检查周期,默认 10000 毫秒 |
CHAIN_EXECUTOR_HEALTH_FAILURE_THRESHOLD |
连续失败自动停用阈值,默认 3 次 |
执行器自身只提供 HTTP。支付后端可使用 HTTP 直连,或使用 HTTPS 调用同机 Nginx,由 Nginx 转发到回环 HTTP。
生产跨机器调用推荐 HTTPS;证书 SAN 必须包含配置的内网 IP,支付后端 JVM 需信任签发 CA,禁止关闭证书校验。
HTTPS使用自签或内部CA时,建议设置 CHAIN_EXECUTOR_TLS_CERTIFICATE=file:/etc/nginx/certs/rent-cert.pem。
支付系统通过独立Java TLS上下文追加该证书,并保留JVM默认证书和主机名校验,不需要配置全局 trustStore。
只支持 IPv4 字面地址,不接受域名,避免 DNS 重绑定和意外公网解析。Nginx 示例见
usdt-chain-executor/nginx/usdt-chain-executor.conf。
后端定期检查执行器联通和业务就绪状态。管理员运行开关保存在 sys_config 的
chain.executor.runtime.enabled:连续失败达到阈值后自动写为 false,新链上操作只能使用配置密码。
服务恢复后只更新可达状态,不会自动打开运行开关;管理员需在全局配置页确认并重新启用。
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 链上确认。