diff --git a/backend-java/docs/migration-inventory.md b/backend-java/docs/migration-inventory.md index 8cab5331e..545256a7f 100644 --- a/backend-java/docs/migration-inventory.md +++ b/backend-java/docs/migration-inventory.md @@ -1,14 +1,14 @@ # Flyway 迁移盘点(task-193) > 生成方式:`src/test/java/com/nanri/aiimage/config/MigrationInventoryTest.java`(只读审计,可重复)。 -> 快照日期:2026-10-01。 +> 快照日期:2026-10-01;2026-10-03 随 V142 追加时同步过概览数字与取号起点。 ## 概览 -- 版本化迁移文件数:**139**(`src/main/resources/db/V*.sql`,其中整数版本 138 个 + 小版本 V25_1) -- 整数版本范围:**V1..V140**,其中 V132/V133 为已退役空号(见下),其余连续 +- 版本化迁移文件数:**141**(`src/main/resources/db/V*.sql`,其中整数版本 140 个 + 小版本 V25_1) +- 整数版本范围:**V1..V142**,其中 V132/V133 为已退役空号(见下),其余连续 - 历史遗留小版本:**V25_1__shop_manage_group_bind_user.sql**(Flyway 语义 25.1,紧跟在 V25 之后、V26 之前执行,属历史命名,保留) -- 最新版本:**V140__collectdata_brand_recheck.sql** +- 最新版本:**V142__web_config_sha256.sql**(V141 已于 2026-10-03 随 jar 上线两台;V142 待下一次发版执行) - 重复版本:无 - 迁移命名:全部符合 `V<整数>(_<子版本>)?__<描述>.sql`,无空格 @@ -20,7 +20,7 @@ 本地曾存在 `V132__web_config_add_is_latest.sql`、`V133__hide_redundant_indexes_invisible.sql`,与另一分支已在生产落库的 V134/V135 冲突。因 Flyway 未开启 `out-of-order`,把任何迁移编到 132/133 会在启动期报 "resolved migration not applied";因此这两条改为 **V136/V137**,132/133 永久退役,不可回填。 -后续新增迁移从 **V141** 起取号(只认"当前最大值 + 1",不要为还没写出来的迁移预留号段——预留会在 1..max 里留洞,`integerVersionsSequentialFromOne` 会红)。 +后续新增迁移从 **V143** 起取号(只认"当前最大值 + 1",不要为还没写出来的迁移预留号段——预留会在 1..max 里留洞,`integerVersionsSequentialFromOne` 会红)。 原先挂在待办里的"V137 冗余索引 DROP"迁移计划取 V139,该号已被 `V139__asin_result_cache.sql` 占用,顺延到 V140;V140 已被品牌补测队列表 `V140__collectdata_brand_recheck.sql` 落用。 diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/model/entity/SoftwareVersionEntity.java b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/model/entity/SoftwareVersionEntity.java index 8d0ce79f9..2167f4f51 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/model/entity/SoftwareVersionEntity.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/model/entity/SoftwareVersionEntity.java @@ -24,6 +24,9 @@ public class SoftwareVersionEntity { /** 安装包可公开访问的下载链接(MinIO path-style 直链) */ private String fileUrl; + /** 安装包 sha256(hex 小写);null 表示 V142 之前的历史行,客户端对这类包不做摘要校验 */ + private String sha256; + /** 是否最新版:全表至多一行为 true,由 SoftwareVersionMapper#markLatestById 单语句维护 */ private Boolean isLatest; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionService.java index 21e4be124..bdacc0271 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionService.java @@ -13,7 +13,10 @@ import org.springframework.web.multipart.MultipartFile; import java.io.File; import java.io.IOException; +import java.io.InputStream; import java.nio.file.Files; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; import java.time.format.DateTimeFormatter; import java.util.ArrayList; import java.util.LinkedHashMap; @@ -102,10 +105,14 @@ public class SoftwareVersionService { if (entity == null) { result.put("version", null); result.put("file_url", null); + result.put("sha256", null); return result; } result.put("version", entity.getVersion() == null ? "" : entity.getVersion()); result.put("file_url", entity.getFileUrl() == null ? "" : entity.getFileUrl()); + // 空字符串 = 「服务端还没有这个包的摘要」(V142 之前的历史行)。客户端据此决定 + // 是硬校验摘要,还是退回旧的「只验 zip 结构」行为。 + result.put("sha256", entity.getSha256() == null ? "" : entity.getSha256()); return result; } @@ -185,6 +192,7 @@ public class SoftwareVersionService { SoftwareVersionEntity entity = new SoftwareVersionEntity(); entity.setVersion(normalizedVersion); entity.setFileUrl(fileUrl); + entity.setSha256(sha256Hex(tempFile)); // 不显式写 created_at,走数据库 CURRENT_TIMESTAMP 默认值(与 Flask 行为一致) softwareVersionMapper.insert(entity); softwareVersionMapper.markLatestById(entity.getId()); @@ -194,6 +202,7 @@ public class SoftwareVersionService { Map result = new LinkedHashMap<>(); result.put("version", normalizedVersion); result.put("file_url", fileUrl); + result.put("sha256", entity.getSha256()); return result; } catch (IOException e) { log.error("[software-version] 上传客户端软件版本文件处理失败 version={} filename={} err={}", @@ -248,6 +257,8 @@ public class SoftwareVersionService { SoftwareVersionEntity entity = new SoftwareVersionEntity(); entity.setVersion(normalizedVersion); entity.setFileUrl(ossStorageService.getSoftwareVersionDownloadUrl(objectKey)); + // 直传确认不重算 sha256:那要把刚上传的 100MB 对象整包拉回来。这条路径落库的行摘要为空, + // 客户端会退回「只验 zip 结构」的旧行为;要给这类包补锚,用发布脚本回填(见凭据轮换工单)。 softwareVersionMapper.insert(entity); softwareVersionMapper.markLatestById(entity.getId()); SoftwareVersionEntity saved = softwareVersionMapper.selectById(entity.getId()); @@ -328,11 +339,35 @@ public class SoftwareVersionService { item.put("id", entity.getId()); item.put("version", entity.getVersion() == null ? "" : entity.getVersion()); item.put("file_url", entity.getFileUrl() == null ? "" : entity.getFileUrl()); + item.put("sha256", entity.getSha256() == null ? "" : entity.getSha256()); item.put("created_at", entity.getCreatedAt() == null ? "" : entity.getCreatedAt().format(CREATED_AT_FORMATTER)); return item; } + /** 算安装包的 sha256(hex 小写),作为更新链路的完整性锚点写进 web_config。 */ + static String sha256Hex(File file) throws IOException { + MessageDigest digest; + try { + digest = MessageDigest.getInstance("SHA-256"); + } catch (NoSuchAlgorithmException e) { + // JDK 必然带 SHA-256;真缺了也不能把已上传成功的版本包静默标成"无摘要" + throw new IOException("SHA-256 不可用", e); + } + byte[] buffer = new byte[1 << 20]; + try (InputStream in = Files.newInputStream(file.toPath())) { + int read; + while ((read = in.read(buffer)) > 0) { + digest.update(buffer, 0, read); + } + } + StringBuilder hex = new StringBuilder(digest.getDigestLength() * 2); + for (byte b : digest.digest()) { + hex.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16)); + } + return hex.toString(); + } + private long elapsedMs(long startedAt) { return (System.nanoTime() - startedAt) / 1_000_000L; } diff --git a/backend-java/src/main/resources/db/V142__web_config_sha256.sql b/backend-java/src/main/resources/db/V142__web_config_sha256.sql new file mode 100644 index 000000000..ad641e916 --- /dev/null +++ b/backend-java/src/main/resources/db/V142__web_config_sha256.sql @@ -0,0 +1,40 @@ +-- V142: web_config(桌面客户端升级包版本表)增加 sha256 —— 更新包的完整性锚点 +-- +-- 背景(2026-10-03 实证):4.0.43 包内 .env 的 oss_access_key_id / oss_access_key_secret 与主机 A +-- minio 容器 env 的 MINIO_ROOT_* 同指纹(口令 len=16 sha8=a84c33f1),也就是对象存储的管理员身份 +-- 随公开包分发给了每个下载者。拿到它的人可以覆盖任意 client/nanri-image/versions/<版本>.zip, +-- 而客户端下载后只验 zip 结构(tool/resumable_download.verify_zip_archive),不比对服务端摘要 +-- ⇒ 结构完整的恶意包会被 update.exe 解压并执行。 +-- 轮换凭据只能管"以后";本表有摘要才能让客户端对每一次下载做与来源无关的校验: +-- 能替换桶里对象的人,替换不了本接口的返回值。 +-- +-- 存量:列可空。历史行没有摘要,客户端在「服务端未登记摘要」时沿用旧行为(告警后继续), +-- 因此本迁移不回填、也不改变 /api/version/latest 对现有客户端的可观察行为(多一个字段, +-- 老客户端按 key 取值,忽略未知键)。当前最新版(4.0.43)的摘要由发布脚本回填。 +-- +-- 不加索引:本表 62 行量级,读取走 is_latest 那条路径,摘要只是随行返回的一列。 +-- 风险:单表 ADD COLUMN,秒级完成;不改任何历史迁移文件。 +-- 上线窗口:无锁窗口顾虑,随双节点滚动发布正常执行;本地/CI 无库不跑 migrate, +-- 首次执行发生在生产启动期,建议先发一台、确认下方验证 SQL 通过后再发第二台。 +-- 回滚:ALTER TABLE `web_config` DROP COLUMN `sha256`; +-- (回滚后客户端不受影响:/latest 不返回 sha256 ⇒ 走"未登记摘要"的旧路径) +-- +-- 验证 SQL(迁移后执行): +-- SHOW COLUMNS FROM `web_config` LIKE 'sha256'; +-- -> 期望 1 行,Type=varchar(64),Null=YES +-- SELECT COUNT(*) AS with_digest FROM `web_config` WHERE `sha256` IS NOT NULL; +-- -> 期望 0(迁移不回填);此后每发布一个版本 +1 + +SET @db_name = DATABASE(); + +SET @col_exists := ( + SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'web_config' AND COLUMN_NAME = 'sha256' +); +SET @sql := IF(@col_exists = 0, + 'ALTER TABLE `web_config` ADD COLUMN `sha256` VARCHAR(64) NULL COMMENT ''更新包sha256(hex小写);NULL=迁移前历史行,客户端不做摘要校验'' AFTER `file_url`', + 'SELECT 1' +); +PREPARE stmt FROM @sql; +EXECUTE stmt; +DEALLOCATE PREPARE stmt; diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionServiceTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionServiceTest.java index 9ebe1da3f..2718f2873 100644 --- a/backend-java/src/test/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionServiceTest.java +++ b/backend-java/src/test/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionServiceTest.java @@ -10,6 +10,7 @@ import org.apache.ibatis.builder.MapperBuilderAssistant; import org.junit.jupiter.api.BeforeAll; import org.junit.jupiter.api.Test; import org.mockito.ArgumentCaptor; +import org.springframework.mock.web.MockMultipartFile; import java.time.LocalDateTime; import java.util.List; @@ -163,4 +164,61 @@ class SoftwareVersionServiceTest { verify(versionMapper, never()).markLatestById(any()); } + + @Test + void latestResponseCarriesThePackageDigest() { + SoftwareVersionEntity withDigest = row(1, "4.0.43", true, 0); + withDigest.setSha256("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"); + when(versionMapper.selectOne(any())).thenReturn(withDigest); + + Map result = service().latestSoftwareVersion(); + + // 客户端拿它比对下载到的 zip:这是更新链路唯一的、换包的人改不动的锚点 + assertEquals("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad", + result.get("sha256")); + } + + @Test + void legacyRowWithoutDigestReportsEmptyStringNotNull() { + when(versionMapper.selectOne(any())).thenReturn(row(1, "4.0.32", true, 0)); + + Map result = service().latestSoftwareVersion(); + + // 空串 = 「服务端还没登记这个包的摘要」,客户端据此退回旧的只验 zip 结构; + // null 会被 JSON 省略掉,客户端就分不清"没有摘要"和"服务端是旧版本没这个字段" + assertEquals("", result.get("sha256")); + } + + @Test + void sha256HexMatchesTheKnownVector() throws Exception { + java.io.File file = java.io.File.createTempFile("digest-vector-", ".zip"); + try { + java.nio.file.Files.write(file.toPath(), new byte[]{'a', 'b', 'c'}); + + assertEquals("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad", + SoftwareVersionService.sha256Hex(file), "\"abc\" 的 SHA-256 是公开向量"); + } finally { + file.delete(); + } + } + + @Test + void multipartUploadStoresTheDigestOfTheUploadedBytes() throws Exception { + // 摘要必须算在真正落到对象存储的那份字节上:先 transferTo 再 digest,顺序反了就锚错对象 + MockMultipartFile upload = new MockMultipartFile("file", "4.0.44.zip", + "application/zip", new byte[]{'a', 'b', 'c'}); + String objectKey = SoftwareVersionService.STORAGE_PATH_PREFIX + "4.0.44.zip"; + when(ossStorageService.uploadSoftwareVersionPackage(any(), eq(objectKey))) + .thenReturn("https://oss.aishufu.top/" + objectKey); + ArgumentCaptor inserted = ArgumentCaptor.forClass(SoftwareVersionEntity.class); + when(versionMapper.insert(inserted.capture())).thenAnswer(invocation -> { + ((SoftwareVersionEntity) invocation.getArgument(0)).setId(300L); + return 1; + }); + + service().uploadSoftwareVersion("4.0.44", upload); + + assertEquals("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad", + inserted.getValue().getSha256()); + } }