Files
usdt/docs/deployment-configuration-guide.md
T
2026-11-07 06:50:14 -05:00

34 KiB
Raw Blame History

支付系统、资源租赁平台与链上执行器配置手册

本文按当前工作区代码说明三个独立运行单元的配置、依赖关系和部署方式:

  1. 支付系统:myEpusdt/ruoyi-admin,负责订单、钱包、归集、代付、资源预检和任务编排。
  2. 资源租赁平台服务端:支付系统中启用 rental profile 后提供的租赁业务服务,负责租赁账户、套餐、订单、节点交付、结算、充值和回调。
  3. 链上执行器: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 资源准备与防重复逻辑

人工密码执行时:

  1. 页面预检每个业务地址的能量和带宽缺口及费用。
  2. 管理员选择是否租赁并确认最大费用。
  3. 后端为业务创建唯一 usdt_resource_preparation。
  4. 每个准备单、每种资源最多创建一张租赁单;唯一键阻止重复购买。
  5. 平台调用成功后不立即执行转账。支付系统主动查询平台订单,并反复查询目标地址链上资源。
  6. 只有能量和带宽实际到账且满足当前重新估算值后,才允许输入钱包配置密码执行链上操作。

执行器自动执行时,同样先完成资源准备和链上到账确认,再创建/唤醒远程执行任务。平台响应“成功”不等于资源已到账。

资源租赁目前不依赖供应商向支付系统回调,因此无需为 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. 启动顺序

  1. 备份并初始化/升级数据库表。
  2. 配置 MySQL、Redis、TRON 网络和支付系统基础秘密。
  3. 若使用 INTERNAL,启动带 rental profile 的租赁平台,确认 RPC、历史采集、套餐、节点和应用凭据正常。
  4. 在 USDTmanage/usdtConfig 保存对应网络的 INTERNAL 或 DUIYA 配置。
  5. 首次将 USDT_RESOURCE_RENTAL_ENABLED=false、CHAIN_EXECUTOR_ENABLED=false 启动支付系统,完成基础页面和数据库检查。
  6. 启动链上执行器,确认日志显示配置校验、数据库/钱包就绪和 HTTP 监听成功。
  7. 若使用 Nginx,执行 nginx -t,reload 后验证 HTTPS。
  8. 配置并启用支付系统执行器客户端,在全局配置页面执行“立即检查”,确认检查时间和状态更新。
  9. 启用资源租赁,先在 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 执行器启动联通测试失败

按顺序检查:

  1. 支付系统 CHAIN_EXECUTOR_BASE_URL 协议是否与入口一致。
  2. HTTP 是否误写成 HTTPS,或 HTTPS 是否绕过了 Nginx 直接访问执行器 HTTP 端口。
  3. 支付系统真实来源 IP 是否在 Nginx和执行器对应白名单中。
  4. 两端 CHAIN_EXECUTOR_TOKEN 是否完全一致且无换行。
  5. readiness 还要求数据库网络配置匹配和钱包配置口令正确。
  6. 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 任务只重播同一签名交易。
  • 已配置日志保留、数据库备份和告警,但日志不包含任何秘密。