回调问题处理

This commit is contained in:
lu7213 committed 2026-11-02 22:34:18 -05:00
1 parent 43dec4c94b
commit 1151dc2535
7 files changed
+99 -16

No files matched your search

+5 -2
View File
@@ -142,17 +142,20 @@ WAITING且没有任务表示尚未派单;已有PENDING任务则继续检查Soc
### 调试接收端验签 ### 调试接收端验签
`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时可再次观察。 `WebhookDebugController`的`POST /api/webhook/debug`仅接收application/json。使用原始UTF-8正文和X-Rent-Key/Timestamp/Nonce/Signature请求头,复用租赁WEBHOOK域HMAC-SHA256协议,允许时间偏差小于60秒;正文上限512KiB。GET返回405,CONFIGURED模式缺凭证或存储故障503,认证失败401,事件JSON无效400,nonce重放409;仅验签及持久化nonce成功返回纯文本ok。不更新业务订单,不用于正式记账,合法事件重投携带新nonce时可再次观察。
```yaml ```yaml
rental: rental:
webhook-debug: webhook-debug:
credential-source: ${RENT_WEBHOOK_DEBUG_CREDENTIAL_SOURCE:APP}
api-key: ${RENT_WEBHOOK_DEBUG_API_KEY:} api-key: ${RENT_WEBHOOK_DEBUG_API_KEY:}
api-secret: ${RENT_WEBHOOK_DEBUG_API_SECRET:} api-secret: ${RENT_WEBHOOK_DEBUG_API_SECRET:}
signature-path: ${RENT_WEBHOOK_DEBUG_SIGNATURE_PATH:} 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端口。 默认APP模式按请求X-Rent-Key查询本系统ACTIVE且未过期的APP凭证并解密Secret验签,不需要填写固定api-key/api-secret;未知、NODE、停用或过期凭证拒绝。适用于同系统调试,能够验证各应用轮换后的真实签名,不能作为外部商户生产回调的身份授权模型。CONFIGURED模式使用上面的固定凭证,必须与发送器当前选择的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端口。
认证诊断不再合并为“通知认证参数无效”:分别记录KEY_MISSING、KEY_MISMATCH、ACTIVE_APP_CREDENTIAL_NOT_FOUND、NONCE_INVALID、TIMESTAMP_NOT_UNIX_MILLIS、TIMESTAMP_OUT_OF_WINDOW及SIGNATURE_MISMATCH_CHECK_SECRET_PATH_AND_BODY。日志提供Key不可逆摘要、时间差毫秒数、nonce长度,不记录认证原文。HTTP时间戳是Unix毫秒,与DATETIME存储时区无关,不允许手工加8小时或取消时间窗验证。独立demo接收端仍使用其固定配置,并返回具体参数校验说明。
在服务端日志中按 `webhookId` 或 `orderId` 查询“租赁回调”。日志依次包含领取次数/正文字节数、目标主机/路径、有效凭证记录ID、POST请求开始、HTTP响应状态/长度和最终状态;异常包含失败阶段及安全的异常类型/代码位置,不输出Secret、签名、请求正文或响应正文。`rent_webhook.last_error`同步保存固定阶段和原因码。 在服务端日志中按 `webhookId` 或 `orderId` 查询“租赁回调”。日志依次包含领取次数/正文字节数、目标主机/路径、有效凭证记录ID、POST请求开始、HTTP响应状态/长度和最终状态;异常包含失败阶段及安全的异常类型/代码位置,不输出Secret、签名、请求正文或响应正文。`rent_webhook.last_error`同步保存固定阶段和原因码。
+1 -1
View File
@@ -26,7 +26,7 @@ curl -i --connect-timeout 3 --max-time 10 \
sudo nginx -T sudo nginx -T
``` ```
新版后端在缺凭证时应返回503,配置凭证但无签名返回401,并带后端标记;不应返回405。不要为测试返回ok而关闭验签。 新版后端默认APP模式,无认证请求头应返回401;CONFIGURED模式缺凭证时返回503,有凭证但无签名返回401,并带后端标记;不应返回405。不要为测试返回ok而关闭验签。
如果Nginx和后端同机、后端端口为2020,在实际监听80、匹配192.168.3.103的server块添加以下精确location(不是放在只监听443的server块): 如果Nginx和后端同机、后端端口为2020,在实际监听80、匹配192.168.3.103的server块添加以下精确location(不是放在只监听443的server块):
@@ -9,7 +9,8 @@ rental:
# 允许192.168/10/172.16~31及IPv6 ULA内网HTTP/HTTPS回调;HTTP允许自定义端口,HTTPS仍验证证书。 # 允许192.168/10/172.16~31及IPv6 ULA内网HTTP/HTTPS回调;HTTP允许自定义端口,HTTPS仍验证证书。
allow-private-network: ${RENT_WEBHOOK_ALLOW_PRIVATE_NETWORK:true} allow-private-network: ${RENT_WEBHOOK_ALLOW_PRIVATE_NETWORK:true}
webhook-debug: webhook-debug:
# 填写发送回调使用的有效APP凭证;缺失返回503,不跳过验签。 # APP按请求Key读取当前有效应用凭证验签,避免轮换后固定Key不匹配;CONFIGURED使用下面的独立凭证。
credential-source: ${RENT_WEBHOOK_DEBUG_CREDENTIAL_SOURCE:APP}
api-key: ${RENT_WEBHOOK_DEBUG_API_KEY:} api-key: ${RENT_WEBHOOK_DEBUG_API_KEY:}
api-secret: ${RENT_WEBHOOK_DEBUG_API_SECRET:} api-secret: ${RENT_WEBHOOK_DEBUG_API_SECRET:}
# 签名使用外部URL路径;代理移除前缀时可填写/api/api/webhook/debug。 # 签名使用外部URL路径;代理移除前缀时可填写/api/api/webhook/debug。
@@ -5,6 +5,7 @@ import com.ruoyi.system.controller.WebhookDebugController;
import com.ruoyi.system.controller.WebhookDebugTraceFilter; import com.ruoyi.system.controller.WebhookDebugTraceFilter;
import com.ruoyi.system.rental.RentalCrypto; import com.ruoyi.system.rental.RentalCrypto;
import com.ruoyi.system.rental.RentalStore; import com.ruoyi.system.rental.RentalStore;
import com.ruoyi.system.rental.RentalIdentity;
import org.junit.Test; import org.junit.Test;
import org.springframework.dao.DuplicateKeyException; import org.springframework.dao.DuplicateKeyException;
import org.springframework.mock.web.MockHttpServletRequest; import org.springframework.mock.web.MockHttpServletRequest;
@@ -19,11 +20,13 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
/** 验证原文签名、代理路径、重放和HTTP方法,不连接真实数据库或回调目标。 */ /** 验证原文签名、代理路径、重放和HTTP方法,不连接真实数据库或回调目标。 */
public class WebhookDebugControllerTest { public class WebhookDebugControllerTest {
private final RentalStore store = mock(RentalStore.class); private final RentalStore store = mock(RentalStore.class);
private final WebhookDebugController controller = new WebhookDebugController(store, new ObjectMapper()); private final RentalIdentity identity = mock(RentalIdentity.class);
private final WebhookDebugController controller = new WebhookDebugController(store, new ObjectMapper(), identity);
private final String body = "{\"event_no\":\"WH-test\",\"event_type\":\"SUCCESS\"}"; private final String body = "{\"event_no\":\"WH-test\",\"event_type\":\"SUCCESS\"}";
private final String externalPath = "/api/api/webhook/debug"; private final String externalPath = "/api/api/webhook/debug";
private void configure() { private void configure() {
ReflectionTestUtils.setField(controller, "credentialSource", "CONFIGURED");
ReflectionTestUtils.setField(controller, "apiKey", "test-key"); ReflectionTestUtils.setField(controller, "apiKey", "test-key");
ReflectionTestUtils.setField(controller, "apiSecret", "test-secret"); ReflectionTestUtils.setField(controller, "apiSecret", "test-secret");
ReflectionTestUtils.setField(controller, "signaturePath", externalPath); ReflectionTestUtils.setField(controller, "signaturePath", externalPath);
@@ -59,6 +62,7 @@ public class WebhookDebugControllerTest {
} }
@Test public void postMappingAndMissingConfigurationAreExplicit() throws Exception { @Test public void postMappingAndMissingConfigurationAreExplicit() throws Exception {
ReflectionTestUtils.setField(controller, "credentialSource", "CONFIGURED");
MockMvc mvc = MockMvcBuilders.standaloneSetup(controller).addFilters(new WebhookDebugTraceFilter()).build(); MockMvc mvc = MockMvcBuilders.standaloneSetup(controller).addFilters(new WebhookDebugTraceFilter()).build();
mvc.perform(get("/api/webhook/debug").header("X-Rent-Callback-Id", "test-callback")) mvc.perform(get("/api/webhook/debug").header("X-Rent-Callback-Id", "test-callback"))
.andExpect(status().isMethodNotAllowed()) .andExpect(status().isMethodNotAllowed())
@@ -70,4 +74,26 @@ public class WebhookDebugControllerTest {
mvc.perform(post("/api/webhook/debug").contentType("application/json").content(body)) mvc.perform(post("/api/webhook/debug").contentType("application/json").content(body))
.andExpect(status().isUnauthorized()); .andExpect(status().isUnauthorized());
} }
@Test public void appModeUsesActualSigningCredentialInsteadOfStaleConfiguredKey() throws Exception {
configure();
ReflectionTestUtils.setField(controller, "credentialSource", "APP");
ReflectionTestUtils.setField(controller, "apiKey", "stale-key");
ReflectionTestUtils.setField(controller, "apiSecret", "stale-secret");
java.util.Map<String, Object> credential = new java.util.HashMap<>();
credential.put("api_key", "test-key");
when(store.one(anyString(), eq("test-key"), any())).thenReturn(credential);
when(identity.secret(credential)).thenReturn("test-secret");
assertEquals("ok", controller.receive(signed(body, System.currentTimeMillis(), externalPath)).getBody());
verify(identity).secret(credential);
verify(store).insert(eq("nonce"), argThat(values -> "test-key".equals(values.get("api_key"))));
}
@Test public void unknownOrInactiveAppKeyIsNotAccepted() throws Exception {
ReflectionTestUtils.setField(controller, "signaturePath", externalPath);
when(store.one(anyString(), eq("test-key"), any())).thenReturn(null);
assertEquals(401, controller.receive(signed(body, System.currentTimeMillis(), externalPath)).getStatusCodeValue());
verifyNoInteractions(identity);
verify(store, never()).insert(anyString(), anyMap());
}
} }
@@ -4,6 +4,8 @@ import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.ObjectMapper;
import com.ruoyi.system.rental.RentalCallbackDemoController; import com.ruoyi.system.rental.RentalCallbackDemoController;
import com.ruoyi.system.rental.RentalStore; import com.ruoyi.system.rental.RentalStore;
import com.ruoyi.system.rental.RentalIdentity;
import com.ruoyi.system.rental.RentalCrypto;
import com.ruoyi.system.rental.RentalValues; import com.ruoyi.system.rental.RentalValues;
import java.io.IOException; import java.io.IOException;
import java.nio.ByteBuffer; import java.nio.ByteBuffer;
@@ -27,6 +29,9 @@ public class WebhookDebugController {
private static final int MAX_BODY_BYTES = 512 * 1024; private static final int MAX_BODY_BYTES = 512 * 1024;
private final RentalStore store; private final RentalStore store;
private final ObjectMapper json; private final ObjectMapper json;
private final RentalIdentity identity;
@Value("${rental.webhook-debug.credential-source:APP}")
private String credentialSource = "APP";
@Value("${rental.webhook-debug.api-key:}") @Value("${rental.webhook-debug.api-key:}")
private String apiKey; private String apiKey;
@Value("${rental.webhook-debug.api-secret:}") @Value("${rental.webhook-debug.api-secret:}")
@@ -35,15 +40,21 @@ public class WebhookDebugController {
@Value("${rental.webhook-debug.signature-path:}") @Value("${rental.webhook-debug.signature-path:}")
private String signaturePath; private String signaturePath;
public WebhookDebugController(RentalStore store, ObjectMapper json) { public WebhookDebugController(RentalStore store, ObjectMapper json, RentalIdentity identity) {
this.store = store; this.store = store;
this.json = json; this.json = json;
this.identity = identity;
} }
@PostMapping(value = "/api/webhook/debug", consumes = MediaType.APPLICATION_JSON_VALUE, @PostMapping(value = "/api/webhook/debug", consumes = MediaType.APPLICATION_JSON_VALUE,
produces = MediaType.TEXT_PLAIN_VALUE) produces = MediaType.TEXT_PLAIN_VALUE)
public ResponseEntity<String> receive(HttpServletRequest request) throws IOException { public ResponseEntity<String> receive(HttpServletRequest request) throws IOException {
if (apiKey == null || apiKey.isEmpty() || apiSecret == null || apiSecret.isEmpty()) { boolean appCredentials = "APP".equalsIgnoreCase(credentialSource);
if (!appCredentials && !"CONFIGURED".equalsIgnoreCase(credentialSource)) {
LOG.warn("租赁调试回调拒绝 reason=INVALID_CREDENTIAL_SOURCE");
return ResponseEntity.status(503).body("invalid credential source");
}
if (!appCredentials && (apiKey == null || apiKey.isEmpty() || apiSecret == null || apiSecret.isEmpty())) {
LOG.warn("租赁调试回调拒绝 reason=CREDENTIAL_NOT_CONFIGURED"); LOG.warn("租赁调试回调拒绝 reason=CREDENTIAL_NOT_CONFIGURED");
return ResponseEntity.status(503).body("callback credentials not configured"); return ResponseEntity.status(503).body("callback credentials not configured");
} }
@@ -63,28 +74,65 @@ public class WebhookDebugController {
return ResponseEntity.status(413).body("payload too large"); return ResponseEntity.status(413).body("payload too large");
} }
final JsonNode event; final JsonNode event;
String verifiedKey = apiKey;
String stage = "SIGNATURE"; String stage = "SIGNATURE";
String authenticationReason = "BODY_ENCODING_INVALID";
try { try {
String body = StandardCharsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT) String body = StandardCharsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT)
.decode(ByteBuffer.wrap(buffer, 0, total)).toString(); .decode(ByteBuffer.wrap(buffer, 0, total)).toString();
RentalCallbackDemoController.verify(apiKey, apiSecret, request.getHeader("X-Rent-Key"), String key = request.getHeader("X-Rent-Key");
Long.parseLong(request.getHeader("X-Rent-Timestamp")), request.getHeader("X-Rent-Nonce"), String secret = apiSecret;
authenticationReason = "KEY_MISSING";
RentalValues.require(key != null && !key.isEmpty() && key.length() <= 128, "通知Key缺失或过长");
if (appCredentials) {
stage = "CREDENTIAL_LOOKUP";
authenticationReason = "ACTIVE_APP_CREDENTIAL_NOT_FOUND";
java.util.Map<String, Object> credential = store.one(
"SELECT * FROM rent_credential WHERE api_key=? AND owner_type='APP' AND status='ACTIVE'"
+ " AND (expires_at IS NULL OR expires_at>?)", key, RentalValues.now());
RentalValues.require(credential != null, "未找到有效应用凭证");
authenticationReason = "CREDENTIAL_DECRYPT_FAILED";
secret = identity.secret(credential);
verifiedKey = key;
}
stage = "SIGNATURE";
authenticationReason = "KEY_MISMATCH";
RentalValues.require(key.equals(verifiedKey), "通知Key不匹配");
String nonce = request.getHeader("X-Rent-Nonce");
authenticationReason = "NONCE_INVALID";
RentalValues.require(nonce != null && nonce.matches("[A-Za-z0-9_-]{16,64}"), "通知nonce格式无效");
authenticationReason = "TIMESTAMP_NOT_UNIX_MILLIS";
String rawTimestamp = request.getHeader("X-Rent-Timestamp");
RentalValues.require(rawTimestamp != null && rawTimestamp.matches("[0-9]{13}"), "通知时间戳格式无效");
long timestamp = Long.parseLong(rawTimestamp);
long now = System.currentTimeMillis();
LOG.info("租赁调试回调认证参数检查 source={} keyFingerprint={} timestampSkewMs={} nonceLength={} signaturePresent={}",
credentialSource, RentalCrypto.sha256(key).substring(0, 12), now - timestamp, nonce.length(),
request.getHeader("X-Rent-Signature") != null);
authenticationReason = "TIMESTAMP_OUT_OF_WINDOW";
RentalValues.require(timestamp > now - 60000 && timestamp < now + 60000, "通知时间戳超窗");
authenticationReason = "SIGNATURE_MISMATCH_CHECK_SECRET_PATH_AND_BODY";
RentalCallbackDemoController.verify(verifiedKey, secret, key,
timestamp, nonce,
path, body, request.getHeader("X-Rent-Signature"), System.currentTimeMillis()); path, body, request.getHeader("X-Rent-Signature"), System.currentTimeMillis());
stage = "EVENT_JSON"; stage = "EVENT_JSON";
authenticationReason = "EVENT_JSON_INVALID";
event = json.readTree(body); event = json.readTree(body);
RentalValues.require(event != null && event.isObject() && event.path("event_no").isTextual() RentalValues.require(event != null && event.isObject() && event.path("event_no").isTextual()
&& !event.path("event_no").asText().isEmpty() && !event.path("event_no").asText().isEmpty()
&& event.path("event_no").asText().length() <= 64, "通知事件无效"); && event.path("event_no").asText().length() <= 64, "通知事件无效");
} catch (Exception ex) { } catch (Exception ex) {
// 不输出异常原文、认证请求头、Secret、签名及正文。 // 不输出异常原文、认证请求头、Secret、签名及正文。
LOG.warn("租赁调试回调拒绝 stage={} reason=INVALID_NOTIFICATION exceptionType={}", LOG.warn("租赁调试回调拒绝 stage={} reason={} exceptionType={}",
stage, ex.getClass().getSimpleName()); stage, authenticationReason, ex.getClass().getSimpleName());
return ResponseEntity.status("SIGNATURE".equals(stage) ? 401 : 400).body("invalid notification"); return ResponseEntity.status("CREDENTIAL_LOOKUP".equals(stage)
&& !"ACTIVE_APP_CREDENTIAL_NOT_FOUND".equals(authenticationReason) ? 503
: "EVENT_JSON".equals(stage) ? 400 : 401).body("invalid notification");
} }
try { try {
// 独立scope和数据库唯一键跨实例防重放;合法事件重投使用新nonce。 // 独立scope和数据库唯一键跨实例防重放;合法事件重投使用新nonce。
// 此接口不执行记账,重复event_no允许观察;正式业务应另做事件幂等处理。 // 此接口不执行记账,重复event_no允许观察;正式业务应另做事件幂等处理。
store.insert("nonce", RentalValues.map("api_key", apiKey, "scope", "DEBUG_WEBHOOK", store.insert("nonce", RentalValues.map("api_key", verifiedKey, "scope", "DEBUG_WEBHOOK",
"nonce", request.getHeader("X-Rent-Nonce"), "expires_at", RentalValues.after(180))); "nonce", request.getHeader("X-Rent-Nonce"), "expires_at", RentalValues.after(180)));
} catch (DuplicateKeyException ex) { } catch (DuplicateKeyException ex) {
LOG.warn("租赁调试回调拒绝 reason=NONCE_REPLAY"); LOG.warn("租赁调试回调拒绝 reason=NONCE_REPLAY");
@@ -112,9 +112,13 @@ public class RentalCallbackDemoController {
/** 验证实际原文及WEBHOOK域;代理必须保留回调路径,不可二次序列化JSON。 */ /** 验证实际原文及WEBHOOK域;代理必须保留回调路径,不可二次序列化JSON。 */
public static void verify(String expectedKey, String secret, String key, long timestamp, public static void verify(String expectedKey, String secret, String key, long timestamp,
String nonce, String path, String body, String signature, long now) { String nonce, String path, String body, String signature, long now) {
require(expectedKey != null && !expectedKey.isEmpty() && secret != null && !secret.isEmpty() require(expectedKey != null && !expectedKey.isEmpty() && secret != null && !secret.isEmpty(),
&& expectedKey.equals(key) && nonce != null && nonce.matches("[A-Za-z0-9_-]{16,64}") "通知接收端凭证未配置");
&& timestamp > now - 60000 && timestamp < now + 60000, "通知认证参数无效"); require(key != null && !key.isEmpty(), "通知缺少X-Rent-Key");
require(expectedKey.equals(key), "通知API Key与接收端凭证不匹配");
require(nonce != null && nonce.matches("[A-Za-z0-9_-]{16,64}"), "通知nonce格式无效");
require(timestamp > now - 60000 && timestamp < now + 60000,
"通知时间戳超出60秒窗口,请使用Unix毫秒并同步服务器时钟");
require(RentalCrypto.equal(RentalCrypto.sign(secret, "WEBHOOK", key, timestamp, require(RentalCrypto.equal(RentalCrypto.sign(secret, "WEBHOOK", key, timestamp,
nonce, "POST", path, body), signature), "通知签名无效"); nonce, "POST", path, body), signature), "通知签名无效");
} }
@@ -368,6 +368,7 @@ public class RentalWorkers {
String responseBody = RentalHttp.body(response); String responseBody = RentalHttp.body(response);
acked = "ok".equals(responseBody); acked = "ok".equals(responseBody);
if (!acked) { if (!acked) {
LOG.error("responseBody {}",responseBody);
failure = "ACK_BODY_NOT_EXACT_OK"; failure = "ACK_BODY_NOT_EXACT_OK";
} }
} }