From 43dec4c94bf508f781824fc51c4a602bd1b468c4 Mon Sep 17 00:00:00 2001 From: luqingjie <544309509@qq.com> Date: Mon, 2 Nov 2026 21:17:15 -0500 Subject: [PATCH] =?UTF-8?q?405=E9=97=AE=E9=A2=98=E6=97=A5=E5=BF=97?= =?UTF-8?q?=E6=B7=BB=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/rental-address-onchain.md | 2 + docs/rental-webhook-405.md | 55 +++++++++++++++++++ .../system/WebhookDebugControllerTest.java | 8 ++- .../controller/WebhookDebugTraceFilter.java | 50 +++++++++++++++++ .../ruoyi/system/rental/RentalWorkers.java | 23 +++++++- 5 files changed, 134 insertions(+), 4 deletions(-) create mode 100644 docs/rental-webhook-405.md create mode 100644 ruoyi-system/src/main/java/com/ruoyi/system/controller/WebhookDebugTraceFilter.java diff --git a/docs/rental-address-onchain.md b/docs/rental-address-onchain.md index 382ae71..1ef536b 100644 --- a/docs/rental-address-onchain.md +++ b/docs/rental-address-onchain.md @@ -138,6 +138,8 @@ WAITING且没有任务表示尚未派单;已有PENDING任务则继续检查Soc ## 回调未到达排查(2026-11-02) +持续405的实际HTTP探测证据、关联日志和Nginx精确代理配置见[回调405定位](rental-webhook-405.md)。 + ### 调试接收端验签 `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时可再次观察。 diff --git a/docs/rental-webhook-405.md b/docs/rental-webhook-405.md new file mode 100644 index 0000000..e6ad58c --- /dev/null +++ b/docs/rental-webhook-405.md @@ -0,0 +1,55 @@ +# 租赁回调405定位与HTTP入口配置 + +## 已复现证据 + +2026-11-02从开发环境发送POST到`http://192.168.3.103/api/api/webhook/debug`,实际返回HTTP405、Server nginx/1.24.0 (Ubuntu)、Content-Type text/html以及Nginx默认405页面。直连`192.168.3.103:2020`超时。证据指向HTTP入口代理/静态路由,尚未取得运行服务器的Nginx配置,不能仅凭Server头断定具体location;代理也可能替换上游错误页。开发环境无法直连2020不等于服务器本地也无法连接。 + +## 新日志如何定位 + +发送端“租赁回调请求开始”包含随机`callbackId`、实际POST、协议、主机、端口和签名路径;“响应来源”记录Server、Allow、X-Rent-Debug-Backend、响应关联ID与上游traceId,不记录凭据、正文或Cookie。 + +接收端`WebhookDebugTraceFilter`在MVC路由匹配前记录“租赁调试回调入口”,出口记录HTTP状态和匹配Controller。即使认证尚未配置或MVC返回405也能记录。响应头`X-Rent-Debug-Backend: ruoyi-webhook-debug-v1`表示经过当前版本调试回调过滤器,不能替代验签,也不证明已进入Controller。缺标记时还需考虑代理剥离响应头或错误页替换,用接收端callbackId日志进一步判断。 + +- 无入口日志:检查Nginx实际HTTP server/location、是否落入前端静态页、是否指向旧实例。 +- 入口方法不是POST:检查proxy_method、rewrite/error_page内部跳转及其他代理。 +- 入口POST且405:查看出口handler、后端运行版本、路由与过滤器。 +- 返回401或503:已经进入验签接收端,应继续配置凭证/签名路径,不再是HTTP方法问题。 + +## 服务器本地验证及修正 + +先在运行后端的服务器执行,使用无签名测试正文不会更新订单: + +```bash +curl -i --connect-timeout 3 --max-time 10 \ + -X POST http://127.0.0.1:2020/api/webhook/debug \ + -H 'Content-Type: application/json' -d '{}' +sudo nginx -T +``` + +新版后端在缺凭证时应返回503,配置凭证但无签名返回401,并带后端标记;不应返回405。不要为测试返回ok而关闭验签。 + +如果Nginx和后端同机、后端端口为2020,在实际监听80、匹配192.168.3.103的server块添加以下精确location(不是放在只监听443的server块): + +```nginx +location = /api/api/webhook/debug { + proxy_pass http://127.0.0.1:2020/api/webhook/debug; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Rent-Callback-Id $http_x_rent_callback_id; + proxy_intercept_errors off; + proxy_connect_timeout 5s; + proxy_read_timeout 10s; +} +``` + +不同机器部署须替换为Nginx能访问的真实后端地址。保持POST方法和正文默认透传,不使用proxy_method GET或关闭proxy_pass_request_body;不要用error_page 405返回200掩盖故障。若server级存在统一return/rewrite,应确保回调请求不会在location处理前被改写到其他地址。 + +```bash +sudo nginx -t && sudo systemctl reload nginx +curl -i --connect-timeout 3 --max-time 10 \ + -X POST http://192.168.3.103/api/api/webhook/debug \ + -H 'Content-Type: application/json' -d '{}' +``` + +外部notify_url不变,验签配置仍使用`RENT_WEBHOOK_DEBUG_SIGNATURE_PATH=/api/api/webhook/debug`,而后端实际接收路径为`/api/webhook/debug`。确认无签名测试返回401/503后再通过正式回调验签验证ok;DEAD事件使用管理员已有重投入口,不能重新扣款或重置业务订单。 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 index ebe8e7d..d595c65 100644 --- 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 @@ -2,6 +2,7 @@ package com.ruoyi.web.controller.system; import com.fasterxml.jackson.databind.ObjectMapper; import com.ruoyi.system.controller.WebhookDebugController; +import com.ruoyi.system.controller.WebhookDebugTraceFilter; import com.ruoyi.system.rental.RentalCrypto; import com.ruoyi.system.rental.RentalStore; import org.junit.Test; @@ -58,8 +59,11 @@ public class WebhookDebugControllerTest { } @Test public void postMappingAndMissingConfigurationAreExplicit() throws Exception { - MockMvc mvc = MockMvcBuilders.standaloneSetup(controller).build(); - mvc.perform(get("/api/webhook/debug")).andExpect(status().isMethodNotAllowed()); + MockMvc mvc = MockMvcBuilders.standaloneSetup(controller).addFilters(new WebhookDebugTraceFilter()).build(); + mvc.perform(get("/api/webhook/debug").header("X-Rent-Callback-Id", "test-callback")) + .andExpect(status().isMethodNotAllowed()) + .andExpect(header().string("X-Rent-Debug-Backend", "ruoyi-webhook-debug-v1")) + .andExpect(header().string("X-Rent-Callback-Id", "test-callback")); mvc.perform(post("/api/webhook/debug").contentType("application/json").content(body)) .andExpect(status().isServiceUnavailable()); configure(); diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/controller/WebhookDebugTraceFilter.java b/ruoyi-system/src/main/java/com/ruoyi/system/controller/WebhookDebugTraceFilter.java new file mode 100644 index 0000000..ceece1c --- /dev/null +++ b/ruoyi-system/src/main/java/com/ruoyi/system/controller/WebhookDebugTraceFilter.java @@ -0,0 +1,50 @@ +package com.ruoyi.system.controller; + +import java.io.IOException; +import javax.servlet.FilterChain; +import javax.servlet.ServletException; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpServletResponse; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; +import org.springframework.web.filter.OncePerRequestFilter; +import org.springframework.web.method.HandlerMethod; +import org.springframework.web.servlet.HandlerMapping; + +/** 在MVC匹配之前记录调试回调:即使405未进入Controller,也能判断是否到达本服务。 */ +@Component +@Order(org.springframework.core.Ordered.HIGHEST_PRECEDENCE + 20) +public class WebhookDebugTraceFilter extends OncePerRequestFilter { + private static final Logger LOG = LoggerFactory.getLogger(WebhookDebugTraceFilter.class); + + @Override + protected boolean shouldNotFilter(HttpServletRequest request) { + String path = request.getRequestURI().substring(request.getContextPath().length()); + return !"/api/webhook/debug".equals(path) && !"/api/api/webhook/debug".equals(path); + } + + @Override + protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) + throws ServletException, IOException { + String incoming = request.getHeader("X-Rent-Callback-Id"); + String correlation = incoming != null && incoming.matches("[A-Za-z0-9_-]{1,64}") + ? incoming : java.util.UUID.randomUUID().toString(); + response.setHeader("X-Rent-Debug-Backend", "ruoyi-webhook-debug-v1"); + response.setHeader("X-Rent-Callback-Id", correlation); + long started = System.nanoTime(); + LOG.info("租赁调试回调入口 callbackId={} method={} path={} localPort={} contentLength={}", + correlation, request.getMethod(), request.getRequestURI(), request.getLocalPort(), request.getContentLengthLong()); + try { + chain.doFilter(request, response); + } finally { + Object handler = request.getAttribute(HandlerMapping.BEST_MATCHING_HANDLER_ATTRIBUTE); + String matched = handler instanceof HandlerMethod + ? ((HandlerMethod) handler).getBeanType().getSimpleName() + "#" + ((HandlerMethod) handler).getMethod().getName() + : "NO_CONTROLLER_MATCH"; + LOG.info("租赁调试回调出口 callbackId={} method={} status={} handler={} elapsedMs={}", + correlation, request.getMethod(), response.getStatus(), matched, (System.nanoTime() - started) / 1000000); + } + } +} diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalWorkers.java b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalWorkers.java index 5ab3490..b5c176b 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalWorkers.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalWorkers.java @@ -319,9 +319,11 @@ public class RentalWorkers { String nonce = RentalCrypto.random(); String body = text(row, "payload"); long timestamp = System.currentTimeMillis(); + String callbackId = java.util.UUID.randomUUID().toString(); Request request = new Request.Builder() .url(url) + .header("X-Rent-Callback-Id", callbackId) .header("X-Rent-Key", key) .header("X-Rent-Timestamp", Long.toString(timestamp)) .header("X-Rent-Nonce", nonce) @@ -341,8 +343,8 @@ public class RentalWorkers { MediaType.parse("application/json"), body)) .build(); stage = "HTTP_EXECUTE"; - LOG.info("租赁回调请求开始 webhookId={} orderId={} method=POST path={} connectTimeoutMs=5000 callTimeoutMs=10000", - id, row.get("order_id"), parsed.encodedPath()); + LOG.info("租赁回调请求开始 webhookId={} orderId={} callbackId={} method={} scheme={} host={} port={} path={} contentType=application/json followRedirects=false connectTimeoutMs=5000 callTimeoutMs=10000", + id, row.get("order_id"), callbackId, request.method(), parsed.scheme(), parsed.host(), parsed.port(), parsed.encodedPath()); OkHttpClient client = parsed.isHttps() ? callbacks : privateHttpCallbacks; try (Response response = client.newCall(request).execute()) { LOG.info("租赁回调收到HTTP响应 webhookId={} httpStatus={} contentType={} contentLength={} elapsedMs={}", @@ -350,8 +352,18 @@ public class RentalWorkers { response.body() == null ? -1 : response.body().contentLength(), (System.nanoTime() - started) / 1000000); stage = "RESPONSE_ACK"; + // 仅记录白名单响应头,不记录Location、Cookie、认证头或错误正文。 + LOG.info("租赁回调响应来源 webhookId={} callbackId={} actualMethod={} actualPath={} server={} allow={} backendMarker={} responseCallbackId={} upstreamTraceId={}", + id, callbackId, response.request().method(), response.request().url().encodedPath(), + callbackHeader(response, "Server"), callbackHeader(response, "Allow"), + callbackHeader(response, "X-Rent-Debug-Backend"), callbackHeader(response, "X-Rent-Callback-Id"), + callbackHeader(response, "X-Trace-Id")); if (response.code() != 200) { failure = "HTTP_STATUS_" + response.code(); + if (response.code() == 405) { + LOG.warn("租赁回调方法被拒绝 webhookId={} callbackId={} reason=HTTP_STATUS_405;按callbackId查接收端入口/出口日志。无入口则检查代理路由、静态服务或旧实例;入口method非POST则检查代理改写;入口POST且405则检查运行版本、MVC映射及过滤器。backendMarker={}", + id, callbackId, callbackHeader(response, "X-Rent-Debug-Backend")); + } } else { String responseBody = RentalHttp.body(response); acked = "ok".equals(responseBody); @@ -386,6 +398,13 @@ public class RentalWorkers { } } + /** 响应头属于不可信输入,限制长度和字符,防止伪造日志或无界输出。 */ + private static String callbackHeader(Response response, String name) { + String value = response.header(name); + if (value == null) return "[absent]"; + return value.substring(0, Math.min(value.length(), 160)).replaceAll("[^A-Za-z0-9 _.,;:/()=+\\-]", "_"); + } + /** 仅返回固定原因码,底层异常原文可能包含URL、响应体或凭据,禁止直接存储或打印。 */ static String callbackFailure(Throwable error, String stage) { Set visited = Collections.newSetFromMap(new IdentityHashMap());