112 lines
8.5 KiB
Markdown
112 lines
8.5 KiB
Markdown
# 内网链上执行服务
|
||
|
||
## 功能与兼容边界
|
||
|
||
`usdt-chain-executor` 是独立 JDK 8 进程,复用当前钱包信封解密、HD 派生、TRON 网络选择和资源估算。
|
||
支持主钱包/子钱包 TRX 与 USDT 转账、Stake 2.0 质押/取消质押、代理/取消代理、取消全部待解冻、归集、代付。
|
||
创建钱包、扩充子账号、轮换配置密码仍走原有人工密码流程,不向执行器开放这些管理能力。
|
||
|
||
支付后端 `CHAIN_EXECUTOR_ENABLED` 默认 `false`,此时直接执行原密码代码,既不访问内网服务,也不依赖新增表。
|
||
启用后,用户输入密码时本地执行,未输入密码时仅允许交给已就绪的内网服务。两种方式共用执行记录和受控交易构造,
|
||
执行前实时校验余额、资源和链上费率。`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 链上确认。
|