docs: 回填版本保留候选清单,并记一次 worktree 全量 26 红的归因

§二.4 直接把 04:50 那轮 dry-run 的 20 个候选版本、两条安全边界(分布式锁已挡并发、
删除路径钉在 nanri-image/versions/ 前缀且需无引用)写清,交人工核对后就能拍 dry-run。

§十六 记下同一批代码在主树 3275/0 绿、在新检出 worktree 却 6 fail + 20 error:
前者是 autocrlf 改写 golden(已由 3bd2b607 钉死),后者是"文档一致性测试"读的是
34 份只活在本机的 md —— 这条属仓库缺口,要人决定入库还是改成缺失即跳过。
This commit is contained in:
2026-09-28 19:05:44 +08:00
parent 3bd2b60774
commit a022bfbe06
+74
View File
@@ -180,6 +180,35 @@ Replica_IO_Running: Yes Replica_SQL_Running: Yes Seconds_Behind_Source: 0
`aiimage.software-version.retention-dry-run` 默认 true(只记日志不删对象)。要启用真删,
先把日志里列出的候选清单人工核一遍(客户端安装包对象有历史事故,见 KKBROSWER 那条),核对后再置 false。
**候选清单已拉出来了(19:0x 读现网 26 小时日志,原文照录,一条不差)**:
```
主机B 2026-09-28 04:50:00.003 [aiimage-scheduling-1] INFO SoftwareVersionRetentionService
- [version-retention] dry-run 未实际删除 total=67 keep=20 候选=20 versions=
[4.0.17, 4.0.16, 4.0.15, 4.0.14, 4.0.13, 4.0.12, 4.0.11, 4.0.10, 4.0.9, 4.0.7,
4.0.6, 4.0.5, 4.0.4, 4.0.3, 4.0.2, 4.0.1, 4.0.0, 3.0.73, 3.0.72, 3.0.71]
留待下轮=27
主机A 同一时刻:[version-retention] 升级包保留清理跳过:另一实例持锁
```
清单里没有 `4.0.8`(4.0.9 直接跳到 4.0.7),这条本身值得看一眼:要么那一版从未上传过,
要么它的行已经不在 keep 窗口外的候选里(被 `is_latest` 过滤掉的可能也有,代码里
`superseded` 会跳过带 is_latest 标记的行)。
三件核对时要知道的事:
1. **不会两实例并发删**:`DistributedJobLockService.tryLock("software-version:retention", 10min)`
已经在那儿了,今天实测 A 跳过、B 执行,所以去 dry-run 不需要先做单点化。
2. **一次只删 20 条**:`MAX_DELETIONS_PER_RUN=20`。67 条记录 - keep 20 = 47 条在窗口外,
分 3 轮(约 3 天)跑完,不是一次清光。按 09-21 盘点口径约 106MB/个推算 ≈ 5GiB(**对象实际大小没实测**)。
3. **KKBROSWER.zip 删不到**:`deleteSoftwareVersions` 先删行,再对每个 `file_url` 反查
`selectCount(eq(fileUrl))`,**只有已无其它行引用时才动对象**;且
`removeSoftwareVersionObjectQuietly` 要求 objectKey `startsWith("nanri-image/versions/")`,
前缀不符直接 return false。桶根与 `client/APP/` 下的历史包都不在这个前缀里。
置 false 的两条路:改 `application.yml` 默认值要重新出包;或往 `/.env` 追加 export 后重启
(键名按 Spring 松散绑定应是 `AIIMAGE_SOFTWAREVERSION_RETENTION_DRYRUN`,**别假设,启动后回读那行生效配置再说**)。
### 5. V137 的 20 个冗余索引还只是 INVISIBLE
V137 只把它们置为不可见,**观察 1~2 周慢日志无退化后要追加 V138 执行 DROP**,否则索引仍占空间、
@@ -1360,3 +1389,48 @@ JPEG 图片 entry 现在仍走 DEFLATE。JPEG 本身已压过,再 deflate 基
而本轮的判据是"不改语义"。
---
## 十六、一次「隔离 worktree 全量 26 红」的归因:一半是检出换行符,一半是测试读了 gitignore 的本机 md(18:5x)
同一批代码,主工作树 3275 用例 0 失败;新检出的 `tmp/head-build`(HEAD 固定版)跑出
`Tests run: 3275, Failures: 6, Errors: 20`。两边差的不是代码,是**检出形态**。
### 16.1 那 6 个 golden 快照失败:`core.autocrlf=true` 把 LF blob 写成了 CRLF
`ShopDataCrawlSnapshotTest` / `AppearancePatentSnapshotTest` / `PublishBatchLoadingSnapshotEquivTest`
都是同一个形状:golden 用 `Files.readString(path, UTF_8)` 直读,被测串用 `sb.append('\n')` 生成,
中间**没有任何换行归一**。worktree 里 `rows-snapshot.txt` 是 `CR=3 LF=3`,主树同一文件 `CR=0 LF=3`,
去掉 `\r` 后两边逐字节相等 —— 所以断言必然红,但内容与行为都没变。
修法落在属性而不是测试:仓库根新增 `.gitattributes`(提交 `0fe2121b`),把断言会读到的
`*.txt *.md *.sql *.yml *.yaml *.json *.sh` 钉成 `text eol=lf`。零 churn 的依据是先量了一遍:
`git grep -I --name-only -P '\r' HEAD` 在**全部 tracked blob 上 0 命中**,所以钉属性不会让
`git status` 变脏(实测加完仍是 0 条 tracked 修改)。只列扩展名、**不写 `* text`**:
后者会让 git 去归一化 jar/png/zip 这些二进制产物。没动 `*.bat/*.cmd`:现在它们的 blob 是 LF,
标成 `eol=crlf` 反而会在下次检出时改写它们,那是另一件事。
一个坑要记下:`git checkout -f <sha>` 和 `git checkout-index -a -f` **都不会重写 git 认为"未变"的文件**,
所以加完 `.gitattributes` 在老 worktree 里看不到效果;删档再 `git checkout -- <path>` 才拿到 `CR=0`。
### 16.2 那 20 个 doc 测试失败:断言对象根本没入库(**这条要人拍**)
`ArchitecturePlanSection6DocTest`(8)+ `ExplainIndexAuditDocTest`(9)+ `IndexMigrationV101Test`(3)
抛的是 `NoSuchFileException`,不是断言不符。它们用相对路径直读 `backend-java/docs/**.md`,而
`backend-java/docs` 下 **41 个文件里只有 7 个是 tracked**:
| 被读的 md | 状态 |
| --- | --- |
| `docs/java-architecture-optimization-plan.md` | `.gitignore:119 backend-java/docs/*plan*.md` 挡掉 |
| `docs/explain-index-audit.md` | `.gitignore:121 backend-java/docs/*audit*.md` 挡掉 |
| `docs/plans/00-plan-overview.md`、`docs/specs/12-flyway-and-inspection.md` 等 | 同样未入库 |
也就是说:**这些"文档一致性测试"在任何 fresh clone 或 CI 上必红 20 个**,它们只在 lxq 这台机器上绿,
因为那 34 份 md 只活在本机。两个方向选一个(我没自行改 `.gitignore`,那等于替整个仓库决定哪些文档要入库):
- 把被断言的那几份 md 纳入版本(加 `!` 白名单或收窄 `*plan*/*audit*` 两条规则),CI 才能当门禁;
- 或让这几类测试在文件缺失时 `assumeTrue(存在)` 跳过,并在报告里显式标"本机限定测试"。
本轮为了拿到干净的发版门禁,采取的是第三条临时路:把本机 `backend-java/docs` 整目录 `cp -ru` 进 worktree
(不改仓库、不改测试),重跑这 7 个类得 **86 用例 0 fail 0 error**(19:02–19:03 的新 surefire 产物)。