34 KiB
支付系统、资源租赁平台与链上执行器配置手册
本文按当前工作区代码说明三个独立运行单元的配置、依赖关系和部署方式:
- 支付系统:
myEpusdt/ruoyi-admin,负责订单、钱包、归集、代付、资源预检和任务编排。 - 资源租赁平台服务端:支付系统中启用
rentalprofile 后提供的租赁业务服务,负责租赁账户、套餐、订单、节点交付、结算、充值和回调。 - 链上执行器:
myEpusdt/usdt-chain-executor,部署在受控内网,持有钱包配置口令并执行远程链上任务。
支付系统还可对接两种资源供应商:
INTERNAL:当前项目自己的资源租赁平台。DUIYA:第三方 DUIYA 资源订单接口。
本文所有密钥均使用
<...>占位符。当前仓库部分配置文件存在看似真实的密码、Token、API Key 和云存储密钥默认值。生产部署前应将其移出版本库,通过环境变量或外部配置注入,并立即轮换所有曾进入版本库的凭据。
1. 总体架构与配置归属
管理员浏览器 / 商户
|
v
支付系统(RuoYi) ----------------------> MySQL / Redis
| ^
| 资源报价、下单、查询 |
+----> DUIYA | 共享 usdt_chain_execution
| |
+----> INTERNAL 资源租赁平台 |
| |
| Bearer + IP 白名单 |
+----> Nginx HTTPS(可选) ----> 链上执行器 HTTP
|
v
TRON 网络
| 配置类别 | 配置位置 | 读取者 | 生效方式 |
|---|---|---|---|
| 支付系统、TRON、执行器客户端开关 | application.yml 对应环境变量 |
支付系统 | 重启支付系统 |
| 资源供应商连接信息 | usdt_resource_rental_config |
支付系统 | 后台新增配置后立即供新订单使用 |
| INTERNAL 租赁平台 | application-rental.yml 对应环境变量 |
启用 rental profile 的服务 |
重启服务 |
| 链上执行器数据库和链查询 | executor.properties 对应环境变量 |
链上执行器 | 重启执行器 |
| 链上执行器网络入口和钱包口令 | 进程环境变量 | 链上执行器 | 重启执行器 |
| Nginx TLS、来源限制 | Nginx 配置 | Nginx | nginx -t 后 reload |
不要将三个概念混为一谈:
RENT_MASTER_KEY是租赁平台数据库敏感凭据的根加密密钥。CHAIN_EXECUTOR_CONFIGURATION_PASSWORD是执行器解锁钱包配置的口令。CHAIN_EXECUTOR_TOKEN是支付系统调用执行器时使用的 Bearer 服务令牌。
2. 部署前准备
2.1 基础依赖
- JDK 8。
- MySQL,字符集使用
utf8mb4,时区与应用保持一致。 - Redis,供支付订单金额槽位、会话和相关任务使用。
- 可访问所选 TRON 网络的 RPC、TronGrid 和 TronScan 接口。
- 需要 HTTPS 时准备 Nginx 及证书。
- 支付系统和链上执行器必须能访问同一个业务数据库。
2.2 SQL 初始化顺序
先备份数据库,再按实际启用功能执行增量脚本。不要用 drop/recreate 升级生产库。
基础支付表 sql/payment_init.sql
资源租赁客户端 sql/resource_rental.sql
链上执行任务 sql/chain_executor.sql
租赁平台主体 sql/rent_init.sql
租赁充值 sql/payment_topup_upgrade.sql
sql/rent_topup_init.sql
租赁历史采集 sql/rent_history_init.sql
历史清理升级(已有库) sql/rent_history_cleanup_upgrade.sql
关键新增表用途:
| 表 | 用途 |
|---|---|
usdt_resource_rental_config |
资源供应商连接配置的版本表;API Key/Secret 以 AES-GCM 密文保存,新配置不覆盖旧订单引用的版本。 |
usdt_resource_preparation |
一次归集或代付的资源准备状态、预计资源、现有资源、授权和到账期限。 |
usdt_resource_rental_order |
能量/带宽租赁订单;preparation_id + resource_type 唯一,防止重复下单。 |
usdt_resource_address_guard |
同网络同地址的跨实例互斥,防止并发资源准备和执行。 |
usdt_chain_execution |
支付系统与执行器共享的链上任务状态、脱敏命令、交易哈希和受控签名交易。 |
rent_topup_order |
租赁平台用户通过支付系统充值的订单及支付通道快照。 |
rent_topup_notify |
已验签充值通知的幂等收件箱。 |
rent_webhook |
租赁订单业务事件的商户回调持久队列。 |
3. 支付系统基础配置
配置文件为 ruoyi-admin/src/main/resources/application.yml。生产环境建议使用外部 application-prod.yml 和环境变量,禁止把生产秘密写回仓库。
3.1 Spring profile、MySQL 与 Redis
spring.profiles.active 选择基础环境,例如 prod。若同一进程还承载租赁平台,应额外包含 rental:
spring:
profiles:
active: prod
include: rental
数据库连接通常在对应 profile 的 Druid 配置中设置。至少配置 URL、用户名和密码:
spring:
datasource:
druid:
master:
url: jdbc:mysql://<mysql-host>:3306/<database>?useUnicode=true&characterEncoding=utf8&connectionTimeZone=LOCAL&forceConnectionTimeZoneToSession=true
username: <database-user>
password: <database-password>
redis:
host: <redis-host>
port: 6379
database: 0
password: <redis-password>
支付数据库连接必须使用本地会话时区。历史 URL 中若有 serverTimezone=UTC,应改为项目约定的 connectionTimeZone=LOCAL&forceConnectionTimeZoneToSession=true。
3.2 支付业务参数
| 环境变量 | 是否必配 | 用途与要求 |
|---|---|---|
APP_PRIVATE_KEY_ENCRYPTION_KEY |
使用商户 RSA 私钥时必配 | 商户私钥的加密主密钥,至少 32 位;所有支付实例保持一致,不可直接轮换。 |
USDT_EXCHANGE_RATE |
建议显式配置 | 1 USDT 对应的业务货币金额;实际 USDT = 业务金额 / 汇率。使用十进制值,不使用浮点近似。 |
PAYMENT_CHECKOUT_URL |
对外创建订单时必配 | 公共收银台完整 URL,例如 https://pay.example.com/public/usdtPay。 |
TRON_OPERATION_RESOURCE_REDUNDANCY_PERCENT |
建议配置 | 链上资源估算冗余百分比,默认 20;过低易因链上变化导致资源不足。 |
同时应修改 RuoYi 自带的 token.secret,关闭生产 Swagger、演示功能和不需要的 Actuator 暴露端点。JWT 密钥必须使用高强度随机值。
3.3 TRON 链数据配置
| 环境变量 | 用途 |
|---|---|
TRON_GRID_API_KEY |
TronGrid API Key。 |
TRONSCAN_API_KEY |
TronScan 独立 API Key,不能用 TronGrid Key 代替。 |
TRON_MAINNET_TRANSACTION_ENDPOINTS |
主网交易查询端点,多个地址用英文逗号分隔。 |
TRON_MAINNET_ACCOUNT_ENDPOINTS |
主网账户查询端点。 |
TRON_NILE_TRANSACTION_ENDPOINTS |
Nile 交易查询端点。 |
TRON_NILE_ACCOUNT_ENDPOINTS |
Nile 账户查询端点。 |
TRON_SHASTA_TRANSACTION_ENDPOINTS |
Shasta 交易查询端点。 |
TRON_SHASTA_ACCOUNT_ENDPOINTS |
Shasta 账户查询端点。 |
生产建议配置至少两个可用查询端点并监控限流。网络由全局 USDT 配置决定,支付系统、租赁平台、执行器和钱包配置必须一致,禁止仅通过替换合约地址混用网络。
3.4 安全与通知可选项
| 环境变量 | 用途 |
|---|---|
TOTP_ENCRYPTION_KEY |
Base64 编码的 32 字节随机 AES 密钥;用于加密 Authenticator 凭据。所有实例一致,缺失时不能新建绑定。 |
TOTP_ISSUER |
Authenticator 中显示的发行方名称。 |
GOOGLE_OAUTH_ENABLED |
是否启用 Google OIDC。 |
GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET |
Google OAuth 客户端凭据。 |
GOOGLE_OAUTH_REDIRECT_URI |
后端 OAuth 回调地址。 |
GOOGLE_OAUTH_FRONTEND_RESULT_URL |
登录完成后的前端结果地址。 |
TELEGRAM_ENABLED |
是否启用 Telegram 审核/通知。 |
TELEGRAM_BOT_TOKEN |
Bot Token,禁止记录日志。 |
TELEGRAM_AUDIT_CHAT_ID |
审核群或会话 ID。 |
TELEGRAM_WEBHOOK_URL / TELEGRAM_WEBHOOK_SECRET |
Telegram Webhook 公网地址和校验 Secret。 |
TELEGRAM_ALLOWED_USER_IDS |
允许操作的 Telegram 用户 ID 列表。 |
TELEGRAM_PUSH_SCAN_INTERVAL_MS |
待推送扫描周期,默认 10000 ms。 |
4. 支付系统的资源租赁客户端
4.1 功能开关
| 环境变量 | 示例 | 说明 |
|---|---|---|
USDT_RESOURCE_RENTAL_ENABLED |
true |
总开关。启用前必须完成 SQL 和平台配置。 |
USDT_RESOURCE_RENTAL_PROVIDER |
INTERNAL |
当前使用的供应商,只能为 INTERNAL 或 DUIYA。 |
USDT_RESOURCE_ARRIVAL_TIMEOUT_SECONDS |
300 |
下单后等待链上资源到账的最长时间。 |
切换供应商只修改 USDT_RESOURCE_RENTAL_PROVIDER 并重启支付系统;数据库中必须已有对应网络、已启用的供应商配置。
4.2 后台配置
进入 USDTmanage/usdtConfig 的“资源租赁平台”区域。保存配置会向 usdt_resource_rental_config 插入新版本,不会覆盖旧行;API Key 和 Secret 只写入、不回显。
| 字段 | 说明 |
|---|---|
| 平台 | INTERNAL 或 DUIYA。 |
| 网络 | NILE 或 MAINNET;DUIYA 当前只允许 MAINNET。 |
| 基础地址 | 平台 API 根地址。INTERNAL 可填写服务根地址,代码会使用 /api/rental/v1;DUIYA 填资源 API v2 根地址。 |
| API Key / Secret | 平台颁发的 HMAC 凭据。编辑时留空表示沿用旧密文。 |
| 能量周期 / 带宽周期 | 供应商支持的产品周期,例如 1h、1day。必须与平台套餐一致。 |
| 租期秒数 | INTERNAL 订单租期,必须匹配可用套餐。 |
| 能量步长 | 数量向上取整步长,常见为 30000。 |
| 带宽步长 | 数量向上取整步长,常见为 100。 |
| 单订单费用上限 | 任一资源订单允许的最大报价。 |
| 单次执行费用上限 | 一次业务全部资源允许的总费用,必须大于等于单订单上限。 |
| 币种 | 由后端确定:INTERNAL 为 USDT,DUIYA 为 TRX。 |
费用上限是资金安全边界,不应设置为无限大。生产值应依据正常报价加合理波动空间,并通过告警处理异常报价。
4.3 DUIYA 配置
DUIYA 当前仅支持主网。资源订单流程使用:
POST /query_price 查询价格
POST /buy_energy 购买能量
POST /buy_net 购买带宽
POST /query_result 查询订单结果
基础地址应以 DUIYA 实际颁发文档为准,例如 API v2 根地址。数量必须符合平台最小值和步长。DUIYA 费用以 TRX 计价,因此费用上限也按 TRX 填写。
4.4 INTERNAL 配置
INTERNAL 指向本项目租赁平台,支付系统调用:
POST /api/rental/v1/quote
POST /api/rental/v1/create
POST /api/rental/v1/query
请求使用 X-Rent-* HMAC 请求头认证。配置的 API Key/Secret 必须来自租赁平台中启用的应用凭据,网络、租期、资源步长必须与租赁账号已分配套餐一致。费用以 USDT 计价。
4.5 资源准备与防重复逻辑
人工密码执行时:
- 页面预检每个业务地址的能量和带宽缺口及费用。
- 管理员选择是否租赁并确认最大费用。
- 后端为业务创建唯一
usdt_resource_preparation。 - 每个准备单、每种资源最多创建一张租赁单;唯一键阻止重复购买。
- 平台调用成功后不立即执行转账。支付系统主动查询平台订单,并反复查询目标地址链上资源。
- 只有能量和带宽实际到账且满足当前重新估算值后,才允许输入钱包配置密码执行链上操作。
执行器自动执行时,同样先完成资源准备和链上到账确认,再创建/唤醒远程执行任务。平台响应“成功”不等于资源已到账。
资源租赁目前不依赖供应商向支付系统回调,因此无需为 DUIYA 或 INTERNAL 配置资源订单回调地址。订单状态与资源到账均由支付系统主动确认。
5. INTERNAL 资源租赁平台服务端
租赁平台配置位于 application-rental.yml。只有 Spring profile 包含 rental 时才加载。以下都是进程启动配置,修改后需要重启。
5.1 核心配置
| 环境变量 | 必需 | 说明 |
|---|---|---|
RENT_ENABLED |
是 | 租赁平台总开关。 |
RENT_DOMAIN |
是 | 对外域名,用于平台生成和校验相关地址;填写域名,不要混入路径。 |
RENT_MASTER_KEY |
是 | Base64 编码的恰好 32 字节随机密钥,用 AES-256-GCM 加密租赁凭据。所有实例必须一致。 |
RENT_MASTER_KEY_VERSION |
是 | 密钥版本标识,例如 v1;轮换时用于识别密钥版本。 |
RENT_CONFIRMATIONS |
是 | 链上交易所需确认数,主网建议按业务风控确定。 |
生成主密钥示例:
openssl rand -base64 32
RENT_MASTER_KEY 不是租赁 API Secret、支付 API Secret 或钱包密码。丢失它会导致已有加密凭据无法解密;直接替换会使历史凭据不可用。轮换必须先实现旧版本解密、新版本加密和数据迁移,不能只改环境变量。
5.2 商户 Webhook
| 环境变量 | 说明 |
|---|---|
RENT_WEBHOOK_ALLOW_PRIVATE_NETWORK |
是否允许向 RFC1918/IPv6 ULA 内网地址发送回调。生产公网平台通常设为 false;内网联调才开启。 |
RENT_WEBHOOK_DEBUG_CREDENTIAL_SOURCE |
调试回调凭据来源:APP 使用应用当前有效凭据;CONFIGURED 使用下面独立凭据。 |
RENT_WEBHOOK_DEBUG_API_KEY / RENT_WEBHOOK_DEBUG_API_SECRET |
仅 CONFIGURED 调试模式使用。 |
RENT_WEBHOOK_DEBUG_SIGNATURE_PATH |
反向代理改写路径时,指定参与签名的外部路径。 |
租赁订单状态变化时,同一事务写入 rent_webhook。后台工作线程按 HMAC 规则向商户的回调 URL 推送;只有响应 HTTP 200 且正文严格等于小写 ok 才确认成功。超时、非 200、正文不匹配都会进入重试/失败处理。
不要把支付充值通知 /api/rental/payment/notify/{channel} 当成租赁订单商户 Webhook:前者是支付系统通知租赁平台,后者是租赁平台通知自己的商户。
5.3 派单与交付
| 环境变量 | 默认概念 | 说明 |
|---|---|---|
RENT_DELIVERY_WORKERS |
4 |
异步交付工作线程数。 |
RENT_DELIVERY_QUEUE_CAPACITY |
200 |
内存快速队列容量;持久化扫描仍负责补偿。 |
RENT_DELIVERY_DISPATCH_INTERVAL_MS |
3000 |
待派单持久化补偿扫描间隔。 |
RENT_DELIVERY_PUSH_INTERVAL_MS |
2000 |
节点推送/任务补偿间隔。 |
RENT_DELIVERY_VERIFICATION_GRACE_SECONDS |
180 |
租期结束后允许链上核验延迟的宽限,不延长用户实际租期。 |
线程数应结合节点数、数据库连接池和 RPC 限流调整,不宜只为降低延迟盲目增大。
5.4 RPC 与历史采集
| 环境变量 | 说明 |
|---|---|
RENT_NILE_RPC / RENT_MAINNET_RPC |
各网络 TRON RPC 根地址。 |
RENT_RPC_KEY |
RPC/TronGrid API Key。 |
RENT_HISTORY_EMBEDDED_ENABLED |
是否启用同进程 Java 历史采集器。 |
RENT_HISTORY_NETWORKS |
采集网络,建议先从 NILE 开始。 |
RENT_HISTORY_POLL_MS |
区块轮询间隔。 |
RENT_HISTORY_BATCH_SIZE |
单批处理区块/记录规模。 |
RENT_HISTORY_PARAMETER_GRACE_SECONDS |
链参数归档暂时落后时的等待时间。 |
RENT_HISTORY_MAX_SAMPLE_AGE_SECONDS |
参数样本最大允许年龄;过期时暂停新资源派单。 |
RENT_HISTORY_PROBE_ADDRESS |
用于链能力/资源数据探测的有效 TRON 地址。 |
RENT_NILE_HISTORY / RENT_MAINNET_HISTORY |
外部历史服务地址;启用内置采集时无需填写。 |
历史清理配置:
| 环境变量 | 说明 |
|---|---|
RENT_HISTORY_CLEANUP_ENABLED |
是否启用归档清理。 |
RENT_HISTORY_CLEANUP_CRON |
UTC 时区 Quartz cron。 |
RENT_HISTORY_RETENTION_DAYS |
在线历史保留天数。 |
RENT_HISTORY_CLEANUP_BATCH_SIZE |
每批清理数量。 |
RENT_HISTORY_CLEANUP_MAX_BATCHES |
单次任务最大批次数。 |
RENT_HISTORY_ARCHIVE_DIRECTORY |
持久、可写且支持原子移动的归档目录;归档文件不会自动删除。 |
5.5 入金、提现和地址上链
| 环境变量 | 说明 |
|---|---|
RENT_NILE_DEPOSIT / RENT_MAINNET_DEPOSIT |
租赁用户 USDT 入金地址,与供应节点钱包无关。 |
RENT_WITHDRAW_ENABLED |
是否开放提现申请。 |
RENT_WITHDRAW_MIN_USDT / RENT_WITHDRAW_MAX_USDT |
单笔提现上下限。 |
RENT_WITHDRAW_SCAN_ENABLED |
是否扫描管理员已广播的提现交易。系统自身不自动广播提现。 |
RENT_WITHDRAW_POLL_MS |
提现链上扫描周期。 |
RENT_WITHDRAW_SCAN_BATCH_BLOCKS |
单批扫描区块数。 |
RENT_WITHDRAW_TELEGRAM_REVIEWERS |
Telegram用户ID:后台用户ID,多项逗号分隔。 |
RENT_WITHDRAW_NILE_PAYOUT_ADDRESSES / RENT_WITHDRAW_MAINNET_PAYOUT_ADDRESSES |
各网络允许的出款地址白名单。 |
地址上链功能固定转出 1 TRX,并从用户 USDT 账户冻结本金折价与服务费:
| 环境变量 | 说明 |
|---|---|
RENT_ADDRESS_ONCHAIN_ENABLED |
总开关,默认应关闭。 |
RENT_ADDRESS_ONCHAIN_<NETWORK>_TRX_PRICE_USDT |
对应网络的 TRX/USDT 固定计价。 |
RENT_ADDRESS_ONCHAIN_<NETWORK>_FEE_USDT |
固定服务费。 |
RENT_ADDRESS_ONCHAIN_<NETWORK>_PLATFORM_FEE_PERCENT |
平台从服务费中的分成比例,0~100。 |
RENT_ADDRESS_ONCHAIN_<NETWORK>_FEE_LIMIT_SUN |
链上交易 fee limit,单位 SUN。 |
<NETWORK> 为 NILE 或 MAINNET。价格必须逐网络显式设置,不跨网络兜底。
6. 租赁平台通过支付系统充值
这一组 RENT_PAYMENT_* 是“租赁平台用户向余额充值”的支付通道,不是支付系统购买能量/带宽的资源供应商配置。
6.1 全局参数
| 环境变量 | 说明 |
|---|---|
RENT_PAYMENT_ENABLED |
充值支付总开关。 |
RENT_PAYMENT_CONNECT_TIMEOUT_MS |
连接支付系统超时。 |
RENT_PAYMENT_READ_TIMEOUT_MS |
支付接口读取超时。 |
RENT_PAYMENT_RECONCILE_MS |
主动查询充值订单的补偿周期。 |
6.2 每网络通道
Nile 使用 RENT_PAYMENT_NILE_*,主网使用 RENT_PAYMENT_MAINNET_*:
| 后缀 | 说明 |
|---|---|
ENABLED |
是否启用该网络充值。 |
BASE_URL |
支付系统开放 API 根地址。 |
API_KEY / API_SECRET |
支付应用凭据,用于创建/查询订单及签名。 |
PUBLIC_KEY |
支付应用的 RSA 公钥文件位置,用于验证支付通知签名。 |
TLS_CERTIFICATE |
HTTPS 服务器证书或 CA 证书位置,仅用于 Java TLS 信任。 |
NOTIFY_URL |
支付系统回调地址,必须为 https://<rent-domain>/api/rental/payment/notify/<channel>。 |
MIN_AMOUNT / MAX_AMOUNT |
单笔充值金额范围。 |
RSA 公钥与 TLS 证书用途不同:RSA 公钥验证业务通知签名;TLS 证书建立 HTTPS 信任。即使两者来自同一域名也不能互相替代。
支付通知请求必须携带 X-Payment-Api-Key 和 X-Payment-Rsa-Signature。租赁平台验签、幂等入库后返回纯文本 ok;无效通知返回 400。
7. 链上执行器
7.1 作用与安全边界
执行器不接收任意交易参数、私钥或 HTTP 口令。支付系统先把脱敏命令写入 usdt_chain_execution,再通过 HTTP 发送空正文唤醒请求。执行器从共享数据库读取任务,使用仅存在于执行器进程中的配置口令解锁钱包并执行。
HTTP 接口:
| 方法与路径 | 用途 | 成功响应 |
|---|---|---|
GET /internal/v1/connectivity |
验证网络、IP 白名单和 Bearer Token。 | CONNECTED |
GET /internal/v1/readiness |
额外验证数据库网络配置和钱包配置口令。 | READY |
POST /internal/v1/executions |
空正文唤醒任务扫描。 | HTTP 202 ACCEPTED |
所有路径都要求真实 TCP 来源 IP 在白名单中并携带 Authorization: Bearer <token>。执行器不信任 X-Forwarded-For。
7.2 执行器进程配置
| 环境变量 | 必需 | 说明 |
|---|---|---|
CHAIN_EXECUTOR_BIND_ADDRESS |
是 | 执行器 HTTP 监听地址,必须属于本机。直连可填内网 IP;Nginx 同机代理建议 127.0.0.1。 |
CHAIN_EXECUTOR_PORT |
是 | HTTP 端口,例如 9089。 |
CHAIN_EXECUTOR_ALLOWED_IPS |
是 | 允许的实际 TCP 来源 IP,逗号分隔。经过同机 Nginx 时通常包含 127.0.0.1。 |
CHAIN_EXECUTOR_TOKEN |
是 | 至少 32 位随机 Bearer Token,必须与支付系统一致。 |
CHAIN_EXECUTOR_CONFIGURATION_PASSWORD |
是 | 主钱包配置文件口令,只允许存在执行器环境中,禁止写入支付系统和日志。 |
CHAIN_EXECUTOR_ALLOWED_NETWORK |
是 | NILE 或 MAINNET,必须与数据库全局配置一致。 |
CHAIN_EXECUTOR_BROADCAST_ENABLED |
是 | 必须明确为小写 true,否则拒绝启动。 |
CHAIN_EXECUTOR_DB_URL |
是 | 与支付系统共享的 MySQL JDBC URL。 |
CHAIN_EXECUTOR_DB_USER / CHAIN_EXECUTOR_DB_PASSWORD |
是 | 建议使用最小权限专用数据库账号。 |
TRON_GRID_API_KEY |
是 | 执行器链查询/交易所需 TronGrid Key。 |
TRON_SCAN_API_KEY |
按实现需要 | 执行器使用的 TronScan Key;注意此处变量名为 TRON_SCAN_API_KEY。 |
支付系统使用 TRONSCAN_API_KEY,执行器使用 TRON_SCAN_API_KEY,两个变量名当前并不相同。
7.3 支付系统的执行器客户端配置
| 环境变量 | 说明 |
|---|---|
CHAIN_EXECUTOR_ENABLED |
是否启用远程执行通道。建议首次部署先设为 false,服务验证后由管理员启用。 |
CHAIN_EXECUTOR_BASE_URL |
执行器根地址,例如直连 http://10.0.0.20:9089 或 Nginx https://executor.internal:9088。不要带 /internal/v1。 |
CHAIN_EXECUTOR_TOKEN |
与执行器完全一致的 Bearer Token。 |
CHAIN_EXECUTOR_TLS_CERTIFICATE |
HTTPS 私有/自签证书或 CA 的位置,仅支持 file:/... 或 classpath:...。HTTP 模式留空。 |
CHAIN_EXECUTOR_HEALTH_CHECK_INTERVAL_MS |
周期性健康检查间隔。 |
CHAIN_EXECUTOR_HEALTH_FAILURE_THRESHOLD |
连续失败达到此阈值后自动停用执行器。 |
代码还支持属性 chain.executor.health-check-initial-delay-ms,用于设置启动后首次周期检查延迟;当前 YAML 未提供同名环境变量占位,可在外部 YAML 中显式配置。
支付系统启动时会进行执行器验证。连续健康检查失败后,远程执行自动停用,只能回退到页面密码执行;执行器恢复上线后不会自动重新启用,需要管理员在 USDTmanage/usdtConfig 中立即检查并重新启用,避免故障抖动自动恢复广播能力。
7.4 任务状态与重启恢复
| 状态/模式 | 处理规则 |
|---|---|
QUEUED + REMOTE |
执行器扫描并领取。 |
未签名的 RUNNING + REMOTE |
执行器启动时将确认可安全重试的记录恢复为 QUEUED,并重新校验有效期、余额和资源。 |
仍有签名或结果歧义的 RUNNING |
不自动重领,启动日志列出,需结合交易哈希和链上结果人工核验。 |
SIGNED |
只重播数据库中同一笔签名交易,禁止重新构造。 |
PASSWORD |
依赖管理员页面口令流程,不由远程执行器自动恢复。 |
8. HTTP 与 Nginx HTTPS
执行器自身只提供 HTTP,不加载 PKCS12/JKS。直接 HTTP 适用于严格隔离的受控内网;需要链路加密时由 Nginx 终止 TLS。
8.1 HTTP 直连
执行器:
CHAIN_EXECUTOR_BIND_ADDRESS=10.0.0.20
CHAIN_EXECUTOR_PORT=9089
CHAIN_EXECUTOR_ALLOWED_IPS=10.0.0.10
支付系统:
CHAIN_EXECUTOR_BASE_URL=http://10.0.0.20:9089
CHAIN_EXECUTOR_TLS_CERTIFICATE=
端口只允许支付系统 IP 访问,不能暴露公网。
8.2 Nginx HTTPS
执行器监听回环地址:
CHAIN_EXECUTOR_BIND_ADDRESS=127.0.0.1
CHAIN_EXECUTOR_PORT=9089
CHAIN_EXECUTOR_ALLOWED_IPS=127.0.0.1
Nginx 示例:
server {
listen 10.0.0.20:9088 ssl;
server_name executor.internal;
ssl_certificate /etc/nginx/certs/executor-cert.pem;
ssl_certificate_key /etc/nginx/certs/executor-private.key;
ssl_protocols TLSv1.2 TLSv1.3;
allow 10.0.0.10; # 支付系统 IP
deny all;
location /internal/v1/ {
proxy_pass http://127.0.0.1:9089;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Authorization $http_authorization;
proxy_set_header Host $host;
proxy_connect_timeout 2s;
proxy_read_timeout 5s;
proxy_send_timeout 5s;
proxy_buffering off;
}
location / { return 404; }
}
支付系统:
CHAIN_EXECUTOR_BASE_URL=https://executor.internal:9088
CHAIN_EXECUTOR_TLS_CERTIFICATE=file:/etc/ruoyi/certs/executor-cert.pem
证书必须在有效期内,并包含与 URL 主机匹配的 SAN。只有 CN、没有 SAN 的自签证书在现代 TLS 主机名校验中可能失败。使用 IP URL 时证书需包含 IP SAN;推荐使用内网 DNS 名和对应 DNS SAN。
9. 推荐环境变量模板
模板仅展示核心关系,不应提交填好秘密的文件到版本库。
9.1 支付系统
APP_PRIVATE_KEY_ENCRYPTION_KEY=<at-least-32-char-random-secret>
USDT_EXCHANGE_RATE=1
PAYMENT_CHECKOUT_URL=https://pay.example.com/public/usdtPay
TRON_OPERATION_RESOURCE_REDUNDANCY_PERCENT=20
TRON_GRID_API_KEY=<trongrid-api-key>
TRONSCAN_API_KEY=<tronscan-api-key>
USDT_RESOURCE_RENTAL_ENABLED=true
USDT_RESOURCE_RENTAL_PROVIDER=INTERNAL
USDT_RESOURCE_ARRIVAL_TIMEOUT_SECONDS=300
CHAIN_EXECUTOR_ENABLED=true
CHAIN_EXECUTOR_BASE_URL=https://executor.internal:9088
CHAIN_EXECUTOR_TOKEN=<same-random-token-as-executor>
CHAIN_EXECUTOR_TLS_CERTIFICATE=file:/etc/ruoyi/certs/executor-ca-or-cert.pem
CHAIN_EXECUTOR_HEALTH_CHECK_INTERVAL_MS=10000
CHAIN_EXECUTOR_HEALTH_FAILURE_THRESHOLD=3
9.2 INTERNAL 租赁平台
RENT_ENABLED=true
RENT_DOMAIN=rent.example.com
RENT_MASTER_KEY=<base64-of-exactly-32-random-bytes>
RENT_MASTER_KEY_VERSION=v1
RENT_CONFIRMATIONS=19
RENT_RPC_KEY=<trongrid-api-key>
RENT_HISTORY_EMBEDDED_ENABLED=true
RENT_HISTORY_NETWORKS=MAINNET
RENT_NILE_DEPOSIT=<nile-tron-address>
RENT_MAINNET_DEPOSIT=<mainnet-tron-address>
9.3 链上执行器
CHAIN_EXECUTOR_BIND_ADDRESS=127.0.0.1
CHAIN_EXECUTOR_PORT=9089
CHAIN_EXECUTOR_ALLOWED_IPS=127.0.0.1
CHAIN_EXECUTOR_TOKEN=<same-random-token-as-payment>
CHAIN_EXECUTOR_CONFIGURATION_PASSWORD=<wallet-configuration-password>
CHAIN_EXECUTOR_ALLOWED_NETWORK=MAINNET
CHAIN_EXECUTOR_BROADCAST_ENABLED=true
CHAIN_EXECUTOR_DB_URL=jdbc:mysql://<db-host>:3306/<db>?useUnicode=true&characterEncoding=utf8&connectionTimeZone=LOCAL&forceConnectionTimeZoneToSession=true
CHAIN_EXECUTOR_DB_USER=<executor-db-user>
CHAIN_EXECUTOR_DB_PASSWORD=<executor-db-password>
TRON_GRID_API_KEY=<trongrid-api-key>
TRON_SCAN_API_KEY=<tronscan-api-key>
10. 启动顺序
- 备份并初始化/升级数据库表。
- 配置 MySQL、Redis、TRON 网络和支付系统基础秘密。
- 若使用 INTERNAL,启动带
rentalprofile 的租赁平台,确认 RPC、历史采集、套餐、节点和应用凭据正常。 - 在
USDTmanage/usdtConfig保存对应网络的 INTERNAL 或 DUIYA 配置。 - 首次将
USDT_RESOURCE_RENTAL_ENABLED=false、CHAIN_EXECUTOR_ENABLED=false启动支付系统,完成基础页面和数据库检查。 - 启动链上执行器,确认日志显示配置校验、数据库/钱包就绪和 HTTP 监听成功。
- 若使用 Nginx,执行
nginx -t,reload 后验证 HTTPS。 - 配置并启用支付系统执行器客户端,在全局配置页面执行“立即检查”,确认检查时间和状态更新。
- 启用资源租赁,先在 Nile 或小额主网业务完成报价、下单、链上到账、签名、广播全流程验证。
11. 验证命令
11.1 执行器直连 HTTP
curl -v \
-H 'Authorization: Bearer <executor-token>' \
http://127.0.0.1:9089/internal/v1/connectivity
curl -v \
-H 'Authorization: Bearer <executor-token>' \
http://127.0.0.1:9089/internal/v1/readiness
11.2 Nginx HTTPS
curl -v \
--cacert /etc/ruoyi/certs/executor-cert.pem \
-H 'Authorization: Bearer <executor-token>' \
https://executor.internal:9088/internal/v1/readiness
只在诊断 TLS 握手时临时使用 curl -k,不要把跳过证书校验作为生产配置。
11.3 证书检查
openssl x509 -in /etc/nginx/certs/executor-cert.pem \
-noout -subject -issuer -dates -fingerprint -sha256 -ext subjectAltName
openssl s_client -connect executor.internal:9088 \
-servername executor.internal </dev/null
11.4 数据库状态
SELECT provider_code, network, base_url, currency, enabled, created_at
FROM usdt_resource_rental_config
ORDER BY id DESC;
SELECT id, business_key, stage, required_energy, required_bandwidth,
available_energy, available_bandwidth, deadline_at, error_message
FROM usdt_resource_preparation
ORDER BY created_at DESC
LIMIT 20;
SELECT execution_id, business_key, execution_mode, status,
transaction_id, error_message, updated_at
FROM usdt_chain_execution
ORDER BY created_at DESC
LIMIT 20;
不要查询或导出 api_key_cipher、api_secret_cipher、signed_transaction、钱包私钥等敏感列用于普通排查。
12. 常见故障
12.1 GET /api/system/chain-resources/config 提示方法不支持
后端实际控制器路径是 GET /system/chain-resources/config。前端通常通过 /api 或 /dev-api 代理前缀转发,需检查代理是否将前缀正确移除。若请求命中旧实例,也会出现 GET 不支持,应确认部署包和实例版本一致。
12.2 执行器启动联通测试失败
按顺序检查:
- 支付系统
CHAIN_EXECUTOR_BASE_URL协议是否与入口一致。 - HTTP 是否误写成 HTTPS,或 HTTPS 是否绕过了 Nginx 直接访问执行器 HTTP 端口。
- 支付系统真实来源 IP 是否在 Nginx和执行器对应白名单中。
- 两端
CHAIN_EXECUTOR_TOKEN是否完全一致且无换行。 readiness还要求数据库网络配置匹配和钱包配置口令正确。- HTTPS 私有证书是否通过
CHAIN_EXECUTOR_TLS_CERTIFICATE加载,SAN 是否匹配 URL。
12.3 浏览器显示 ERR_EMPTY_RESPONSE
常见原因是对纯 HTTP 执行器端口发起 HTTPS 握手。执行器不支持 TLS:使用 http://...:9089,或访问 Nginx 的 https://...:9088。浏览器无法方便地附带 Bearer Token,也不是合适的验收工具,应使用 curl。
12.4 TLS证书加载失败
- 路径必须为支付系统 JVM 可读的
file:/absolute/path.pem或有效classpath:资源。 - 文件应为 PEM X.509 证书/CA,而不是只有私钥、PKCS12 中的错误条目或 Nginx 配置文本。
- 检查文件权限、有效期和完整证书链。
- 证书 SAN 必须匹配
CHAIN_EXECUTOR_BASE_URL的主机名或 IP。
12.5 资源订单成功但迟迟不执行
平台订单成功并不代表资源已到账。检查:
usdt_resource_rental_order的供应商状态和错误信息。usdt_resource_preparation的required_*与available_*。- 目标地址是否正确、网络是否一致。
USDT_RESOURCE_ARRIVAL_TIMEOUT_SECONDS是否足够。- RPC 是否返回最新账户资源,是否被限流或缓存。
不要手工重复下单。唯一键和未知状态保护用于避免同一资源重复购买;应先查询供应商和链上结果,再决定人工处理。
12.6 执行任务停在 RUNNING
先查 transaction_id 和是否存在签名交易:
- 无签名、无交易哈希且为远程任务:重启执行器会尝试安全恢复。
- 已签名:只能重播同一签名交易,不能重新构造。
- 有交易哈希:先查链上结果,再做业务对账。
- 日志显示
VALIDATE_BUSINESS:业务状态、金额、地址或任务有效期已变化,应检查业务表,不是简单网络故障。
12.7 Protobuf 与 TRON Trident 不兼容
出现 NoSuchMethodError: com.google.protobuf.Any.pack(...) 表示运行时装载了不兼容的 protobuf-javalite 或旧版 protobuf-java。应在最终构建依赖中只保留与当前 TRON Trident 兼容的 protobuf 版本,检查 fat jar/lib 目录是否残留旧 jar,清理后重新完整构建和部署。
13. 安全、备份与轮换
- 数据库、Redis、API Secret、Bearer Token、钱包密码、RSA 私钥、TOTP 密钥和
RENT_MASTER_KEY不得写日志、HTTP 响应或前端状态。 - 配置文件中已经出现过的秘密应视为泄露并轮换,包括数据库/Redis 密码、TRON API Key、执行器 Token 和云服务密钥。
RENT_MASTER_KEY、APP_PRIVATE_KEY_ENCRYPTION_KEY、TOTP_ENCRYPTION_KEY轮换前必须先设计版本化解密和数据迁移,不能直接替换。CHAIN_EXECUTOR_TOKEN可在维护窗口双端同步替换并重启;替换期间先停用远程执行。CHAIN_EXECUTOR_CONFIGURATION_PASSWORD轮换后执行器 readiness 会立即失败,必须同步更新钱包配置并验证。- 对数据库和租赁历史归档目录做加密备份,并定期验证恢复。
- Nginx 和防火墙只开放必需来源;执行器端口绝不能暴露公网。
- 上线主网前在 Nile 完成端到端演练,并使用小额主网交易验证资源估算、到账确认、广播和业务对账。
14. 上线检查清单
- 已轮换所有曾进入版本库的真实凭据。
- 基础支付表和所启用功能的增量 SQL 已执行并备份。
- 支付系统、租赁平台、执行器使用相同网络。
RENT_MASTER_KEY是 Base64 编码的 32 字节随机值并已离线备份。- 资源平台配置已在后台保存,网络、周期、步长和费用上限正确。
- 执行器 Token 两端一致,钱包配置口令只存在执行器。
- HTTP 端口受防火墙限制,或 Nginx TLS 证书 SAN 与 URL 匹配。
- connectivity、readiness、立即检查均通过且页面显示正确检查时间。
- 已验证资源下单后由系统独立确认链上到账,不依赖平台成功响应。
- 已验证重复点击、超时和服务重启不会重复租赁。
- 已验证 SIGNED 任务只重播同一签名交易。
- 已配置日志保留、数据库备份和告警,但日志不包含任何秘密。