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

704 lines
34 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 支付系统、资源租赁平台与链上执行器配置手册
本文按当前工作区代码说明三个独立运行单元的配置、依赖关系和部署方式:
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 任务只重播同一签名交易。
- [ ] 已配置日志保留、数据库备份和告警,但日志不包含任何秘密。