# 管理员租赁接口调试台 ## 安装与入口 先执行已有租赁菜单脚本,再执行 `sql/rent_api_debugger_menu.sql`。新菜单为“资源租赁 / 租赁API调试”,组件 `rental/apiDebugger`,权限 `rent:api:debug`,默认只授予admin角色;其他管理员需显式分配菜单。当前目录路径为rental时访问 `/rental/api-debugger`,已安装目录使用proxyRent时为 `/proxyRent/api-debugger`。刷新登录权限后显示菜单,不需要后端新增配置或存储凭证。 ## 使用流程 1. 输入API基地址、租赁应用的API Key与API Secret。基地址默认取当前后台代理前缀,例如 `/prod-api`,最终调用 `/prod-api/api/rental/v1/packages`;直连API域名时填写 `https://租赁域名`,也支持包含实际代理前缀。 2. 在接口下拉框中选择7个商户接入接口之一,按“资源租赁 / 地址上链”分组。页面自动显示对应参数表单、必填标记、单位和填写说明;不适用的参数不显示。每个接口分别保留当前页面内的草稿。 3. 查询套餐后点击“使用此套餐报价”,填写真实资源接收地址,发送报价。 4. 报价成功后点击“使用此报价准备下单”,自动沿用参数、报价原始金额字符串并生成商户单号。确认接收地址、网络、费用和回调地址,再发送下单请求。 5. 下单成功后点击“查询此商户订单”跟踪状态。创建成功不代表履约成功;超时/停止等待不会取消服务端业务,请用原商户单号查询,不要贸然生成新单号重试。 ## 调试信息 ### 格式化请求的签名兼容 全局 `RepeatedlyRequestWrapper` 必须按原始字节缓存请求体。原实现通过 `HttpHelper.getBodyString` 逐行拼接,删除JSON中的LF/CRLF,造成页面签名与服务端验签请求体不同,表现为凭证正确但“租赁签名无效”。已改为原始字节缓存,并显式使用UTF-8读取字符,保留空格、换行和中文。此修复需要更新后端;不能通过要求用户删除换行或放宽验签来绕过。 默认使用表单填写网络、套餐ID、接收地址、商户单号、时长、资源数量、预计金额和回调地址。查询仅需原商户订单号,套餐查询仅需网络。选填参数清空时从请求中移除,不发送空字符串;金额和资源整数按精确字符串提交。需要扩展参数或排查原始字节时,切换“高级JSON / 请求预览”,两种模式共享同一份请求数据。无效JSON需先修正才能继续表单编辑。 页面展示HTTP状态、业务原始响应、耗时、可见响应头、完整请求URL、JSON原文、请求体SHA256和脱敏签名原文。API Key与签名脱敏,Secret不展示、不写日志、不持久化。签名与发送共用同一原始UTF-8请求体,时间戳和nonce每次更新;反向代理前缀不参与签名。 页面使用独立浏览器请求,不携带后台Token或Cookie,不使用后端代发代理。签名依赖Web Crypto,需要HTTPS或localhost。跨域API必须允许当前后台来源、POST、Content-Type和X-Rent-*认证头;响应头受浏览器CORS可见范围限制。证书不可信、网络错误、跨域或重定向均需按实际部署修复,页面不会关闭证书校验。 初版仅调试当前服务已提供的7个用户接入接口,不提供不存在的余额、取消或退款API。回调地址通过下单JSON的notify_url填写;Webhook接收和验签示例参见 `/rental-api` 文档页面。 ## 服务端验签日志排查 `RentalIdentity`在INFO级别打印“租赁认证开始 / 凭证已定位 / 认证成功”,失败在WARN打印“租赁认证失败”。同一次认证使用相同`diagnosticId`,同时沿用项目日志traceId。不会输出Secret、请求正文、完整Key或完整签名。 | stage | 排查方向 | | --- | --- | | AUTH_FIELDS | 检查keyValid、nonceValid、timestamp、serverTime、clockSkewMs;客户端时间必须在±60秒内 | | CREDENTIAL_LOAD | Key不存在、凭证已吊销或过期,或数据库异常;使用Key的SHA256前16位keyFingerprint关联同一凭证 | | OWNER_TYPE | 例如在商户API中使用NODE节点凭证;此处需要APP凭证 | | SIGNATURE_FORMAT | 签名缺失、长度不为64或不是十六进制;观察signatureLength/Whitespace等字段 | | SECRET_DECRYPT | 检查部署主密钥及版本,不能通过重填客户端Secret修复服务端解密问题 | | SIGNATURE_COMPARE | 将method、path、bodySha256与调试台逐项对照;路径不含代理剥离前缀,JSON签名后不能修改;协议输出小写签名。若路径和摘要一致,再检查原始Secret是否匹配、是否复制了空格 | | NONCE_SAVE | 检查是否重复提交同一nonce或数据库结构问题,每次请求必须产生新nonce | bodyBytes为UTF-8字节数,bodyLfCount/bodyCrCount为服务端实际收到的换行数。比如页面请求有格式化换行而日志显示0,应继续排查部署版本、全局过滤器和代理是否改写正文。storedMasterVersion/configuredMasterVersion仅显示版本号,不输出密钥内容。 ## 本地验证 已校验Vue模板与脚本解析;使用Node Web Crypto及独立HMAC计算交叉核对签名、JSON原文字节、代理前缀、地址上链子路径和随机nonce。未用真实凭证创建订单或冻结资金。 前端staging打包通过,保留项目已有3个API导出缺失告警及资源体积告警。本次无后端业务或数据库结构变更;菜单SQL尚未执行。