diff --git a/docs/rental-address-onchain.md b/docs/rental-address-onchain.md index fb7e260..784ec91 100644 --- a/docs/rental-address-onchain.md +++ b/docs/rental-address-onchain.md @@ -136,6 +136,23 @@ ORDER BY w.id; WAITING且没有任务表示尚未派单;已有PENDING任务则继续检查Socket推送和Agent接收日志。EXECUTING/UNKNOWN已有在途任务时,不允许手动重置订单或另建交易。更新服务端后,仍在派单期限内的WAITING订单由扫描自动重试;已超时取消的订单不会自动恢复。 +## 回调未到达排查(2026-11-02) + +在服务端日志中按 `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等也会被拒绝。 +- `TLS_CERTIFICATE_OR_HANDSHAKE_FAILED`:HTTPS握手或证书验证失败。 +- `DNS_RESOLUTION_FAILED`、`CONNECTION_FAILED`、`TIMEOUT_OR_INTERRUPTED`:分别核对DNS、端口和网络超时。 +- `NO_VALID_CREDENTIAL_OR_LOOKUP_FAILED`:检查订单所属应用是否有ACTIVE且未过期凭证及数据库状态。 +- `HTTP_STATUS_301/302/404/401/...`:请求已收到HTTP响应,检查代理路由/登录拦截;不会自动跟随重定向。`/api/api/webhook/debug`是否正确取决于Nginx前缀转发,不自动删减路径。 +- `ACK_BODY_NOT_EXACT_OK`:要求HTTP200且响应正文严格为小写`ok`,JSON包装、HTML或多余换行均不确认。 + +扫描每5秒执行,仅领取已到`next_attempt_at`且租约可用的PENDING/SENDING记录。失败退避重试,累计10次进入DEAD;管理员通过已有回调重投功能重新投递DEAD事件,不直接修改订单或删除回调记录。没有回调URL时沿用既有跳过发送并确认的行为,日志标记`EMPTY_NOTIFY_URL`。 + +内网回调配置为`rental.webhook.allow-private-network: ${RENT_WEBHOOK_ALLOW_PRIVATE_NETWORK:true}`,按当前需求默认开启,修改后重启服务生效;设为false恢复仅公网策略。`https://192.168.3.103/api/api/webhook/debug`可通过内网地址检查,实际路由仍取决于Nginx配置。HTTPS证书链和IP SAN仍须有效并被服务端JVM信任,开启内网不跳过证书校验;回调仍仅允许443端口,禁止重定向。 + +诊断定向测试3项通过,覆盖内网开关、私网及IPv6 ULA放行、特殊地址继续拒绝和网络/凭证错误分类;未连接实际回调目标或操作生产数据。 + ## 验证记录(2026-10-29) 地址上链派单修复回归:JDK8离线执行 `RentalBusinessTest,RentalOnchainTest`,67项通过、0失败、0错误。新增覆盖无资源快照派单并完成独立核验扣款、过期快照不阻止转账但阻止资源委托,以及无快照下身份/网络/在线心跳/授权/余额保护。本次未进行真实链上广播或生产部署。 diff --git a/docs/rental/implementation.md b/docs/rental/implementation.md index f82c25f..1f28980 100644 --- a/docs/rental/implementation.md +++ b/docs/rental/implementation.md @@ -129,7 +129,7 @@ SHA256(实际UTF-8请求体)的小写十六进制 跨语言固定向量: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。 +回调使用相同请求头但scope=WEBHOOK;仅HTTPS 443、无用户信息/fragment/query,实际DNS连接地址逐个检查,不跟随重定向。`rental.webhook.allow-private-network`通过`RENT_WEBHOOK_ALLOW_PRIVATE_NETWORK`控制,当前默认true,允许IPv4私网和IPv6 ULA;false恢复仅公网,回环、链路本地等特殊目标始终拒绝。HTTPS证书校验保持开启。HTTP200且正文精确为 `ok` 才确认。最多10次,失败指数退避,终止为DEAD;每次新timestamp/nonce,业务event_no、payload和订单事件序号不变。商户按event_no去重并按序号识别乱序。无回调地址的事件直接确认,不发HTTP。 ## 7. WSS协议与历史资源证明 diff --git a/ruoyi-admin/src/main/resources/application-rental.yml b/ruoyi-admin/src/main/resources/application-rental.yml index 19fe7f1..9e2447a 100644 --- a/ruoyi-admin/src/main/resources/application-rental.yml +++ b/ruoyi-admin/src/main/resources/application-rental.yml @@ -5,6 +5,9 @@ rental: master-key: ${RENT_MASTER_KEY:ZA+5tLy20rbLxsMEvVm7Ow9hl2qtAPD3nmiK1Tf52NA=} master-key-version: ${RENT_MASTER_KEY_VERSION:v1} confirmations: ${RENT_CONFIRMATIONS:19} + webhook: + # 允许192.168/10/172.16~31及IPv6 ULA内网HTTPS回调;仍验证证书,拒绝回环/链路本地及重定向。 + allow-private-network: ${RENT_WEBHOOK_ALLOW_PRIVATE_NETWORK:true} # 正常在线、无排队且RPC及时返回时,调度+推送等待约0~5秒,目标10秒左右接单。 # 均为上轮执行完成后的等待时间;链上查询耗时不包含在间隔中。修改后重启服务端。 delivery: diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalHttp.java b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalHttp.java index d2f9ee7..bb67746 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalHttp.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalHttp.java @@ -14,6 +14,15 @@ import java.util.concurrent.TimeUnit; public final class RentalHttp { private RentalHttp() {} + /** 独立异常类型用于安全诊断,不依赖可能含目标URL或凭证的底层异常原文。 */ + public static final class CallbackTargetRejectedException extends java.net.UnknownHostException { + private static final long serialVersionUID = 1L; + + CallbackTargetRejectedException() { + super("回调目标非公网地址"); + } + } + public static void checkUrl(String url) { URI uri = URI.create(url); require( @@ -54,6 +63,15 @@ public final class RentalHttp { } public static OkHttpClient callbackClient() { + return callbackClient(false); + } + + /** + * 允许配置启用内网业务回调(IPv4私网和IPv6 ULA)。 + * 始终拒绝回环、链路本地、未指定及组播地址;HTTPS证书校验和禁止重定向保持有效。 + * 对解析出的每个地址校验,并将同一结果用于连接,避免校验与连接使用不同DNS结果。 + */ + public static OkHttpClient callbackClient(boolean allowPrivateNetwork) { return new OkHttpClient.Builder() .connectTimeout(5, TimeUnit.SECONDS) .readTimeout(5, TimeUnit.SECONDS) @@ -65,8 +83,8 @@ public final class RentalHttp { host -> { InetAddress[] addresses = InetAddress.getAllByName(host); for (InetAddress address : addresses) { - if (!publicAddress(address)) { - throw new java.net.UnknownHostException("回调目标非公网地址"); + if (!callbackAddressAllowed(address, allowPrivateNetwork)) { + throw new CallbackTargetRejectedException(); } } return Arrays.asList(addresses); @@ -74,6 +92,24 @@ public final class RentalHttp { .build(); } + static boolean callbackAddressAllowed(InetAddress address, boolean allowPrivateNetwork) { + if (publicAddress(address)) { + return true; + } + if (!allowPrivateNetwork || address.isAnyLocalAddress() || address.isLoopbackAddress() + || address.isLinkLocalAddress() || address.isMulticastAddress()) { + return false; + } + byte[] bytes = address.getAddress(); + if (bytes.length == 16) { + return (bytes[0] & 0xfe) == 0xfc; + } + int first = bytes[0] & 255; + int second = bytes[1] & 255; + return first == 10 || (first == 172 && second >= 16 && second <= 31) + || (first == 192 && second == 168); + } + public static String body(Response response) throws IOException { return body(response, 1024 * 1024); } 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 558b0b3..b5cac95 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 @@ -22,7 +22,9 @@ public class RentalWorkers { private final RentalTasks tasks; private final RentalSocket socket; private final RentalIdentity identity; - private final OkHttpClient callbacks = RentalHttp.callbackClient(); + private OkHttpClient callbacks = RentalHttp.callbackClient(); + @org.springframework.beans.factory.annotation.Value("${rental.webhook.allow-private-network:true}") + private boolean allowPrivateNetwork = true; private long walletCursor; private long monitoringCursor; private long dispatchCursor; @@ -37,6 +39,7 @@ public class RentalWorkers { /** 启动即校验,避免配置为零造成热循环或过大造成难以定位的交付延迟。 */ @javax.annotation.PostConstruct public void validateDeliveryIntervals() { + callbacks = RentalHttp.callbackClient(allowPrivateNetwork); require(dispatchIntervalMs >= 500 && dispatchIntervalMs <= 60000, "订单调度间隔必须为500到60000毫秒"); require(pushIntervalMs >= 500 && pushIntervalMs <= 60000, @@ -44,6 +47,8 @@ public class RentalWorkers { LOG.info("租赁交付调度配置 dispatchIntervalMs={} pushIntervalMs={}", dispatchIntervalMs, pushIntervalMs); LOG.info("租赁快照定时扫描已启用 intervalMs=15000 batchSize=20,刷新ACTIVE且快照缺失或过期的钱包"); + LOG.info("租赁回调扫描已启用 intervalMs=5000 batchSize=20 maxAttempts=10 allowPrivateNetwork={};HTTPS证书校验开启,拒绝重定向、回环及链路本地地址,要求HTTP200且正文严格为ok", + allowPrivateNetwork); } @org.springframework.beans.factory.annotation.Autowired @@ -272,16 +277,31 @@ public class RentalWorkers { return store.get("webhook", id, false); }); if (row == null) { + LOG.debug("租赁回调跳过 webhookId={} reason=LEASE_NOT_ACQUIRED", id); continue; } boolean acked = false; + long started = System.nanoTime(); + String stage = "ORDER_LOAD"; + String failure = ""; + LOG.info("租赁回调已领取 webhookId={} orderId={} eventNo={} attempt={} payloadBytes={}", + id, row.get("order_id"), row.get("event_no"), row.get("attempt_count"), + text(row, "payload").getBytes(java.nio.charset.StandardCharsets.UTF_8).length); try { Map order = store.get("order", number(row, "order_id"), false); String url = text(order, "notify_url"); if (url.isEmpty()) { acked = true; + LOG.info("租赁回调无需发送 webhookId={} orderId={} reason=EMPTY_NOTIFY_URL", id, row.get("order_id")); } else { + stage = "URL_CHECK"; RentalHttp.checkUrl(url); + HttpUrl parsed = HttpUrl.parse(url); + require(parsed != null && parsed.query() == null, "回调URL不允许查询串"); + // 只打印已校验URL的主机与路径,绝不打印查询串、用户信息或请求头凭证。 + LOG.info("租赁回调目标检查通过 webhookId={} appId={} scheme={} host={} port={} path={}", + id, order.get("app_id"), parsed.scheme(), parsed.host(), parsed.port(), parsed.encodedPath()); + stage = "CREDENTIAL_LOOKUP"; Map credential = store.one( "SELECT * FROM rent_credential WHERE owner_type='APP' AND" @@ -290,12 +310,13 @@ public class RentalWorkers { order.get("app_id"), now()); require(credential != null, "无有效回调凭证"); + LOG.info("租赁回调凭证已找到 webhookId={} credentialId={} appId={}", + id, credential.get("id"), order.get("app_id")); + stage = "SIGN_REQUEST"; String key = text(credential, "api_key"); String nonce = RentalCrypto.random(); String body = text(row, "payload"); long timestamp = System.currentTimeMillis(); - HttpUrl parsed = HttpUrl.parse(url); - require(parsed != null && parsed.query() == null, "回调URL不允许查询串"); Request request = new Request.Builder() .url(url) @@ -317,24 +338,61 @@ public class RentalWorkers { RequestBody.create( 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()); try (Response response = callbacks.newCall(request).execute()) { - acked = response.code() == 200 && "ok".equals(RentalHttp.body(response)); + LOG.info("租赁回调收到HTTP响应 webhookId={} httpStatus={} contentType={} contentLength={} elapsedMs={}", + id, response.code(), response.body() == null ? "" : response.body().contentType(), + response.body() == null ? -1 : response.body().contentLength(), + (System.nanoTime() - started) / 1000000); + stage = "RESPONSE_ACK"; + if (response.code() != 200) { + failure = "HTTP_STATUS_" + response.code(); + } else { + String responseBody = RentalHttp.body(response); + acked = "ok".equals(responseBody); + if (!acked) { + failure = "ACK_BODY_NOT_EXACT_OK"; + } + } } } } catch (Exception ex) { - /* 不记录URL、签名或响应原文,保留同一事件下次重试。 */ + failure = callbackFailure(ex, stage); + LOG.warn("租赁回调异常 webhookId={} orderId={} stage={} reason={} elapsedMs={} diagnostic={}", + id, row.get("order_id"), stage, failure, (System.nanoTime() - started) / 1000000, + RentalDiagnostics.describe(ex)); } int attempt = (int) number(row, "attempt_count"); - store.execute( + String nextStatus = acked ? "ACKED" : attempt >= 10 ? "DEAD" : "PENDING"; + java.time.LocalDateTime nextAttempt = after(Math.min(3600, 1L << Math.min(attempt, 11))); + int updated = store.execute( "UPDATE rent_webhook SET" + " status=?,next_attempt_at=?,lock_owner=NULL,lock_until=NULL,last_error=?,version=version+1,updated_at=?" + " WHERE id=? AND lock_owner=?", - acked ? "ACKED" : attempt >= 10 ? "DEAD" : "PENDING", - after(Math.min(3600, 1L << Math.min(attempt, 11))), - acked ? null : "回调未确认,请核对凭证、目标网络和响应", + nextStatus, + nextAttempt, + acked ? null : "stage=" + stage + "; reason=" + failure, now(), id, lease); + LOG.info("租赁回调处理结束 webhookId={} orderId={} attempt={} status={} reason={} nextAttemptAt={} updatedRows={} elapsedMs={}", + id, row.get("order_id"), attempt, nextStatus, acked ? "ACKNOWLEDGED" : failure, + "PENDING".equals(nextStatus) ? nextAttempt : null, updated, (System.nanoTime() - started) / 1000000); } } + + /** 仅返回固定原因码,底层异常原文可能包含URL、响应体或凭据,禁止直接存储或打印。 */ + static String callbackFailure(Throwable error, String stage) { + Set visited = Collections.newSetFromMap(new IdentityHashMap()); + for (int depth = 0; error != null && depth < 8 && visited.add(error); depth++, error = error.getCause()) { + if (error instanceof RentalHttp.CallbackTargetRejectedException) return "TARGET_NOT_PUBLIC"; + if (error instanceof javax.net.ssl.SSLException) return "TLS_CERTIFICATE_OR_HANDSHAKE_FAILED"; + if (error instanceof java.net.UnknownHostException) return "DNS_RESOLUTION_FAILED"; + if (error instanceof java.net.ConnectException) return "CONNECTION_FAILED"; + if (error instanceof java.io.InterruptedIOException) return "TIMEOUT_OR_INTERRUPTED"; + } + return "CREDENTIAL_LOOKUP".equals(stage) ? "NO_VALID_CREDENTIAL_OR_LOOKUP_FAILED" : "STAGE_FAILED"; + } } diff --git a/ruoyi-system/src/test/java/com/ruoyi/system/rental/RentalWebhookDiagnosticsTest.java b/ruoyi-system/src/test/java/com/ruoyi/system/rental/RentalWebhookDiagnosticsTest.java new file mode 100644 index 0000000..370b17c --- /dev/null +++ b/ruoyi-system/src/test/java/com/ruoyi/system/rental/RentalWebhookDiagnosticsTest.java @@ -0,0 +1,47 @@ +package com.ruoyi.system.rental; + +import org.junit.Test; +import static org.junit.Assert.*; + +/** 诊断不能只留下笼统失败,也不得依赖可能包含凭证的异常原文。 */ +public class RentalWebhookDiagnosticsTest { + @Test + public void privateTargetIsRejectedBeforeConnectionAndClassified() throws Exception { + try { + RentalHttp.callbackClient().dns().lookup("192.168.3.103"); + fail("内网目标必须被现有回调策略拒绝"); + } catch (RentalHttp.CallbackTargetRejectedException ex) { + assertEquals("TARGET_NOT_PUBLIC", RentalWorkers.callbackFailure(ex, "HTTP_EXECUTE")); + } + } + + @Test + public void enabledPrivateCallbacksAllowBusinessNetworksButKeepSpecialAddressesBlocked() throws Exception { + okhttp3.OkHttpClient client = RentalHttp.callbackClient(true); + for (String host : new String[] {"192.168.3.103", "10.0.0.1", "172.16.0.1", "fd00::1"}) { + assertFalse(client.dns().lookup(host).isEmpty()); + } + for (String host : new String[] {"127.0.0.1", "::1", "169.254.169.254", "0.0.0.0", "224.0.0.1"}) { + try { + client.dns().lookup(host); + fail("特殊用途目标仍应拒绝:" + host); + } catch (RentalHttp.CallbackTargetRejectedException expected) { + // 开启内网只扩大业务私网范围,不关闭所有地址检查。 + } + } + assertFalse(client.followRedirects()); + assertFalse(client.followSslRedirects()); + } + + @Test + public void networkAndCredentialErrorsHaveSafeDistinctReasons() { + assertEquals("TLS_CERTIFICATE_OR_HANDSHAKE_FAILED", RentalWorkers.callbackFailure( + new javax.net.ssl.SSLHandshakeException("secret must not appear"), "HTTP_EXECUTE")); + assertEquals("DNS_RESOLUTION_FAILED", RentalWorkers.callbackFailure( + new java.net.UnknownHostException("secret must not appear"), "HTTP_EXECUTE")); + assertEquals("TIMEOUT_OR_INTERRUPTED", RentalWorkers.callbackFailure( + new java.net.SocketTimeoutException("secret must not appear"), "HTTP_EXECUTE")); + assertEquals("NO_VALID_CREDENTIAL_OR_LOOKUP_FAILED", RentalWorkers.callbackFailure( + new IllegalArgumentException("secret must not appear"), "CREDENTIAL_LOOKUP")); + } +}