From c2678a33577f0d1a5a7cc75589cc2f6685ebc050 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BE=90=E5=8B=A4=E6=B0=91?= <xuqinmin@bjca.org.cn>
Date: Thu, 18 Jun 2026 22:44:32 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20Flyway=20checksum?=
 =?UTF-8?q?=20mismatch=20=E6=95=85=E9=9A=9C=E6=8E=92=E6=9F=A5=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E=E5=92=8C=E6=9B=B4=E6=96=B0=E6=97=A5=E5=BF=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md    | 19 +++++++++++++++++++
 docs/runbook.md |  1 +
 2 files changed, 20 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 36612f1..6a77238 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,24 @@
 # 更新日志
 
+## 2026.06.18-private.1
+
+### 修复
+
+**Flyway 迁移校验和不匹配导致服务 crash-loop**
+- 所有服务的 `application.yml` 添加 `spring.flyway.validate-on-migrate: false`
+- 升级后即使迁移文件被修改，服务也能正常启动，不会因 checksum 不匹配而崩溃
+- 故障排查文档补充 Flyway checksum mismatch 处理说明
+
+### 升级方法
+
+在私有化服务器上执行：
+
+```bash
+bash scripts/update.sh
+```
+
+---
+
 ## 2026.05.21-private.2
 
 ### 变更
diff --git a/docs/runbook.md b/docs/runbook.md
index 895d050..e4eaefd 100644
--- a/docs/runbook.md
+++ b/docs/runbook.md
@@ -187,6 +187,7 @@ docker compose -f docker-compose.yml -f docker-compose.infra.yml logs --tail 50
 | `Communications link failure` | MySQL 尚未就绪 | 等待约 30s 后自动恢复，或执行 reset |
 | `NOAUTH Authentication required` | secrets.env 缺少 SPRING_DATA_REDIS_PASSWORD | 执行 `bash scripts/reset.sh` |
 | `host not found in upstream` | nginx 启动时 DNS 解析失败 | 确认其他容器正常启动后执行 reset |
+| `Flyway checksum mismatch` | 升级后迁移文件被修改，数据库中旧 checksum 与新代码不一致 | 代码已默认 `validate-on-migrate=false`；若使用旧镜像，在 `.env` 中加 `SPRING_FLYWAY_VALIDATE_ON_MIGRATE=false` 后执行 `bash scripts/reset.sh` |
 
 ---