diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java b/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java index 6b7176e6c..bec31078f 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java +++ b/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java @@ -72,8 +72,11 @@ public class AdminApiGuardFilter extends OncePerRequestFilter { *
原因:桌面客户端(Python)直连这些接口且不带任何认证头,先于客户端发布开启会 * 让线上集采/跟价全线 401。待携带 X-Internal-Token 的新客户端铺开后,把开关置 true * (或把这些前缀从 USER_TOOL_PREFIXES 移除、直接无条件纳入)即可完成收紧。 + * + *
包级可见(不是 private):{@code ClientVersionGuardFilter} 复用同一份"桌面客户端直连的 + * 用户态前缀"口径。**这份清单改动会同时改动两个闸门的覆盖面**,改前先想清楚版本地板是否也该跟着变。 */ - private static final String[] USER_TOOL_PREFIXES = { + static final String[] USER_TOOL_PREFIXES = { "/api/collect-data", "/api/price-track", // 2026-09 全维度审查补:以下前缀此前完全在守卫范围之外。 diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java b/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java new file mode 100644 index 000000000..d1b2ee79c --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java @@ -0,0 +1,291 @@ +package com.nanri.aiimage.config; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.nanri.aiimage.common.api.ApiResponse; +import io.micrometer.core.instrument.Counter; +import io.micrometer.core.instrument.MeterRegistry; +import jakarta.servlet.FilterChain; +import jakarta.servlet.ServletException; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; +import lombok.extern.slf4j.Slf4j; +import org.springframework.beans.factory.ObjectProvider; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.core.Ordered; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; +import org.springframework.web.filter.OncePerRequestFilter; + +import java.io.IOException; +import java.util.LinkedHashMap; +import java.util.Map; +import java.util.Set; +import java.util.concurrent.ConcurrentHashMap; + +/** + * 客户端版本硬地板:桌面客户端(ShuFuAI)上报的 {@value #HEADER} 低于服务端最低支持版本时的判定点。 + * + *
此前全仓唯一的 {@code minClientVersion} 在 digitalhuman 模块里,而且只是个**存进库又原样 + * 吐回 VO 的字段**({@code DigitalHumanVersionService:86} 写入、{@code :258} 读出,两处都是透传, + * 全树没有一处比较过它),对桌面客户端的 API 面零约束。本类是那个缺口的真闸门。 + * + *
三档开关,默认态 = **现网零行为变更**: + *
受管前缀取自 {@link AdminApiGuardFilter#USER_TOOL_PREFIXES}(**同一份出处**,不复制清单: + * 那份常量记的正是"桌面客户端直连的用户态接口"),另加 {@value #CLIENT_ENTRY_PREFIX} + * ({@code /api/client}——客户端取凭据的第一跳,不在那份名单里,但它同样得能被地板挡住)。 + * {@code /api/version/**}(更新检查)与 {@code /api/admin/**}、{@code /api/internal/**} 一律**不在** + * 受管集合内:被拒的老客户端必须永远能拿到升级信息,否则闸门把自己变成砖。 + * + *
响应体沿用项目约定(HTTP 200 + {@code {success:false, code, message, data}},与 + * {@code GlobalExceptionHandler} 同形),业务码 {@value #CODE_TOO_OLD}:401/403 已被鉴权与 + * 越权占用,4011 是被顶下线,这里取同一族的 4012。 + * + *
紧急回退:把 {@code min-supported-version} 置空即可(无需重启改代码),或
+ * {@code aiimage.client-version.enforce=false} 退回纯记账。
+ */
+@Slf4j
+@Component
+@Order(Ordered.LOWEST_PRECEDENCE)
+public class ClientVersionGuardFilter extends OncePerRequestFilter {
+
+ /** 客户端自报版本的请求头(由 app_client 的 user_token 出口钩子注入,只对自家后端基址生效)。 */
+ public static final String HEADER = "X-Client-Version";
+
+ /** 低于地板时的业务码;与 {@code DeviceSessionPolicy.CODE_KICKED=4011} 同族。 */
+ public static final int CODE_TOO_OLD = 4012;
+
+ /** 取凭据那一跳:桌面端入口,不在 {@link AdminApiGuardFilter#USER_TOOL_PREFIXES} 里,单独补上。 */
+ static final String CLIENT_ENTRY_PREFIX = "/api/client";
+
+ /** 指标名:按 verdict(below/unreported/unparsable)与是否 enforce 打标签,装机分布由 version 标签给出。 */
+ static final String METRIC = "aiimage.client.version.floor";
+
+ private static final String VERDICT_BELOW = "below";
+ private static final String VERDICT_UNREPORTED = "unreported";
+ private static final String VERDICT_UNPARSABLE = "unparsable";
+
+ /** WARN 去重上限:版本号是有限集合,超上限后不再新增键(只继续计数),防无界增长。 */
+ private static final int WARN_KEYS_MAX = 64;
+
+ private final ObjectMapper objectMapper;
+ private final MeterRegistry meterRegistry;
+ private final Set 记账模式必须"只留痕不动响应"(chain 继续、响应体一个字节都不许多),执法模式必须"根本不放行"
+ * (chain 不前进 + 4012 体)。这两个断言分别挡住两类事故:只记账却顺手改了响应 = 现网故障;
+ * 想执法却只记了账 = 地板形同虚设。
+ *
+ * 重跑:{@code mvn -o test -Dtest=ClientVersionGuardFilterTest}(cwd = backend-java)。
+ */
+class ClientVersionGuardFilterTest {
+
+ private final ObjectMapper objectMapper = new ObjectMapper();
+
+ private ClientVersionGuardFilter filter(String minVersion, boolean enforce, boolean rejectUnreported,
+ MeterRegistry registry) {
+ ClientVersionGuardFilter filter = new ClientVersionGuardFilter(objectMapper, registry);
+ ReflectionTestUtils.setField(filter, "minSupportedVersion", minVersion);
+ ReflectionTestUtils.setField(filter, "enforce", enforce);
+ ReflectionTestUtils.setField(filter, "rejectUnreported", rejectUnreported);
+ return filter;
+ }
+
+ private ClientVersionGuardFilter accounting(String minVersion) {
+ return filter(minVersion, false, false, null);
+ }
+
+ private ClientVersionGuardFilter enforcing(String minVersion) {
+ return filter(minVersion, true, false, null);
+ }
+
+ private MockHttpServletRequest post(String uri, String reportedVersion) {
+ MockHttpServletRequest request = new MockHttpServletRequest("POST", uri);
+ if (reportedVersion != null) {
+ request.addHeader(ClientVersionGuardFilter.HEADER, reportedVersion);
+ }
+ return request;
+ }
+
+ private long counterValue(MeterRegistry registry, String verdict, String version) {
+ io.micrometer.core.instrument.Counter counter = registry.find(ClientVersionGuardFilter.METRIC)
+ .tag("verdict", verdict).tag("version", version).counter();
+ return counter == null ? 0L : (long) counter.count();
+ }
+
+ // ------------------------------------------------------------- 默认态:零行为变更
+
+ @Test
+ void minVersionUnsetMakesTheGateTotallyInert() throws Exception {
+ MeterRegistry registry = new SimpleMeterRegistry();
+ ClientVersionGuardFilter filter = filter("", false, false, registry);
+
+ // 一个明显"该被挡住"的老版本 + 一个不带版本的客户端核心入口:闸门惰性时都必须原样放行
+ for (MockHttpServletRequest request :
+ new MockHttpServletRequest[]{post("/api/shop-match/tasks/1/result", "1.0.0"),
+ post("/api/client/credentials", null)}) {
+ MockHttpServletResponse response = new MockHttpServletResponse();
+ MockFilterChain chain = new MockFilterChain();
+ filter.doFilter(request, response, chain);
+ assertThat(chain.getRequest()).as("%s 应被放行", request.getRequestURI()).isNotNull();
+ assertThat(response.getContentAsByteArray()).isEmpty();
+ }
+ assertThat(registry.find(ClientVersionGuardFilter.METRIC).counter()).isNull();
+ }
+
+ @Test
+ void nonClientFacingPathsAreNeverJudged() throws Exception {
+ MeterRegistry registry = new SimpleMeterRegistry();
+ ClientVersionGuardFilter filter = filter("4.0.46", true, true, registry);
+
+ // 执法模式、且 unreported 也拒:这三类面一条都不许被 judge
+ for (MockHttpServletRequest request : new MockHttpServletRequest[]{
+ post("/api/version/latest", "1.0.0"),
+ post("/api/admin/users", "1.0.0"),
+ post("/api/internal/user-proxy", null)}) {
+ MockHttpServletResponse response = new MockHttpServletResponse();
+ MockFilterChain chain = new MockFilterChain();
+ filter.doFilter(request, response, chain);
+ assertThat(chain.getRequest()).as("%s 不在受管面内", request.getRequestURI()).isNotNull();
+ assertThat(response.getContentAsByteArray()).isEmpty();
+ }
+ assertThat(registry.find(ClientVersionGuardFilter.METRIC).counter()).isNull();
+ }
+
+ // ------------------------------------------------------------- 记账模式(默认档位)
+
+ @Test
+ void belowFloorInAccountingModeRecordsWithoutTouchingTheResponse() throws Exception {
+ MeterRegistry registry = new SimpleMeterRegistry();
+ ClientVersionGuardFilter filter = filter("4.0.46", false, false, registry);
+
+ MockFilterChain chain = new MockFilterChain();
+ MockHttpServletResponse response = new MockHttpServletResponse();
+ filter.doFilter(post("/api/publish/tasks/7/result", "4.0.45"), response, chain);
+
+ assertThat(chain.getRequest()).as("记账模式不许截断请求").isNotNull();
+ assertThat(response.getContentAsByteArray()).as("记账模式响应体必须一个字节都不许多").isEmpty();
+ assertThat(counterValue(registry, "below", "4.0.45")).isEqualTo(1L);
+ }
+
+ @Test
+ void accountingCountsEveryRequestButWarnsOncePerVersion() throws Exception {
+ MeterRegistry registry = new SimpleMeterRegistry();
+ ClientVersionGuardFilter filter = filter("4.0.46", false, false, registry);
+
+ // 同一个老客户端连打三次:指标必须数到 3(巡检看的是量),WARN 只许第一条
+ for (int i = 0; i < 3; i++) {
+ filter.doFilter(post("/api/price-track/tasks/1/result", "4.0.40"),
+ new MockHttpServletResponse(), new MockFilterChain());
+ }
+ assertThat(counterValue(registry, "below", "4.0.40")).as("日志去重不许把计数一起吞掉").isEqualTo(3L);
+ assertThat(filter.firstWitness("below", "4.0.40")).as("4.0.40 已经留过一条 WARN").isFalse();
+ assertThat(filter.firstWitness("below", "4.0.41")).as("新出现过低版本应允许留第一条").isTrue();
+ }
+
+ @Test
+ void unreportedAndUnparsableBothLandInTheirOwnBuckets() throws Exception {
+ MeterRegistry registry = new SimpleMeterRegistry();
+ ClientVersionGuardFilter filter = filter("4.0.46", false, false, registry);
+
+ filter.doFilter(post("/api/brand/tasks", null), new MockHttpServletResponse(), new MockFilterChain());
+ filter.doFilter(post("/api/brand/tasks", " "), new MockHttpServletResponse(), new MockFilterChain());
+ filter.doFilter(post("/api/brand/tasks", "4.x.6"), new MockHttpServletResponse(), new MockFilterChain());
+
+ assertThat(counterValue(registry, "unreported", "unknown")).isEqualTo(2L);
+ assertThat(counterValue(registry, "unparsable", "4.x.6")).isEqualTo(1L);
+ assertThat(registry.find(ClientVersionGuardFilter.METRIC).tag("verdict", "below").counter())
+ .as("报不出版本不等于版本低").isNull();
+ }
+
+ // ------------------------------------------------------------- 执法模式
+
+ @Test
+ void belowFloorInEnforceModeRefusesWithoutReachingTheController() throws Exception {
+ MeterRegistry registry = new SimpleMeterRegistry();
+ ClientVersionGuardFilter filter = filter("4.0.46", true, false, registry);
+ MockHttpServletResponse response = new MockHttpServletResponse();
+ MockFilterChain chain = new MockFilterChain();
+
+ filter.doFilter(post("/api/similar-asin/tasks/9/result", "4.0.44"), response, chain);
+
+ assertThat(chain.getRequest()).as("执法模式必须截断,不能让老客户端进到 controller").isNull();
+ JsonNode body = objectMapper.readTree(response.getContentAsString());
+ assertThat(body.get("success").asBoolean()).isFalse();
+ assertThat(body.get("code").asInt()).isEqualTo(ClientVersionGuardFilter.CODE_TOO_OLD);
+ assertThat(body.get("message").asText()).contains("客户端版本过低").contains("4.0.46");
+ assertThat(body.get("data").get("minSupportedVersion").asText()).isEqualTo("4.0.46");
+ assertThat(body.get("data").get("reportedVersion").asText()).isEqualTo("4.0.44");
+ assertThat(counterValue(registry, "below", "4.0.44")).isEqualTo(1L);
+ }
+
+ @Test
+ void unreportedOldInstallsAreSparedUntilTheSeparateSwitchIsFlipped() throws Exception {
+ MockFilterChain spared = new MockFilterChain();
+ MockHttpServletResponse sparedResponse = new MockHttpServletResponse();
+ // 存量装机不知道有这个头:光翻 enforce 就把它们判死 = 一次配置变更打停全线
+ enforcing("4.0.46").doFilter(post("/api/shop-match/tasks/1/items", null), sparedResponse, spared);
+ assertThat(spared.getRequest()).as("reject-unreported 默认 false,未上报的装机不许被误杀").isNotNull();
+ assertThat(sparedResponse.getContentAsByteArray()).isEmpty();
+
+ MeterRegistry registry = new SimpleMeterRegistry();
+ ClientVersionGuardFilter both = filter("4.0.46", true, true, registry);
+ MockFilterChain refused = new MockFilterChain();
+ MockHttpServletResponse refusedResponse = new MockHttpServletResponse();
+ both.doFilter(post("/api/shop-match/tasks/1/items", null), refusedResponse, refused);
+ assertThat(refused.getRequest()).as("两个开关都打开后,未上报也要被拒").isNull();
+ assertThat(objectMapper.readTree(refusedResponse.getContentAsString()).get("code").asInt())
+ .isEqualTo(ClientVersionGuardFilter.CODE_TOO_OLD);
+ assertThat(counterValue(registry, "unreported", "unknown")).isEqualTo(1L);
+ }
+
+ @Test
+ void unparsableVersionIsNeverRefusedEvenInEnforceMode() throws Exception {
+ ClientVersionGuardFilter filter = enforcing("4.0.46");
+ MockFilterChain chain = new MockFilterChain();
+ MockHttpServletResponse response = new MockHttpServletResponse();
+
+ filter.doFilter(post("/api/publish/tasks/1/result", "4.x.6"), response, chain);
+
+ assertThat(chain.getRequest()).as("一次格式异常不该由客户端承担断服代价").isNotNull();
+ assertThat(response.getContentAsByteArray()).isEmpty();
+ }
+
+ @Test
+ void aVersionAtOrAboveTheFloorIsPassedWithoutAnyTrace() throws Exception {
+ MeterRegistry registry = new SimpleMeterRegistry();
+ ClientVersionGuardFilter filter = filter("4.0.46", true, true, registry);
+
+ filter.doFilter(post("/api/publish/tasks/1/result", "4.0.46"), new MockHttpServletResponse(),
+ new MockFilterChain());
+ filter.doFilter(post("/api/publish/tasks/1/result", "4.1.0"), new MockHttpServletResponse(),
+ new MockFilterChain());
+
+ assertThat(registry.find(ClientVersionGuardFilter.METRIC).counter()).isNull();
+ }
+
+ @Test
+ void aBrokenFloorConfigNeverRefusesAnyone() throws Exception {
+ // 把最低版本写成 "v4.0" 这类解析不出来的值:闸门不许据此拒绝任何客户端
+ ClientVersionGuardFilter filter = enforcing("v4.0");
+ MockFilterChain chain = new MockFilterChain();
+ MockHttpServletResponse response = new MockHttpServletResponse();
+
+ filter.doFilter(post("/api/publish/tasks/1/result", "1.0.0"), response, chain);
+
+ assertThat(chain.getRequest()).isNotNull();
+ assertThat(response.getContentAsByteArray()).isEmpty();
+ }
+
+ // ------------------------------------------------------------- 名单与解析
+
+ @Test
+ void clientFacingPrefixesComeFromTheAdminGuardListPlusTheCredentialEntry() {
+ List