diff --git a/.gitignore b/.gitignore index ffb204562..8a2bae1b7 100644 --- a/.gitignore +++ b/.gitignore @@ -139,3 +139,7 @@ data/logs/ # 生产库转储永不再入库(本体只留 backend-java/data/,那里已被忽略) backend-java/src/main/resources/db/aiimage.sql + +# 打包前由 scripts/_git_stamp.py write 生成,随 jar 进 BOOT-INF/classes/; +# 入库会变成"孤儿构建产物"(10-07 那笔 target/classes 里的 V148 就是这个形状造成的宕机) +backend-java/src/main/resources/git.properties diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/BuildInfoLogger.java b/backend-java/src/main/java/com/nanri/aiimage/config/BuildInfoLogger.java new file mode 100644 index 000000000..251e4ab74 --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/config/BuildInfoLogger.java @@ -0,0 +1,94 @@ +package com.nanri.aiimage.config; + +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.nio.charset.StandardCharsets; +import java.util.Properties; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.boot.context.event.ApplicationReadyEvent; +import org.springframework.context.event.EventListener; +import org.springframework.core.io.ClassPathResource; +import org.springframework.core.io.Resource; +import org.springframework.stereotype.Component; + +/** + * 开机把「这个 jar 是从哪一笔代码打出来的」念出来。 + * + *
存在的理由:制品名自始没 bump 过({@code aiimage-backend-0.0.1-SNAPSHOT.jar}),pom 也没接 + * git-commit-id,所以出问题时光看线上机器无法回答"现在跑的是哪版代码"——2026-10-07 那次 41 分钟 + * 宕机就是靠"哪个类只有那笔才有"人工认出来的。章由 {@code scripts/_git_stamp.py write} 在打包前 + * 生成,随 jar 落在 {@code BOOT-INF/classes/git.properties}。 + * + *
读不到时**不许静默**:打 {@link #MISSING_ANCHOR} 一行 WARN,巡检(scripts/_prod_watch.py 的 + * SIGNATURES)能按这个锚点计数。真正的拦在发布闸门({@code _git_stamp.py verify}),不在这里—— + * 这里拒绝启动会把一个只是没盖章的在跑实例打死,代价和收益不成比例。 + */ +@Component +public class BuildInfoLogger { + + static final String RESOURCE = "git.properties"; + static final String MISSING_ANCHOR = "[build-info-missing]"; + static final String INFO_ANCHOR = "[build-info]"; + + private static final Logger log = LoggerFactory.getLogger(BuildInfoLogger.class); + + /** 一份构建章。{@code commit} 为空串表示章在但没盖住。 */ + record BuildInfo(String commit, String branch, String dirty, String buildTime) { + boolean usable() { + return commit != null && !commit.isBlank(); + } + } + + /** + * 读 classpath 上的章。返回 null 代表**文件不存在**; + * 存在但内容空则返回一个 {@link #BuildInfo#usable()} 为 false 的对象—— + * 这两种情况在日志里必须分开,否则"忘了打包前盖章"和"章被清空"会混成同一条。 + */ + static BuildInfo read(Resource resource) { + if (!resource.exists()) { + return null; + } + Properties p = new Properties(); + try (InputStream in = resource.getInputStream()) { + p.load(new InputStreamReader(in, StandardCharsets.UTF_8)); + } catch (IOException ex) { + log.warn("{} 读到 {} 但解析失败:{}", MISSING_ANCHOR, RESOURCE, ex.getMessage()); + return new BuildInfo("", "", "", ""); + } + return new BuildInfo(p.getProperty("commit", "").trim(), p.getProperty("branch", "").trim(), + p.getProperty("dirty", "").trim(), p.getProperty("build_time", "").trim()); + } + + /** 一行话的描述,供日志与测试共用(测试拿它断言"脏包不会被念成干净")。 */ + static String describe(BuildInfo info) { + if (info == null) { + return "commit=unknown(jar 内无 " + RESOURCE + ",这份包是跳过 _git_stamp.py write 打出来的)"; + } + if (!info.usable()) { + return "commit=empty(" + RESOURCE + " 里 commit 键为空,等于没盖章)"; + } + return "commit=" + info.commit().substring(0, Math.min(12, info.commit().length())) + + " branch=" + (info.branch().isEmpty() ? "?" : info.branch()) + + " dirty=" + info.dirty() + + " built=" + (info.buildTime().isEmpty() ? "?" : info.buildTime()); + } + + @EventListener(ApplicationReadyEvent.class) + public void logOnBoot() { + logIt(read(new ClassPathResource(RESOURCE))); + } + + /** 与 {@link #logOnBoot()} 分开,是为了让测试能直接喂三种形状进来,不必伪造 classpath。 */ + String logIt(BuildInfo info) { + String line = describe(info); + if (info == null || !info.usable() || "true".equalsIgnoreCase(info.dirty())) { + log.warn("{} {}", MISSING_ANCHOR, line); + } else { + log.info("{} {}", INFO_ANCHOR, line); + } + return line; + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/config/BuildInfoLoggerTest.java b/backend-java/src/test/java/com/nanri/aiimage/config/BuildInfoLoggerTest.java new file mode 100644 index 000000000..f123505eb --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/config/BuildInfoLoggerTest.java @@ -0,0 +1,135 @@ +package com.nanri.aiimage.config; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.charset.StandardCharsets; +import java.util.List; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.springframework.core.io.ByteArrayResource; +import org.springframework.core.io.FileSystemResource; +import org.springframework.core.io.Resource; + +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; + +/** + * 构建章的读法与"念出来"的级别。 + * + *
这些用例要防的形状是:读不到章时静默当作干净构建。所以每条都同时断言
+ * **说了什么**(describe)与**用什么级别说**(WARN/INFO),后者才是巡检能数到的那一部分。
+ */
+class BuildInfoLoggerTest {
+
+ private static final String STAMP =
+ "commit=3a49f5f8b1c2d3e4f5061728394a5b6c7d8e9f00\n"
+ + "branch=master\ndirty=false\nbuild_time=2026-10-08T17:00:00+08:00\n";
+
+ private static ByteArrayResource stamp(String body) {
+ return new ByteArrayResource(body.getBytes(StandardCharsets.UTF_8));
+ }
+
+ /** 挂一个 ListAppender 到本类的 logger 上,取回真实落到的事件(不是自己拼字符串)。 */
+ private static List