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:
2026-10-03 15:41:49 +08:00
parent 37592a3b62
commit 4b7405895d
5 changed files with 141 additions and 5 deletions
@@ -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;
@@ -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;
@@ -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());
}
}