接入租赁平台
This commit is contained in:
1 parent
c035263bc6
commit
1c2d15b2a9
51 files changed
+3631
-15
No files matched your search
@@ -0,0 +1,111 @@
|
||||
# 内网链上执行服务
|
||||
|
||||
## 功能与兼容边界
|
||||
|
||||
`usdt-chain-executor` 是独立 JDK 8 进程,复用当前钱包信封解密、HD 派生、TRON 网络选择和资源估算。
|
||||
支持主钱包/子钱包 TRX 与 USDT 转账、Stake 2.0 质押/取消质押、代理/取消代理、取消全部待解冻、归集、代付。
|
||||
创建钱包、扩充子账号、轮换配置密码仍走原有人工密码流程,不向执行器开放这些管理能力。
|
||||
|
||||
支付后端 `CHAIN_EXECUTOR_ENABLED` 默认 `false`,此时直接执行原密码代码,既不访问内网服务,也不依赖新增表。
|
||||
启用后,用户输入密码时本地执行,未输入密码时仅允许交给已就绪的内网服务。两种方式共用执行记录和受控交易构造,
|
||||
执行前实时校验余额、资源和链上费率。`RESOURCE_ONLY` 缺口拒绝;`DIRECT` 检查燃烧预算及全局 `trx_num` 保留量。
|
||||
页面仍要求明确确认广播;服务上线不会触发历史业务自动广播。
|
||||
|
||||
## 部署顺序
|
||||
|
||||
1. 备份并执行 `sql/chain_executor.sql`,只新增执行记录表,不重建原表。
|
||||
2. 使用 JDK 8 构建:`mvn -pl usdt-chain-executor -am package -DskipTests`。
|
||||
3. 给独立执行器配置下表环境变量,再启动 `java -jar usdt-chain-executor/target/usdt-chain-executor-3.4.0.jar`。
|
||||
4. 验证监听地址、来源白名单、TLS 和服务认证后,再配置支付后端环境变量并部署前端。
|
||||
5. 首次在 NILE 验证。没有执行过真实交易的构建/隔离测试不能替代实际部署验收。
|
||||
|
||||
禁止把真实配置密码写在脚本、命令行参数、Git 文件或支付后端配置中。通过进程管理器的受控环境注入。
|
||||
|
||||
### 执行器环境变量
|
||||
|
||||
| 变量 | 含义 |
|
||||
| --- | --- |
|
||||
| `CHAIN_EXECUTOR_BIND_ADDRESS` | 必填,本机明确 IPv4;只接受 `10/8`、`172.16/12`、`192.168/16` 或 `127/8` |
|
||||
| `CHAIN_EXECUTOR_PORT` | 必填,独立监听端口,例如 `9088` |
|
||||
| `CHAIN_EXECUTOR_ALLOWED_IPS` | 必填,支付后端实际 TCP 来源 IPv4,逗号分隔,逐个精确匹配;不支持通配/CIDR |
|
||||
| `CHAIN_EXECUTOR_TOKEN` | 必填,至少 32 位的独立随机服务凭据;与后端配置相同,不是钱包密码 |
|
||||
| `CHAIN_EXECUTOR_CONFIGURATION_PASSWORD` | 必填,当前全局钱包配置密码,仅在执行器进程内存中使用 |
|
||||
| `CHAIN_EXECUTOR_ALLOWED_NETWORK` | 必填,`NILE` 或 `MAINNET`;与数据库全局配置不同则未就绪 |
|
||||
| `CHAIN_EXECUTOR_BROADCAST_ENABLED` | 必填,只有明确为 `true` 才启动 |
|
||||
| `CHAIN_EXECUTOR_DB_URL` | 与支付后端相同数据库;使用 `connectionTimeZone=LOCAL&forceConnectionTimeZoneToSession=true` |
|
||||
| `CHAIN_EXECUTOR_DB_USER` / `CHAIN_EXECUTOR_DB_PASSWORD` | 独立最小权限数据库账号及密码 |
|
||||
| `CHAIN_EXECUTOR_TLS_KEYSTORE` | 非回环监听必填,PKCS12 证书库的绝对路径 |
|
||||
| `CHAIN_EXECUTOR_TLS_PASSWORD` | 证书库密码 |
|
||||
| `TRON_GRID_API_KEY` / `TRON_SCAN_API_KEY` | 按实际节点配置,沿用共享 TRON 客户端 |
|
||||
|
||||
独立执行器数据库权限:`usdt_config`、`wallet_address`、`usdt_payout_order`、
|
||||
`usdt_aggregation_task`、`usdt_aggregation_task_item` 只需 SELECT;`usdt_chain_execution` 需 SELECT/UPDATE。
|
||||
执行器不需要创建表、删除表、写业务状态或修改商户余额的权限。
|
||||
|
||||
### 支付后端环境变量
|
||||
|
||||
| 变量 | 含义 |
|
||||
| --- | --- |
|
||||
| `CHAIN_EXECUTOR_ENABLED` | 启用双通道时设 `true` |
|
||||
| `CHAIN_EXECUTOR_BASE_URL` | 无尾斜杠/路径的根地址,例如 `https://192.168.10.20:9088` |
|
||||
| `CHAIN_EXECUTOR_TOKEN` | 独立服务凭据,与执行器一致 |
|
||||
|
||||
仅回环地址允许 HTTP;跨机器强制 HTTPS。证书 SAN 必须包含配置的内网 IP,支付后端 JVM 需信任签发 CA。
|
||||
使用 JVM trustStore 配置受信 CA,禁止关闭证书校验。只支持 IPv4 字面地址,不接受域名,避免 DNS 重绑定和意外公网解析。
|
||||
|
||||
## 仅内网访问
|
||||
|
||||
- 服务拒绝 `0.0.0.0`、公网、域名、IPv6 和未配置白名单的启动方式。
|
||||
- 所有 HTTP 路径统一检查真实 TCP 对端 IP 和独立 Bearer 凭据;健康检查也不例外。
|
||||
- 不信任 `X-Forwarded-For` 或其他代理头。默认直接从支付后端调用,不经过反向代理。
|
||||
- 防火墙/安全组仅允许支付后端指定内网 IP 访问执行端口,其他来源全部拒绝。
|
||||
- 禁止配置公网 NAT、端口转发、公网反向代理和公网 Ingress;容器部署只发布到宿主机指定内网地址。
|
||||
- 前端只访问现有支付后端;执行器地址、凭据、密码、信封和签名交易不返回浏览器。
|
||||
|
||||
应用只能校验本机监听与实际来源,无法代替基础设施防火墙,也无法检测外部设备上的 NAT/公网转发规则。
|
||||
|
||||
## 协议与执行流程
|
||||
|
||||
- `GET /internal/v1/readiness`:鉴权后验证当前配置密码和网络,成功返回纯文本 `READY`,未就绪返回 503。
|
||||
- `POST /internal/v1/executions`:鉴权后接收空正文通知,返回 202;只唤醒数据库扫描,不接收任意交易参数。
|
||||
- `GET /system/chainExecutor/status`:现有后端登录鉴权入口,返回可用性和当前操作人最近 5 条公开执行记录。
|
||||
|
||||
业务指令先写数据库,通知只是加速信号;通知丢失时每 2 秒补扫。队列指令 10 分钟内未开始则拒绝执行。
|
||||
就绪校验会解密信封但不签名;实际执行再次核对信封版本、网络、钱包启用状态、地址与索引、代付/归集业务状态及金额。
|
||||
私钥仍由 `WalletSigningService` 在内存中派生,派生地址不匹配时拒绝。
|
||||
|
||||
| 状态 | 语义与恢复 |
|
||||
| --- | --- |
|
||||
| `QUEUED` | 持久化待执行;REMOTE 可以补扫;PASSWORD 不会在无人输入密码时自动解锁 |
|
||||
| `RUNNING` | 已原子领取,正在校验/签名;不凭超时自动释放,防止多进程同时签名 |
|
||||
| `SIGNED` | 签名交易与哈希已落库,广播前的持久化屏障;只查询或重播原字节,不重新构造 |
|
||||
| `BROADCASTED` | 节点确认接收或按哈希查到原交易;不等同于链上执行成功 |
|
||||
| `FAILED` | 明确在签名前失败,可以重新输入密码或重试远程执行;旧记录归档保留 |
|
||||
| `CHAIN_FAILED` | 原代付链上确认任务已确认原哈希执行失败,允许下一次人工尝试;保留旧交易审计 |
|
||||
|
||||
广播包含首次最多尝试 4 次,使用同一笔签名交易。`SIGNED` 后响应丢失或数据库断连不改为可重新广播的失败。
|
||||
恢复任务查原哈希或重播同一交易,不能因交易过期/未查到就自动创建新交易。
|
||||
|
||||
代付保留状态 6 直到结果明确;后端每 5 秒同步为已广播,再由原链上确认和账务结算完成。
|
||||
归集明细保留状态 4,逐明细同步交易哈希与幂等支出流水;全部明细结束后同步主任务。
|
||||
执行器只写执行记录,不能代替支付系统做审核或结算。
|
||||
|
||||
## 维护与异常恢复
|
||||
|
||||
- 密码轮换后,旧环境密码无法解密,服务就绪状态立即失败。更新执行器环境变量并重启;不要通过 HTTP 发送新密码。
|
||||
- 切换全局网络时,必须同步调整执行器允许网络。旧网络 `SIGNED` 记录未处理完前不要切换。
|
||||
- 存在 QUEUED/RUNNING/SIGNED 未决记录时,不要关闭后端功能开关后改走不受新表约束的旧通道。
|
||||
- `SIGNED` 长期未确认:核对网络、交易哈希、交易过期时间与链上结果。禁止清空签名记录或直接重新转账。
|
||||
- `RUNNING` 在进程异常退出后可能保留:先停止所有本地和远程执行进程,确认该记录没有 `signed_transaction`、没有交易哈希,
|
||||
且签名前持久化屏障确实未通过,再由维护人员将其标记为 FAILED。禁止运行中按时间强制抢占。
|
||||
- 后端分发归集期间异常退出时,主任务可能保留“正在分发链上执行任务”。先核对已创建指令与未提交明细,
|
||||
不要直接重跑主任务。明确已提交结果后再恢复业务状态;该保守占位用于避免重复归集。
|
||||
|
||||
需要停机维护时先停止新提交,等待已签名交易和业务同步完成,再停执行器、关闭功能开关。
|
||||
`signed_transaction` 不包含私钥,但具有广播能力,必须限制数据库读取和备份访问,不得公开或写日志。
|
||||
|
||||
## 验证
|
||||
|
||||
隔离测试覆盖:同业务并发提交/领取只成功一次、签名后不可标记为可重试失败、密码不入库、
|
||||
广播响应丢失时同一字节重播与恢复不重新签名、真实回环 HTTP 的 IP 白名单/凭据校验、伪造转发头拒绝、密码轮换未就绪。
|
||||
部署仍须验证公网无法连接、非白名单内网来源拒绝、错误服务凭据拒绝、TLS 验证和实际 NILE 链上确认。
|
||||
@@ -0,0 +1,73 @@
|
||||
# 归集与代付资源租赁
|
||||
|
||||
## 启用与兼容
|
||||
|
||||
默认关闭:`USDT_RESOURCE_RENTAL_ENABLED=false`。关闭时保留原转账通道、燃烧预算、审核和账务结算行为,不查询新增资源表。此功能仅用于归集、代付,普通钱包操作不自动购买资源。
|
||||
|
||||
部署前备份数据库,依次执行 `sql/chain_executor.sql`、`sql/resource_rental.sql`。均为增量建表,不删除旧数据。后端与执行器必须共享同一数据库;远程模式还需按 [执行器说明](chain-executor.md) 部署执行器。不要在生产数据库上运行测试脚本。
|
||||
|
||||
支付后端外部配置:
|
||||
|
||||
```yaml
|
||||
usdt:
|
||||
resource-rental:
|
||||
enabled: true
|
||||
provider: INTERNAL # INTERNAL 或 DUIYA,仅影响尚未授权的新准备记录
|
||||
arrival-timeout-seconds: 300
|
||||
rental:
|
||||
master-key: ${RENT_MASTER_KEY} # 外部注入的Base64编码32字节随机密钥
|
||||
```
|
||||
|
||||
也可使用已接入的环境变量 `USDT_RESOURCE_RENTAL_ENABLED`、`USDT_RESOURCE_RENTAL_PROVIDER`、`USDT_RESOURCE_ARRIVAL_TIMEOUT_SECONDS`。所有支付实例的密钥必须一致;不要随意更换,原订单查询仍需要解密原配置。执行器只核验资源和签名,不需要平台API密钥或租赁加密密钥。
|
||||
|
||||
## 保存平台配置
|
||||
|
||||
使用已登录管理员的 `system:usdtConfig:edit` 权限调用 `POST /system/chain-resources/config`。凭据为只写字段,后端加密入库;每次保存新增配置版本,原订单始终使用其 `config_id`,切换平台不会重购原单。不要把实际密钥写入文档、命令行或日志。
|
||||
|
||||
自有平台请求示例(占位符须在受控配置客户端中替换):
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "INTERNAL",
|
||||
"network": "NILE",
|
||||
"baseUrl": "https://rental.example.com",
|
||||
"apiKey": "<API Key>",
|
||||
"apiSecret": "<API Secret>",
|
||||
"durationSeconds": 3600,
|
||||
"energyStep": 30000,
|
||||
"bandwidthStep": 100,
|
||||
"maxOrderCost": 10,
|
||||
"maxExecutionCost": 20
|
||||
}
|
||||
```
|
||||
|
||||
`baseUrl` 为HTTPS站点根地址,自有平台适配器自动拼接 `/api/rental/v1`。自有租赁账户需要启用应用及API凭据、绑定当前网络的能量/带宽默认套餐并准备可用余额。`energyStep`、`bandwidthStep`、`durationSeconds` 必须匹配对应默认套餐的数量和周期倍数;不传 `package_id`。费用单位为USDT。
|
||||
|
||||
兑呀使用 `provider=DUIYA`、`network=MAINNET`、`baseUrl=https://weidubot.cc/api/v2`,按需设置 `energyPeriod`(默认`1h`)、`bandwidthPeriod`(默认`1day`)。费用单位为TRX;能量最低30000、带宽最低100,按配置步长向上取整。使用资源订单 `buy_energy/buy_net`,不调用速充接口。公开文档未确认测试网支持,DUIYA的NILE请求会被拒绝。
|
||||
|
||||
每类资源检查 `maxOrderCost`,每个业务准备检查 `maxExecutionCost`;人工额外受页面确认的报价上限限制。归集各地址独立计费。这里没有每日总费用额度,部署时按业务量设置单笔上限和平台余额。兑呀创建接口未提供锁价字段,预估费用无法替代平台最终扣费,首次上线需小额核对实际计价。
|
||||
|
||||
## 操作流程
|
||||
|
||||
人工执行:在归集/代付页面选择“手动输入配置密码”,点击执行后先展示实时资源和报价。可选择租赁,或沿用原转账规则。确认租赁仅购买缺口;页面只读轮询,支付后端独立查询链上,必须能量、带宽均足额才显示密码输入。输入密码并确认广播后,签名前再次核验。资源已足额时不购买。密码不持久化、不交给资源Worker,关闭弹窗不会自动转账。
|
||||
|
||||
远程执行:提交业务后保持原执行中状态;支付后端资源Worker为远程排队指令自动准备资源。执行器资源未就绪时仍保持QUEUED,不解锁钱包,不签名;就绪后复检、构造并签名一次,持久化后广播。等待期间的状态和错误显示在“最近执行记录”中。原转账授权有效期仍为10分钟,资源等待不会无限延长授权。
|
||||
|
||||
链上查询失败不是资源为零,不会因此付费。租赁平台返回成功或交付成功均不能证明可用资源满足,只有支付系统读取指定网络的实时 `limit-used` 并重新估算本次操作,才会置为READY。估算失败拒绝购买,不使用页面的默认能量兜底值。
|
||||
|
||||
## 防重复与恢复
|
||||
|
||||
- 同一业务唯一准备记录;同一次准备每类资源唯一订单。本地CREATED→SUBMITTING的数据库CAS是实际付费调用屏障,浏览器、多个后端实例、进程重启均复用原单。
|
||||
- 创建请求禁止HTTP自动重试和重定向。超时/响应丢失/进程中断保留SUBMIT_UNKNOWN,不回到CREATED。自有平台可按原商户单号只读核对;兑呀未文档化商户幂等号,结果未知必须人工核对平台账单,不能自动重下。
|
||||
- 等待超时显示TIMEOUT,可点“继续检查原单”;此操作只延长到账检测,不新建租赁订单、不更换平台、不延长转账授权。关闭页面后服务仍继续检查,重新打开复用原记录。
|
||||
- REVIEW阻止转账,即使地址后来资源足额也不会绕过未知/失败租赁订单;需运维核实原单。当前版本不提供自动补租第二轮或清除未知订单的按钮,避免重复扣费。已确定交付但资源仍不足时,可继续原单检测或由管理员从其他渠道补充资源,不自动再购买。
|
||||
- 同网络同发送钱包独占准备,主钱包代付按地址串行。签名后占用不按超时回收,只有链上收据确认资源已消耗才释放。已明确链上失败的原交易可复用原租赁资源重新预检,不自动重租。
|
||||
- 已租赁但尚未执行的准备保留地址占用,关闭弹窗不释放,也不撤销已付费订单。管理员应完成原操作或核对异常后处理;不要直接删除准备/订单/地址占用表记录。
|
||||
|
||||
业务审核、代付冻结与最终链上确认结算沿用原实现。租赁费用由平台账户支付,不混入商户USDT本金结算。一个归集地址失败不终止其他地址的后端准备,但人工批次需全部资源就绪才允许输入密码;可先取消尚未执行且无需继续的明细,再预检剩余明细。
|
||||
|
||||
## 验证范围
|
||||
|
||||
隔离H2测试使用真实增量SQL和可控链上/平台替身,覆盖并发唯一订单、延迟到账、两类资源分别到账、签名前回落、未知结果不重下、超时续查、原平台配置引用、费用上限和同地址互斥。既有链上执行与独立执行器启动测试继续运行。前端使用实际Vue/Element组件的模拟接口检查桌面1200px和窄屏390px,验证刷新不重复购买、到账前不展示密码、确认后才执行。
|
||||
|
||||
未进行真实钱包签名、真实平台扣费或生产数据库升级。上线需先配置自有平台NILE环境进行受控联调;DUIYA需在主网小额核对凭据、周期、扣费和代理到账。
|
||||
Reference in new issue
Block a user