feat(更新链路): web_config 加 sha256(V142),/api/version/latest 回带包摘要
客户端自更新过去只验 zip 结构:桶里的包被换掉时,结构完整的恶意 zip 会直接交给 update.exe 解压执行。摘要必须由服务端给出才与下载来源无关——能替换对象的人替换不了这个接口。 - V142 加 sha256 列(可空、不回填历史行,列缺失时客户端行为不变); - /latest、公开列表、后台上传响应都回带摘要;multipart 上传按真正落盘的字节算; - 直传确认路径不重算摘要(那要把 100MB 对象拉回来),这类行留空由发布脚本回填。 盘点文档同步:V1..V142、141 个文件、后续从 V143 取号。
This commit is contained in:
@@ -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` 落用。
|
||||
|
||||
|
||||
+3
@@ -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;
|
||||
|
||||
|
||||
+35
@@ -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<String, Object> 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;
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
+58
@@ -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<String, Object> 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<String, Object> 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<SoftwareVersionEntity> 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());
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user