feat(版本硬地板): ClientVersionGuardFilter 双模式闸门,默认惰性+只记账

口径出处:四面 9 分文档 §2 后端最后一项。此前全仓唯一的 minClientVersion 在 digitalhuman
里,且 DigitalHumanVersionService:86 写入、:258 读出两处都是**透传**,全树没有一处比较过它
(grep getMinClientVersion 只有这两处命中)——对桌面客户端 API 面零约束。

新增 backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java:
读 X-Client-Version,与 aiimage.client-version.min-supported-version 比较,三档开关:
- min 留空(默认)= 闸门整条惰性,逐请求等价于没装;
- enforce=false(默认)= 只记账:Counter aiimage.client.version.floor{verdict,version,enforce}
  + 每个 (verdict,version) 至多一条 [版本地板] WARN(日志去重不吞计数,与 10-06 通知放大同口径);
- enforce=true 才拒,响应体沿用项目约定 HTTP 200 + {success:false, code:4012, message, data}。
另有一条 reject-unreported=false:4.0.46 及更早的装机不知道有这个头,光翻 enforce 就把它们
判死等于用一次配置变更打停全线存量,所以"未上报"默认只进 unreported 桶;报不出格式的
(4.x.6)永不拒。

受管前缀**复用** AdminApiGuardFilter.USER_TOOL_PREFIXES(同一份"桌面客户端直连的用户态前缀"
口径,改成包级可见,不复制清单),另补 /api/client(取凭据第一跳)。/api/version/** 明确不在
名单内——被拒的老客户端必须永远能拿到升级信息,否则闸门把自己变成砖。

ClientVersionGuardFilterTest 12 例(mvn -o test -Dtest=ClientVersionGuardFilterTest:
Tests run: 12, Failures: 0, Errors: 0):两种模式各钉一条正断言(记账必须"响应体一个字节都
不许多"、执法必须"chain 不前进"),另钉默认态零行为、三类非客户端面零判定、unreported 与
unparsable 分桶、名单逐条继承 + 三个排除项、版本解析/比较边界(4.0==4.0.0、4.0<4.0.1、
4.0.46.2>4.0.46、v4.0.6/4..6/4.x.6 判不出)、WARN 去重与计数不相干、min 配置写坏时不拒任何人。

不出包、不重启、不改任何 yml(默认值即现网态)。
This commit is contained in:
2026-10-08 20:25:59 +08:00
parent a24d7b9bac
commit 9d762c552a
3 changed files with 562 additions and 1 deletions
@@ -0,0 +1,267 @@
package com.nanri.aiimage.config;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
import org.junit.jupiter.api.Test;
import org.springframework.mock.web.MockFilterChain;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.util.ReflectionTestUtils;
import java.util.ArrayList;
import java.util.List;
import static org.assertj.core.api.Assertions.assertThat;
/**
* 客户端版本硬地板判据:**两种模式各钉一条**,并证明默认态(min 未配置)逐请求等价于没装闸门。
*
* <p>记账模式必须"只留痕不动响应"(chain 继续、响应体一个字节都不许多),执法模式必须"根本不放行"
* (chain 不前进 + 4012 体)。这两个断言分别挡住两类事故:只记账却顺手改了响应 = 现网故障;
* 想执法却只记了账 = 地板形同虚设。
*
* <p>重跑:{@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<String> missing = new ArrayList<>();
for (String prefix : AdminApiGuardFilter.USER_TOOL_PREFIXES) {
if (!ClientVersionGuardFilter.isClientFacing(prefix + "/anything")) {
missing.add(prefix);
}
}
assertThat(missing).as("受管面必须整份继承用户态名单,不许有漏项").isEmpty();
assertThat(ClientVersionGuardFilter.isClientFacing("/api/client/credentials")).isTrue();
// 反向:这三类必须不在名单里,否则被拒的老客户端拿不到升级信息(闸门把自己变成砖)
assertThat(ClientVersionGuardFilter.isClientFacing("/api/version/latest")).isFalse();
assertThat(ClientVersionGuardFilter.isClientFacing("/api/admin/users")).isFalse();
assertThat(ClientVersionGuardFilter.isClientFacing("/api/internal/user-proxy")).isFalse();
assertThat(ClientVersionGuardFilter.isClientFacing(null)).isFalse();
}
@Test
void versionParsingAndOrdering() {
assertThat(ClientVersionGuardFilter.parse("4.0.46")).containsExactly(4L, 0L, 46L);
assertThat(ClientVersionGuardFilter.parse(" 4.0.46 ")).containsExactly(4L, 0L, 46L);
assertThat(ClientVersionGuardFilter.parse("4.0")).containsExactly(4L, 0L);
assertThat(ClientVersionGuardFilter.parse("")).isNull();
assertThat(ClientVersionGuardFilter.parse(" ")).isNull();
assertThat(ClientVersionGuardFilter.parse("4..6")).isNull();
assertThat(ClientVersionGuardFilter.parse("4.x.6")).isNull();
assertThat(ClientVersionGuardFilter.parse("v4.0.6")).isNull();
assertThat(ClientVersionGuardFilter.parse("4.0.6-beta")).isNull();
assertThat(ClientVersionGuardFilter.compare(
ClientVersionGuardFilter.parse("4.0"), ClientVersionGuardFilter.parse("4.0.0"))).isZero();
assertThat(ClientVersionGuardFilter.compare(
ClientVersionGuardFilter.parse("4.0"), ClientVersionGuardFilter.parse("4.0.1"))).isNegative();
assertThat(ClientVersionGuardFilter.compare(
ClientVersionGuardFilter.parse("4.0.46.2"), ClientVersionGuardFilter.parse("4.0.46"))).isPositive();
assertThat(ClientVersionGuardFilter.compare(
ClientVersionGuardFilter.parse("10.0"), ClientVersionGuardFilter.parse("9.9.9"))).isPositive();
}
}