diff --git a/docs/deployment-configuration-guide.md b/docs/deployment-configuration-guide.md new file mode 100644 index 0000000..2580c39 --- /dev/null +++ b/docs/deployment-configuration-guide.md @@ -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://: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