docs(gitea): 记录精简升级验收策略

CHANGELOG.md

@@ -34,6 +34,8 @@ What changed in this homelab, when, and why. Newest first.
 | Gitea 1.26 result | Flux 以 Helm revision 16 成功完成 chart `12.6.0` / Gitea `1.26.4-rootless` 的 Recreate upgrade 和 migration 323–330；Pod 内/统一域名 API、临时 branch push/delete、Flux source 及 main/smoke 的全部 CI jobs 均通过，Pod 在约 15 分钟采样中保持零重启，Authelia OIDC init 同步与浏览器交互式管理员登录也已确认成功 |
 | Gitea 1.27 preparation | 预拉取 `1.27.3-rootless` 并将第二跳 desired state 原子设置为 chart `12.7.0`、显式 image `1.27.3` 和 `suspend: true`；合并只暂停并登记目标，不执行 migration，激活前必须从当前 1.26.4 数据建立新的配套回滚点 |
 | Gitea 1.27 activation | 按明确决定跳过新的 1.26.4 数据库/PVC 备份，激活变更只移除 HelmRelease 的 `suspend`；接受 migration 失败后不能无损回退到 1.26.4 的风险，现有 1.25.5 本地备份仅能作为会丢失第一跳后状态的灾难恢复点 |
+| Gitea 1.27 result | Flux 以 Helm revision 17 成功部署 chart `12.7.0` / 实际 Gitea `1.27.3-rootless`，migration 331–342 与 init containers 全部成功；内外 API、Git write 路径与 Flux source 均通过，Pod Ready 且零重启。Chart metadata 的 appVersion `1.27.0` 不代表实际固定镜像版本 |
+| Gitea upgrade policy | 连续两次跨 minor 升级证明当前 Flux + Recreate + rootless PVC + 外部 CNPG 路径稳定；后续常规 patch/minor 默认缩减为 release-note review、render、UpgradeSucceeded/Pod Ready/API、OIDC 与 Git 抽查。只有数据库/存储/rootless/PVC/部署策略/重大 chart 或 breaking migration 变化及实际失败时，才恢复停机备份和扩展验收 |
 
 ### Incident: Gitea 备份后的恢复命令被 stdin 校验阻塞
 
@@ -44,11 +46,10 @@ What changed in this homelab, when, and why. Newest first.
 旧版 Gitea 恢复后内外 API 和 Flux source 均正常；后续 runbook 不再把 stdin 管道与
 恢复命令放进同一个 shell transaction。
 
-`Carried forward`: complete the two-stage zero-change `gitea` HelmRelease
+`Carried forward`: migrate Gitea's remaining manual OIDC Secret to OpenBao/ESO,
-adoption, migrate its remaining manual OIDC Secret to OpenBao/ESO, then upgrade
+then add credential-free PR plan output and order the remaining Helm migrations
-Gitea and add credential-free PR plan output before ordering the remaining Helm
+by dependency and blast radius. Root Flux prune remains disabled until
-migrations by dependency and blast radius. Root Flux prune remains disabled
+brownfield ownership is audited.
-until brownfield ownership is audited.
 
 ## 2026-09-09
 

apps/gitea/README.md

@@ -6,7 +6,7 @@ Envoy Gateway HTTPRoute 提供。Helm chart 自带的无 class Ingress 暂时保
 
 ## Flux 接管
 
-现有 release 是 `gitea-12.5.3`（Gitea `1.25.5`）。接管分为两个 PR：第一阶段创建
+初始接管 release 是 `gitea-12.5.3`（Gitea `1.25.5`）。接管分为两个 PR：第一阶段创建
 固定版本且 `suspend: true` 的 HelmRelease，只让 Flux 登记对象；确认 source Ready
 并重新验证完整 chart render 后，第二阶段解除 suspend。第一阶段已经确认 source、
 子 Kustomization 和 HTTPRoute 均 Ready，Helm revision 与 Gitea Pod 未变化；第二次
@@ -24,8 +24,23 @@ Gitea 是 Flux GitRepository 的上游。升级或重启期间 Git source 暂时
 跨 minor 的执行顺序、停机一致备份和失败恢复步骤见
 [`../../docs/gitea-upgrade-plan.md`](../../docs/gitea-upgrade-plan.md)。
 
