17 KiB
租赁模块三端实现与运行说明
供应商/租赁账户首页现为统计图表与运行监控看板,不嵌入业务操作菜单;接口、指标口径和可选索引升级见角色统计看板。
用户套餐绑定增量:核心表新增 rent_user_package,管理员授权具体套餐版本;应用按 user_id 选择已绑定套餐,省略 package_id 自动选择默认。部署前执行增量表SQL并配置用户绑定,见 用户套餐绑定与脚本。历史订单和在途处理不受绑定变更影响。
本文对应当前工作区的 V2.2 实现。设计依据仍为 schema-design.md 和 rent_init.sql。代码交付不等于生产迁移或真实链上验收;本次没有修改现有数据库,没有执行任何真实广播。
1. 三端职责
| 端 | 入口 | 职责 |
|---|---|---|
| Java 8 后端 | ruoyi-system/.../rental |
归属及权限、钱包控制权、固定套餐、冻结与不可变流水、任务调度、独立核验、回收、退款、人工结算、持久回调 |
| Vue 2 前端 | usdt-ui/src/views/rental |
商户/供应商工作台与运营操作;原16个管理菜单和3个用户菜单路径保留,复用业务组件 |
| 本地 Node.js Agent | rent-agent/src |
主动WSS连接、双向签名心跳、加密可靠日志、钱包本地限制、只构建签名一次、原交易恢复 |
| 本地 JavaFX Agent(替代实现) | rent-agent-java/src |
JDK17 + JavaFX20.0.2,使用同一节点协议;桌面启停、广播确认、本地签名与原交易恢复 |
供应商可选择 Node.js 24 + TronWeb 6.0.4,或独立的 JDK17 + JavaFX20.0.2 桌面Agent。Java版安装、配置与验证见 Java Agent README,不依赖Node运行时,不修改示例JavaFX钱包程序,不要求供应商运行完整TRON节点。同一节点/钱包不能同时运行两种实现;原签名交易的本地存储结构不同,存在在途或未知任务时不能直接互换日志接管。
核心链路:商户下单冻结USDT → 后端按可信动态资源参数预留SUN → 推送冻结任务意图 → Agent先保存再ACK、复核后本地签名、原交易落盘后广播 → 云端独立核验 → 达标且未到期则扣款及记供应商净应收 → 到期按原SUN撤销 → 资源实际恢复后释放地址对占位。
生成器的 /system/rentXxx 接口已由 RentalLegacyGuard 拒绝,包括读取、导出及写入。这样既防止任意覆盖余额/状态,也防止旧凭证导出接口泄露密文。新页面使用 /rental,不要再调用旧CRUD。旧Service/Mapper保留作为已生成基础代码,业务链路不调用其任意修改方法。
角色配置与资金账户
角色编码、专属首页及完整接口授权 SQL 见 角色首页与权限配置。
| 角色 | 需要配置的业务主体 | 资金账户用途 |
|---|---|---|
| 供应商(仅出租) | rent_node、节点凭证、本地 Agent 及 rent_wallet;无需 rent_app |
通过 rent_account 记录净待结算收入、退款冲正和结算 |
| 租赁用户(购买资源的商户) | rent_app;使用外部 API 时配置应用凭证 |
通过 rent_account 记录充值、可用余额、订单冻结和扣款 |
供应商无需手动创建或配置 rent_account:当前代码在调度选中供应商时,根据 rent_node.user_id 与订单网络自动创建或复用账户,并将其固定到订单的 supplier_account_id。这不意味着供应商不需要资金账户记录。
rent_account 是平台内部 USDT 账本账户,不是链上钱包,不需要配置私钥。每个用户在每个网络只有一个账户(user_id + network 唯一),不按应用或节点单独开立;同一用户可以同时出租和购买资源,共用对应网络的账户。NILE 和 MAINNET 的资金分别记账。完整角色与表关系见 设计说明。
2. 数据库、菜单和后端配置
- 新环境检查MySQL5.7.8+/8.0配置后执行
sql/rent_init.sql。已有旧表不能靠IF NOT EXISTS升级,必须按实际结构和在途数据编写增量迁移;本次未运行脚本。 - 执行
sql/rent_menu.sql创建租赁工作台、16个运营查询菜单及按钮权限,不自动向任何现有角色授权。通过若依角色管理分配商户、供应商、运营、退款申请人、独立财务审批人。 - 使用 JDK8;在 Spring Boot 配置中包含
rentalprofile,载入application-rental.yml。通过环境变量注入配置。默认RENT_ENABLED=false,不开调度或节点Socket。 RENT_MASTER_KEY必须为外部生成的32字节随机密钥的Base64。不要使用测试代码中的零值密钥,也不要把实际值提交到仓库。RENT_MASTER_KEY_VERSION标识当前版本;当前运行实例必须保留解密历史Secret所需的相同主密钥。本实现不自动迁移主密钥版本,换主密钥前须另行完成离线重封装。- 配置
RENT_NILE_RPC/RENT_MAINNET_RPC、可选RENT_RPC_KEY,以及每个网络的租赁USDT收款地址RENT_NILE_DEPOSIT/RENT_MAINNET_DEPOSIT。USDT合约地址复用TronServiceProvider.getServiceForNetwork(),不随支付全局网络切换。 - 单实例Socket入口启用
RENT_ENABLED=true,通过HTTPS反向代理暴露/node/v1/socket。代理保留WebSocket Upgrade,读超时大于45秒,对API及Socket入口设置连接数和速率限制。首版不承诺跨实例Socket路由;数据库持久事实可以多worker争抢,但节点WSS须固定一个入口实例。
可在本地用以下命令生成随机主密钥,仅把输出放入安全配置:
node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
UTC字段使用 LocalDateTime 显式按UTC写入,不改变支付业务的LOCAL JDBC连接时区。租赁HTTP响应把BIGINT和USDT转为字符串,防止浏览器浮点数丢精度;时间输出UTC ISO8601,响应设置 Cache-Control: no-store。
3. 首次开通流程
- 商户进入租赁工作台,创建应用,开通所需网络的租赁账户,在凭证页为本人APP签发Secret并立即安全保存。充值发到配置的租赁收款地址后,运营填写原USDT交易哈希、Transfer日志序号及精确金额审核;后端独立校验合约、接收地址、金额及确认深度,同一日志不能给不同用户重复入账。
- 供应商注册节点,运营用不同账号审核通过;供应商为本人NODE创建凭证。节点审核与连接在线是两个不同状态。
- 供应商绑定公开钱包,TronLink切换到该地址,点击一次性消息验证。挑战绑定平台域、用户、钱包、网络、nonce及有效期;后端恢复地址并原子消费挑战。此步骤不广播、不收取验证费。
- 运营审核钱包;供应商分别开启能量/带宽出租并设置SUN本金留存。平台不接受钱包私钥。Agent首版只支持owner权限单签,不自动处理多签或自定义active权限;不满足时拒绝执行。
- 运营新增不可变套餐版本,显式填写正数量、正冗余、租期、售价、供应商毛收入、0至100之间的正手续费率及正费用预算,然后审核上架。改价新增版本,不覆盖旧订单快照。
- Agent启动且同步完成后节点才ONLINE;对应钱包可信快照有效时才可调度。
4. Agent安装与恢复
在 rent-agent 目录执行:
npm ci --ignore-scripts
node --env-file=.env src/index.js
复制 .env.example 为本机 .env 并填写。.env、data 和 node_modules 已忽略提交。私钥只留在本地;日志密钥 RENT_JOURNAL_KEY 必须与云端主密钥、API Secret分离。填写本人 RENT_NODE_ID、RENT_NODE_NO、NODE凭证、网络RPC和本地额度。默认 RENT_ALLOW_BROADCAST=false,任务会明确拒绝为未构建;供应商在本地审核后才可改为true并重新启动。平台无法替本地开启广播。
RENT_MAX_SUN、RENT_MAX_FEE_SUN 为每笔上限;RENT_ENERGY_ENABLED / RENT_BANDWIDTH_ENABLED 是本地独立出租开关,默认false,需供应商明确开启。关闭某类出租不阻止原授权本金回收,但全局广播关闭仍不广播。两个资源各有留存本金;另有 RENT_TRX_RETAIN_SUN 费用留存。Agent查询实时 getTransactionFee,用600字节保守预算检查原生交易费用,构建后再次限制实际原文和签名预留不超过预算字节;这是本地预算策略,不是协议的 fee_limit 硬上限。SDK无法精确表示的整数超过 Number.MAX_SAFE_INTEGER 时直接拒绝,绝不转成不精确数字广播。
本地 journal.gcm 保存完整原任务、原签名交易、txId和待ACK事件,使用AES-256-GCM;写临时文件、fsync、原子rename,成功后才ACK或广播。重复任务相同内容只恢复,内容变化拒绝。广播超时、断线、租约过期或重启均不能构造新交易;过期原交易只查询。无已保存交易的BUILDING/UNKNOWN保持隔离,不重新构建。未知不等于失败。
同一数据目录用 agent.lock 排除并发进程。正常关闭会先停止接单并等待RPC归档,再释放锁。崩溃保留锁:先确认原进程已退出、只有一套Agent使用该钱包、备份整个加密数据目录,再人工移除该精确锁文件后重启。不得删除日志“重置”任务。丢失日志密钥、签名交易或原Secret时停止接单并核对云端与链上,不按空记录重新执行。
凭证轮换时通过 RENT_OLD_KEYS 保留仍有在途任务的旧 api_key:secret JSON映射。云端新连接使用当前ACTIVE凭证,历史任务内层意图使用原凭证验签。REVOKED不再投递;历史链上独立核验继续进行。
5. HTTP业务接口
所有 /rental 接口使用若依JWT及明确 rent:* 权限,用户归属由服务端关联查询决定。分页每页50条,页码从1开始。
| 接口 | 功能 |
|---|---|
GET /rental/mine/{resource} |
本人的应用、节点、钱包、订单、资金及公开上架套餐 |
GET /rental/manage/{resource} |
运营16表脱敏查询,不返回Secret、签名或挑战 |
POST /rental/register/{app,node,wallet} |
创建本人业务主体 |
POST /rental/credential/issue、/{id}/revoke |
凭证轮换、吊销;Secret仅一次展示 |
POST /rental/wallet/{id}/{challenge,prove,policy} |
钱包挑战、TronLink验证和出租策略 |
POST /rental/package、/status/{resource}/{id} |
套餐版本创建及运营审核启停 |
POST /rental/account/open、/account/{id}/topup |
开户及独立校验充值 |
POST /rental/order、/order/{id}/cancel |
订单幂等冻结及未派单取消 |
POST /rental/order/{id}/refund、/refund/{id}/review |
退款申请、不同账号审批和内部入账 |
POST /rental/settlement |
按同一供应商同网络的订单净来源建立结算 |
POST /rental/settlement/{id}/{approve,reject,pay,unknown,confirm} |
独立审批、原付款授权及核验;PAYING/UNKNOWN不可拒绝释放 |
POST /rental/wallet/{id}/refresh、/task/{id}/verify |
可信快照和原交易独立核验 |
POST /rental/task/{id}/attach |
只给原在途任务补充已独立核对的原交易哈希 |
POST /rental/order/{id}/resolve |
仅MANUAL_REVIEW、HELD且回收DONE的异常单可解冻终结 |
POST /rental/webhook/{id}/retry |
人工修正配置后重新投递DEAD事件,原编号和业务内容不变 |
GET /rental/reconcile?afterId=0 |
分批核对余额与不可变流水、钱包SUN预留与任务占用 |
每天UTC02:00自动进行账账核对,发现差异只告警,不直接修复余额或释放未知本金。运营可在资金账户/流水页主动执行完整分页核对。
结算 pay 先持久化唯一 payout_no 及本次收款地址,再由人工付款;重试返回原授权,不产生新的付款。confirm 根据原授权收款地址、账户网络及精确USDT金额核对原交易日志。后端不自动对外出金。
6. 外部商户签名接口
POST /api/rental/v1/create、query、packages,仅JSON,最多64KiB,不允许查询串。请求头为 X-Rent-Key、X-Rent-Timestamp(Unix毫秒)、X-Rent-Nonce、X-Rent-Signature。认证窗口前后60秒,nonce保留180秒后可清理。
签名原文用换行连接,末尾不加换行:
RENT_HMAC_SHA256_V1
API
api_key
timestamp
nonce
POST
/api/rental/v1/create
SHA256(实际UTF-8请求体)的小写十六进制
使用Secret做HMAC-SHA256,输出小写64位十六进制。scope为API/NODE/TASK/WEBHOOK,不能互换;不共用支付MD5。下单字段:package_id、merchant_order_no、receiver_address,可选 notify_url 和与套餐一致的 resource_type。APP和用户从凭证推导。query 用 merchant_order_no;packages 用 network。
跨语言固定向量:Secret=test-secret、scope=API、key=test-key、timestamp=1700000000123、nonce=abcdefghijklmnop、method=POST、path=/api/rental/v1/create、body={"amount":"1.000000"},结果为 47241a34f0813881384317eafbfc068dc9f7c6061a8fe269cb815e7820d48430。此值仅用于测试,不是有效运行凭证。
回调使用相同请求头但scope=WEBHOOK;仅HTTPS公网443、无用户信息/fragment/query,实际DNS连接地址逐个检查,不跟随重定向。HTTP200且正文精确为 ok 才确认。最多10次,失败指数退避,终止为DEAD;每次新timestamp/nonce,业务event_no、payload和订单事件序号不变。商户按event_no去重并按序号识别乱序。无回调地址的事件直接确认,不发HTTP。
7. WSS协议与历史资源证明
通道 /node/v1/socket:CHALLENGE → AUTH → 签名AUTH_OK → 分页SYNC_STATE/SYNC_ACK → ONLINE。未同步不得接新单。外层帧的 body 是原始JSON字符串;信封含 api_key,timestamp,nonce,body,signature,NODE域、method=FRAME、path固定。body含type、方向、session_id、session_epoch、sequence、message_id、payload。双方向序号各自从1递增。每15秒签名PING/PONG,45秒超时断开,nonce重复或旧会话帧拒绝。
TASK_PUSH中保留稳定delivery_message_id、原api_key/intent/timestamp/nonce/signature。TASK域、method=PUSH、path=/node/v1/task。任务intent为按键排序的紧凑JSON;任务字段只含ASCII字符串/布尔值。MySQL JSON规范化后由后端按同一规则重建,再传输原意图,不改变授权内容。
Agent事件先落本地可靠队列,云端同事务以 NODE:nodeId:eventId 去重后RESULT_ACK。ACK只说明持久接收,ACCEPTED只说明本地接受,BUILT/BROADCASTED/RESULT只说明执行线索。云端另查交易合约、owner/receiver、网络、资源类型、非锁定、SUN、回执、确认深度和关系,不能凭节点消息扣款。
普通TRON RPC没有任意确认区块的资源历史查询。现已增加与云端同进程部署的内置历史采集/证明服务:执行 sql/rent_history_init.sql 增加4张历史表,设置 RENT_HISTORY_EMBEDDED_ENABLED=true 和 RENT_HISTORY_NETWORKS=NILE。派单前采集确认关系基线,持续归档确认区块和资源参数,交付核验直接调用Java服务;不需要填写 RENT_NILE_HISTORY / RENT_MAINNET_HISTORY。表设计、接口、配置、采集缺口与部署详见 内置历史证明服务。
外部服务模式继续兼容:内置关闭时,RENT_NILE_HISTORY / RENT_MAINNET_HISTORY 可以指向运营部署、独立于供应商的可信历史证明服务。后端向 /rental/resource-proof POST network,tx_id,block_height,owner,receiver,resource_type,服务必须基于该实际区块状态返回:
{"tx_id":"原交易哈希","block_height":123,"baseline_sun":0,"after_sun":1300000000,"total_limit":60000000,"total_weight":1000000}
示例参数不代表当前链。内置实现从启用时开始保存真实确认状态,不会补造上线前或停机期间漏采的全网参数。未配置历史服务,或内置服务缺少该高度参数/派单前基线时,可以确认真实委托,但订单转MANUAL_REVIEW、保留HELD资金并按原SUN回收,不自动记SUCCESS或供应商收入。 内置区块尚未采集到交易高度则保持待核验并重试。交易已确认而交付不足、核验时已过期,同样人工隔离。可在确认回收DONE后通过受保护的resolve解冻。外部擅自变更委托关系会告警并转人工,不能任意释放关系占位。
8. 验证与边界
具体命令、结果及尚未验收的外部条件见 validation-implementation.md。
已提供后端 RentalBusinessTest 与 Agent test/agent.test.js,分别覆盖资金/并发/状态机/协议和本地加密持久化/原交易恢复。H2测试从权威16表DDL只替换H2不支持的存储及JSON声明,保留字段与唯一键;不等同真实MySQL并发验收。Socket测试使用可控会话,不等同公网TLS/半开连接验收。前端构建输出到独立目录,不覆盖现有dist。
未接入项目数据库、实际部署WSS、真实TronLink浏览器签名、NILE委托/回收或历史证明服务进行联调;这些必须在专用测试环境验收后再启用业务。本实现不自动开放主网广播、不自动建设历史节点、不自动出金。