添加测试

This commit is contained in:
lu7213 committed 2026-11-07 06:50:14 -05:00
1 parent 68bb68b2b4
commit 72ad60cb60
3 files changed
+831 -2

No files matched your search

+703
View File
@@ -0,0 +1,703 @@
# 支付系统、资源租赁平台与链上执行器配置手册
本文按当前工作区代码说明三个独立运行单元的配置、依赖关系和部署方式:
1. **支付系统**:`myEpusdt/ruoyi-admin`,负责订单、钱包、归集、代付、资源预检和任务编排。
2. **资源租赁平台服务端**:支付系统中启用 `rental` profile 后提供的租赁业务服务,负责租赁账户、套餐、订单、节点交付、结算、充值和回调。
3. **链上执行器**:`myEpusdt/usdt-chain-executor`,部署在受控内网,持有钱包配置口令并执行远程链上任务。
支付系统还可对接两种资源供应商:
- `INTERNAL`:当前项目自己的资源租赁平台。
- `DUIYA`:第三方 DUIYA 资源订单接口。
> 本文所有密钥均使用 `<...>` 占位符。当前仓库部分配置文件存在看似真实的密码、Token、API Key 和云存储密钥默认值。生产部署前应将其移出版本库,通过环境变量或外部配置注入,并立即轮换所有曾进入版本库的凭据。
## 1. 总体架构与配置归属
```text
管理员浏览器 / 商户
|
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 升级生产库。
```text
基础支付表 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`:
```yaml
spring:
profiles:
active: prod
include: rental
```
数据库连接通常在对应 profile 的 Druid 配置中设置。至少配置 URL、用户名和密码:
```yaml
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 当前仅支持主网。资源订单流程使用:
```text
POST /query_price 查询价格
POST /buy_energy 购买能量
POST /buy_net 购买带宽
POST /query_result 查询订单结果
```
基础地址应以 DUIYA 实际颁发文档为准,例如 API v2 根地址。数量必须符合平台最小值和步长。DUIYA 费用以 TRX 计价,因此费用上限也按 TRX 填写。
### 4.4 INTERNAL 配置
INTERNAL 指向本项目租赁平台,支付系统调用:
```text
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` | 是 | 链上交易所需确认数,主网建议按业务风控确定。 |
生成主密钥示例:
```bash
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 直连
执行器:
```bash
CHAIN_EXECUTOR_BIND_ADDRESS=10.0.0.20
CHAIN_EXECUTOR_PORT=9089
CHAIN_EXECUTOR_ALLOWED_IPS=10.0.0.10
```
支付系统:
```bash
CHAIN_EXECUTOR_BASE_URL=http://10.0.0.20:9089
CHAIN_EXECUTOR_TLS_CERTIFICATE=
```
端口只允许支付系统 IP 访问,不能暴露公网。
### 8.2 Nginx HTTPS
执行器监听回环地址:
```bash
CHAIN_EXECUTOR_BIND_ADDRESS=127.0.0.1
CHAIN_EXECUTOR_PORT=9089
CHAIN_EXECUTOR_ALLOWED_IPS=127.0.0.1
```
Nginx 示例:
```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; }
}
```
支付系统:
```bash
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 支付系统
```bash
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 租赁平台
```bash
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 链上执行器
```bash
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
```bash
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
```bash
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 证书检查
```bash
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 数据库状态
```sql
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 任务只重播同一签名交易。
- [ ] 已配置日志保留、数据库备份和告警,但日志不包含任何秘密。