-第一跳 chart `12.6.0` / Gitea `1.26.4` 已完成，migration、API、Git push 和 CI 均
+当前 release 是 chart `12.7.0` / Gitea `1.27.3-rootless`。两次跨 minor migration、
-通过。第二跳 desired state 已准备为 chart `12.7.0` / Gitea `1.27.3`，HelmRelease
+API、OIDC、Git/Flux 和 runner 均已验证。第二跳按明确决定跳过了新的 1.26.4 停机
-的激活变更只移除 `suspend`。第二跳按明确决定跳过新的 1.26.4 停机一致回滚点；若
+一致回滚点；现有 1.25.5 本地备份没有 OCI 或异机副本，因此只作为会丢失后续状态的
-1.27 migration 后失败，现有 1.25.5 本地备份只能恢复到更早状态，不能无损回退到
+灾难恢复点。
-1.26.4。第一阶段备份也没有上传 OCI 或建立异机副本，因此恢复冗余低于长期目标。
+
+## 后续升级默认策略
+
+已连续验证两次 Flux 驱动的跨 minor Recreate upgrade，后续常规 patch/minor 升级
+不再默认执行长时间观察、临时 branch push/delete、重复 CI、逐条 migration 日志审计
+或每个 minor 的停机备份。默认只需要：
+
+1. 固定 chart 和实际 `image.tag`，阅读与本配置相关的 breaking/security notes；
+2. Helm/Kustomize render 通过 review；
+3. 合并后确认 HelmRelease `UpgradeSucceeded`、Pod Ready 且没有 CrashLoop；
+4. API 返回目标版本，并简单确认 OIDC 登录和一次正常 Git 操作。
+
+只有变更数据库后端或存储布局、rootless 模式、PVC identity、部署策略、重大 chart
+结构，或者 release notes 指出相关 breaking migration 时，才恢复停机一致备份、分阶段
+suspend、详细日志审计和扩展验收。出现启动失败或 migration error 时也立即升级为完整
+故障流程。

docs/gitea-upgrade-plan.md

@@ -41,8 +41,9 @@ Actions fork PR 审批绕过等安全问题。两个 rootless 镜像标签都已
   排版变化和 test hook 参数排版，没有新增或删除 live 业务对象。
 - `docker.gitea.com/gitea:1.26.4-rootless` 与
   `docker.gitea.com/gitea:1.27.3-rootless` 的 multi-arch manifests 均存在。
-- 当前 Gitea 日志没有 deprecation、warning 或 error；HTTPRoute、内部 API、统一域名
+- 升级前没有 deprecation 或 error；启动会报告若干数据库 default 比较及内网明文 SMTP
-  API 与 Flux GitRepository 均 Ready。
+  warning，均为已有状态。HTTPRoute、内部 API、统一域名 API 与 Flux GitRepository
+  均 Ready。
 
 ## 每个 minor 的执行单元
 
@@ -147,6 +148,23 @@ Terraform CI 均通过。Pod 在约 15 分钟观察期内保持 Running、零重
 migration 后若失败，不能无损回到 1.26.4；现有本地 1.25.5 备份只可用于接受丢失
 第一跳之后状态的灾难恢复。目标 1.27.3 镜像已预拉取，其余准备检查均已通过。
 
+激活后 Helm revision 17 以 chart `12.7.0` 成功部署实际镜像 `1.27.3-rootless`，
+migration 331–342 和全部 init containers 成功；Pod 内/统一域名 API、Git pull、临时
+branch push/delete 与 Flux source 均通过，Pod Ready 且零重启。Chart metadata 显示
+appVersion `1.27.0`，实际版本以固定 image 和 API 返回的 `1.27.3` 为准。
+
+## 后续升级策略
+
+本次连续两次跨 minor 升级证明现有 chart、外部 CNPG、rootless PVC 和 `Recreate`
+组合工作稳定。后续常规 patch/minor 升级采用精简验收：固定 chart/image、审阅相关
+release notes、render、确认 `UpgradeSucceeded`/Pod Ready/API 版本，再人工抽查 OIDC
+与 Git。长时间观察、临时 branch、重复 CI、逐条 migration 日志和逐 minor 停机备份
+不再是默认步骤。
+
+以下任一条件出现时恢复本文的完整流程：数据库或存储变更、rootless/权限模型变化、
+PVC identity 或 deployment strategy 变化、重大 chart 结构变化、相关 breaking migration，
+以及任何启动失败、CrashLoop 或 migration error。
+
 ## 后续但不并入升级
 
 - 将 `gitea-oidc-secret` 等剩余手工 Secret 迁入 OpenBao/ESO；