# 支付系统、资源租赁平台与链上执行器配置手册 本文按当前工作区代码说明三个独立运行单元的配置、依赖关系和部署方式: 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://:3306/?useUnicode=true&characterEncoding=utf8&connectionTimeZone=LOCAL&forceConnectionTimeZoneToSession=true username: password: redis: host: port: 6379 database: 0 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__TRX_PRICE_USDT` | 对应网络的 TRX/USDT 固定计价。 | | `RENT_ADDRESS_ONCHAIN__FEE_USDT` | 固定服务费。 | | `RENT_ADDRESS_ONCHAIN__PLATFORM_FEE_PERCENT` | 平台从服务费中的分成比例,0~100。 | | `RENT_ADDRESS_ONCHAIN__FEE_LIMIT_SUN` | 链上交易 fee limit,单位 SUN。 | `` 为 `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:///api/rental/payment/notify/`。 | | `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 `。执行器不信任 `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= USDT_EXCHANGE_RATE=1 PAYMENT_CHECKOUT_URL=https://pay.example.com/public/usdtPay TRON_OPERATION_RESOURCE_REDUNDANCY_PERCENT=20 TRON_GRID_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= 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= RENT_MASTER_KEY_VERSION=v1 RENT_CONFIRMATIONS=19 RENT_RPC_KEY= RENT_HISTORY_EMBEDDED_ENABLED=true RENT_HISTORY_NETWORKS=MAINNET RENT_NILE_DEPOSIT= RENT_MAINNET_DEPOSIT= ``` ### 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= CHAIN_EXECUTOR_CONFIGURATION_PASSWORD= CHAIN_EXECUTOR_ALLOWED_NETWORK=MAINNET CHAIN_EXECUTOR_BROADCAST_ENABLED=true CHAIN_EXECUTOR_DB_URL=jdbc:mysql://:3306/?useUnicode=true&characterEncoding=utf8&connectionTimeZone=LOCAL&forceConnectionTimeZoneToSession=true CHAIN_EXECUTOR_DB_USER= CHAIN_EXECUTOR_DB_PASSWORD= TRON_GRID_API_KEY= TRON_SCAN_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 ' \ http://127.0.0.1:9089/internal/v1/connectivity curl -v \ -H 'Authorization: Bearer ' \ 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 ' \ 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