# 内网链上执行服务 ## 功能与兼容边界 `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 链上确认。