From 4818f25d8f56870eff7a0833b3425c458f7ad95a Mon Sep 17 00:00:00 2001 From: luqingjie <544309509@qq.com> Date: Mon, 2 Nov 2026 20:25:09 -0500 Subject: [PATCH] =?UTF-8?q?=E5=9B=9E=E8=B0=83=E9=AA=8C=E8=AF=81=E5=92=8C?= =?UTF-8?q?=E8=B0=83=E8=AF=95=E6=97=A5=E5=BF=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/rental-address-onchain.md | 14 ++ .../src/main/resources/application-rental.yml | 6 + .../system/WebhookDebugControllerTest.java | 69 +++++++++ .../controller/WebhookDebugController.java | 131 ++++++++++-------- 4 files changed, 164 insertions(+), 56 deletions(-) create mode 100644 ruoyi-admin/src/test/java/com/ruoyi/web/controller/system/WebhookDebugControllerTest.java diff --git a/docs/rental-address-onchain.md b/docs/rental-address-onchain.md index ff43007..382ae71 100644 --- a/docs/rental-address-onchain.md +++ b/docs/rental-address-onchain.md @@ -138,6 +138,20 @@ WAITING且没有任务表示尚未派单;已有PENDING任务则继续检查Soc ## 回调未到达排查(2026-11-02) +### 调试接收端验签 + +`WebhookDebugController`的`POST /api/webhook/debug`仅接收application/json。使用原始UTF-8正文和X-Rent-Key/Timestamp/Nonce/Signature请求头,复用租赁WEBHOOK域HMAC-SHA256协议,允许时间偏差小于60秒;正文上限512KiB。GET返回405,未配置凭证返回503,认证失败401,事件JSON无效400,nonce重放409;仅验签及持久化nonce成功返回纯文本ok。不更新业务订单,不用于正式记账,合法事件重投携带新nonce时可再次观察。 + +```yaml +rental: + webhook-debug: + api-key: ${RENT_WEBHOOK_DEBUG_API_KEY:} + api-secret: ${RENT_WEBHOOK_DEBUG_API_SECRET:} + signature-path: ${RENT_WEBHOOK_DEBUG_SIGNATURE_PATH:} +``` + +凭证必须与发送器当前选择的APP有效凭证一致;轮换后同步更新接收端。路径必须与外部notify_url路径逐字一致:例如回调地址为`http://192.168.3.103/api/api/webhook/debug`,Nginx移除一层/api后,设置`RENT_WEBHOOK_DEBUG_SIGNATURE_PATH=/api/api/webhook/debug`。留空使用后端实际请求URI,不能从不可信转发头推断路径。不将Secret、签名、完整正文或异常原文写日志;成功记录事件号、订单号、事件类型及状态摘要。修改配置后重启服务。此接口映射不能修复Nginx静态服务产生的405,仍需确保POST转发到后端2020端口。 + 在服务端日志中按 `webhookId` 或 `orderId` 查询“租赁回调”。日志依次包含领取次数/正文字节数、目标主机/路径、有效凭证记录ID、POST请求开始、HTTP响应状态/长度和最终状态;异常包含失败阶段及安全的异常类型/代码位置,不输出Secret、签名、请求正文或响应正文。`rent_webhook.last_error`同步保存固定阶段和原因码。 - `TARGET_NOT_PUBLIC`:目标被地址策略拒绝。开启内网配置后允许192.168/10/172.16~31及IPv6 ULA;回环、链路本地、未指定及组播仍拒绝。关闭内网配置时192.168.x.x等也会被拒绝。 diff --git a/ruoyi-admin/src/main/resources/application-rental.yml b/ruoyi-admin/src/main/resources/application-rental.yml index c83baac..f566df2 100644 --- a/ruoyi-admin/src/main/resources/application-rental.yml +++ b/ruoyi-admin/src/main/resources/application-rental.yml @@ -8,6 +8,12 @@ rental: webhook: # 允许192.168/10/172.16~31及IPv6 ULA内网HTTP/HTTPS回调;HTTP允许自定义端口,HTTPS仍验证证书。 allow-private-network: ${RENT_WEBHOOK_ALLOW_PRIVATE_NETWORK:true} + webhook-debug: + # 填写发送回调使用的有效APP凭证;缺失返回503,不跳过验签。 + api-key: ${RENT_WEBHOOK_DEBUG_API_KEY:} + api-secret: ${RENT_WEBHOOK_DEBUG_API_SECRET:} + # 签名使用外部URL路径;代理移除前缀时可填写/api/api/webhook/debug。 + signature-path: ${RENT_WEBHOOK_DEBUG_SIGNATURE_PATH:} # 正常在线、无排队且RPC及时返回时,调度+推送等待约0~5秒,目标10秒左右接单。 # 均为上轮执行完成后的等待时间;链上查询耗时不包含在间隔中。修改后重启服务端。 delivery: diff --git a/ruoyi-admin/src/test/java/com/ruoyi/web/controller/system/WebhookDebugControllerTest.java b/ruoyi-admin/src/test/java/com/ruoyi/web/controller/system/WebhookDebugControllerTest.java new file mode 100644 index 0000000..ebe8e7d --- /dev/null +++ b/ruoyi-admin/src/test/java/com/ruoyi/web/controller/system/WebhookDebugControllerTest.java @@ -0,0 +1,69 @@ +package com.ruoyi.web.controller.system; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.ruoyi.system.controller.WebhookDebugController; +import com.ruoyi.system.rental.RentalCrypto; +import com.ruoyi.system.rental.RentalStore; +import org.junit.Test; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.mock.web.MockHttpServletRequest; +import org.springframework.test.util.ReflectionTestUtils; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.test.web.servlet.setup.MockMvcBuilders; +import static org.junit.Assert.*; +import static org.mockito.Mockito.*; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; + +/** 验证原文签名、代理路径、重放和HTTP方法,不连接真实数据库或回调目标。 */ +public class WebhookDebugControllerTest { + private final RentalStore store = mock(RentalStore.class); + private final WebhookDebugController controller = new WebhookDebugController(store, new ObjectMapper()); + private final String body = "{\"event_no\":\"WH-test\",\"event_type\":\"SUCCESS\"}"; + private final String externalPath = "/api/api/webhook/debug"; + + private void configure() { + ReflectionTestUtils.setField(controller, "apiKey", "test-key"); + ReflectionTestUtils.setField(controller, "apiSecret", "test-secret"); + ReflectionTestUtils.setField(controller, "signaturePath", externalPath); + } + + private MockHttpServletRequest signed(String content, long timestamp, String path) { + MockHttpServletRequest request = new MockHttpServletRequest("POST", "/api/webhook/debug"); + request.setContentType("application/json"); + request.setContent(content.getBytes(java.nio.charset.StandardCharsets.UTF_8)); + request.addHeader("X-Rent-Key", "test-key"); + request.addHeader("X-Rent-Timestamp", Long.toString(timestamp)); + request.addHeader("X-Rent-Nonce", "abcdefghijklmnop"); + request.addHeader("X-Rent-Signature", RentalCrypto.sign("test-secret", "WEBHOOK", "test-key", + timestamp, "abcdefghijklmnop", "POST", path, body)); + return request; + } + + @Test public void verifiedPostUsesExternalPathAndRejectsReplay() throws Exception { + configure(); + MockHttpServletRequest request = signed(body, System.currentTimeMillis(), externalPath); + assertEquals("ok", controller.receive(request).getBody()); + verify(store).insert(eq("nonce"), argThat(values -> "DEBUG_WEBHOOK".equals(values.get("scope")))); + when(store.insert(eq("nonce"), anyMap())).thenThrow(new DuplicateKeyException("duplicate")); + assertEquals(409, controller.receive(signed(body, System.currentTimeMillis(), externalPath)).getStatusCodeValue()); + } + + @Test public void tamperedExpiredOrWrongPathCannotReachNonceStore() throws Exception { + configure(); + assertEquals(401, controller.receive(signed(body + " ", System.currentTimeMillis(), externalPath)).getStatusCodeValue()); + assertEquals(401, controller.receive(signed(body, System.currentTimeMillis() - 120000, externalPath)).getStatusCodeValue()); + assertEquals(401, controller.receive(signed(body, System.currentTimeMillis(), "/wrong")).getStatusCodeValue()); + verifyNoInteractions(store); + } + + @Test public void postMappingAndMissingConfigurationAreExplicit() throws Exception { + MockMvc mvc = MockMvcBuilders.standaloneSetup(controller).build(); + mvc.perform(get("/api/webhook/debug")).andExpect(status().isMethodNotAllowed()); + mvc.perform(post("/api/webhook/debug").contentType("application/json").content(body)) + .andExpect(status().isServiceUnavailable()); + configure(); + mvc.perform(post("/api/webhook/debug").contentType("application/json").content(body)) + .andExpect(status().isUnauthorized()); + } +} diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/controller/WebhookDebugController.java b/ruoyi-system/src/main/java/com/ruoyi/system/controller/WebhookDebugController.java index 0c0e74d..6b11f40 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/controller/WebhookDebugController.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/controller/WebhookDebugController.java @@ -1,88 +1,107 @@ package com.ruoyi.system.controller; +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.ruoyi.system.rental.RentalCallbackDemoController; +import com.ruoyi.system.rental.RentalStore; +import com.ruoyi.system.rental.RentalValues; import java.io.IOException; +import java.nio.ByteBuffer; +import java.nio.charset.CodingErrorAction; import java.nio.charset.StandardCharsets; -import java.util.regex.Pattern; +import javax.servlet.ServletInputStream; import javax.servlet.http.HttpServletRequest; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.dao.DuplicateKeyException; import org.springframework.http.MediaType; import org.springframework.http.ResponseEntity; -import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RestController; -import org.springframework.web.util.UriUtils; -/** - * 通用 Webhook 免登录调试入口。只用于确认网络连通和观察回调数据, - * 不校验业务签名、不修改订单,也不代表业务回调已验签或已处理成功。 - */ +/** 租赁回调验签调试端:按原始正文验证WEBHOOK域HMAC,仅记录事件摘要,不修改订单。 */ @RestController public class WebhookDebugController { - private static final Logger LOG = LoggerFactory.getLogger(WebhookDebugController.class); + private static final int MAX_BODY_BYTES = 512 * 1024; + private final RentalStore store; + private final ObjectMapper json; + @Value("${rental.webhook-debug.api-key:}") + private String apiKey; + @Value("${rental.webhook-debug.api-secret:}") + private String apiSecret; + /** 显式配置外部原始路径;不信任调用方传入的Forwarded头。空值使用请求URI。 */ + @Value("${rental.webhook-debug.signature-path:}") + private String signaturePath; - /** 限制单次读取量,避免匿名请求产生无限大的日志或内存占用。 */ - private static final int MAX_BODY_BYTES = 64 * 1024; + public WebhookDebugController(RentalStore store, ObjectMapper json) { + this.store = store; + this.json = json; + } - /** JSON、表单和查询参数中的常见凭据不得直接写入日志。 */ - private static final Pattern SENSITIVE_VALUE = Pattern.compile( - "(?i)([\"']?(?:token_key|private_key|privateKey|api_secret|apiSecret|password|" - + "mnemonic|authorization|secret|access_token|token|signature)[\"']?\\s*[:=]\\s*)" - + "(\"(?:\\\\.|[^\"\\\\])*\"|'[^']*'|[^&\\s,}]+)"); - - /** - * 接受任意 HTTP 方法和正文格式,兼容 JSON、表单及纯文本回调。 - * 正常接收返回 HTTP 200 和纯文本 ok,便于回调发送方确认送达。 - * 仅记录 Content-Type 等必要元数据,不记录可能携带令牌的请求头。 - * - * @param request 原始回调请求 - * @return 回调接收确认;正文超过上限时返回 HTTP 413 - * @throws IOException 请求流读取失败时由框架返回错误,不伪装成成功 - */ - @RequestMapping(value = "/api/webhook/debug", produces = MediaType.TEXT_PLAIN_VALUE) + @PostMapping(value = "/api/webhook/debug", consumes = MediaType.APPLICATION_JSON_VALUE, + produces = MediaType.TEXT_PLAIN_VALUE) public ResponseEntity receive(HttpServletRequest request) throws IOException { + if (apiKey == null || apiKey.isEmpty() || apiSecret == null || apiSecret.isEmpty()) { + LOG.warn("租赁调试回调拒绝 reason=CREDENTIAL_NOT_CONFIGURED"); + return ResponseEntity.status(503).body("callback credentials not configured"); + } + String path = signaturePath == null || signaturePath.isEmpty() ? request.getRequestURI() : signaturePath; + LOG.info("租赁调试回调接收 method=POST requestPath={} signaturePath={} contentLength={}", + safe(request.getRequestURI()), safe(path), request.getContentLengthLong()); byte[] buffer = new byte[MAX_BODY_BYTES + 1]; int total = 0; int count; - while (total < buffer.length - && (count = request.getInputStream().read(buffer, total, buffer.length - total)) != -1) { + // 只获取一次输入流,防止可重复读取包装器在循环中重复返回正文。 + ServletInputStream stream = request.getInputStream(); + while (total < buffer.length && (count = stream.read(buffer, total, buffer.length - total)) != -1) { total += count; } if (total > MAX_BODY_BYTES) { - LOG.warn("Webhook debug rejected: body exceeds {} bytes", MAX_BODY_BYTES); + LOG.warn("租赁调试回调拒绝 reason=BODY_TOO_LARGE"); return ResponseEntity.status(413).body("payload too large"); } - String body = new String(buffer, 0, total, StandardCharsets.UTF_8); - String query = request.getQueryString(); - // 表单先解码再脱敏,防止百分号编码的字段名绕过敏感字段匹配。 - if (request.getContentType() != null - && request.getContentType().startsWith(MediaType.APPLICATION_FORM_URLENCODED_VALUE)) { - body = decode(body); + final JsonNode event; + String stage = "SIGNATURE"; + try { + String body = StandardCharsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT) + .decode(ByteBuffer.wrap(buffer, 0, total)).toString(); + RentalCallbackDemoController.verify(apiKey, apiSecret, request.getHeader("X-Rent-Key"), + Long.parseLong(request.getHeader("X-Rent-Timestamp")), request.getHeader("X-Rent-Nonce"), + path, body, request.getHeader("X-Rent-Signature"), System.currentTimeMillis()); + stage = "EVENT_JSON"; + event = json.readTree(body); + RentalValues.require(event != null && event.isObject() && event.path("event_no").isTextual() + && !event.path("event_no").asText().isEmpty() + && event.path("event_no").asText().length() <= 64, "通知事件无效"); + } catch (Exception ex) { + // 不输出异常原文、认证请求头、Secret、签名及正文。 + LOG.warn("租赁调试回调拒绝 stage={} reason=INVALID_NOTIFICATION exceptionType={}", + stage, ex.getClass().getSimpleName()); + return ResponseEntity.status("SIGNATURE".equals(stage) ? 401 : 400).body("invalid notification"); } - LOG.info("Webhook debug received: method={}, path={}, remote={}, contentType={}, query={}, body={}", - new Object[] {request.getMethod(), request.getRequestURI(), request.getRemoteAddr(), - safe(request.getContentType()), safe(decode(query)), safe(body)}); + try { + // 独立scope和数据库唯一键跨实例防重放;合法事件重投使用新nonce。 + // 此接口不执行记账,重复event_no允许观察;正式业务应另做事件幂等处理。 + store.insert("nonce", RentalValues.map("api_key", apiKey, "scope", "DEBUG_WEBHOOK", + "nonce", request.getHeader("X-Rent-Nonce"), "expires_at", RentalValues.after(180))); + } catch (DuplicateKeyException ex) { + LOG.warn("租赁调试回调拒绝 reason=NONCE_REPLAY"); + return ResponseEntity.status(409).body("replayed notification"); + } catch (Exception ex) { + LOG.warn("租赁调试回调拒绝 reason=NONCE_STORAGE_FAILED exceptionType={}", ex.getClass().getSimpleName()); + return ResponseEntity.status(503).body("retry later"); + } + LOG.info("租赁调试回调验签成功 eventNo={} orderNo={} eventType={} orderType={} status={} bodyBytes={}", + safe(event.path("event_no").asText()), safe(event.path("order_no").asText()), + safe(event.path("event_type").asText()), safe(event.path("order_type").asText()), + safe(event.path("status").asText()), total); return ResponseEntity.ok("ok"); } - /** 非法 URL 编码不回显原文,避免错误日志泄露凭据。 */ - private static String decode(String value) { - if (value == null) { - return ""; - } - try { - return UriUtils.decode(value, StandardCharsets.UTF_8.name()); - } catch (Exception exception) { - return "[invalid URL encoding]"; - } - } - - /** 脱敏后转义换行,确保一条回调对应一条日志,避免伪造日志行。 */ private static String safe(String value) { - if (value == null) { - return ""; - } - return SENSITIVE_VALUE.matcher(value).replaceAll("$1\"***\"") - .replace("\r", "\\r").replace("\n", "\\n"); + String clean = value.replaceAll("[\\p{Cntrl}]", "_"); + return clean.substring(0, Math.min(clean.length(), 256)); } }