CHANGELOG.md

@@ -29,6 +29,17 @@ What changed in this homelab, when, and why. Newest first.
 | Gitea adoption activate | 第一阶段合并后 source、子 Kustomization 和 HTTPRoute 均 Ready，Helm release 仍为 revision 14，Gitea Pod 未重建或重启；再次确认固定 chart 对 live 业务资源零差异后移除 `suspend`，允许 Flux 修正 Helm 存储状态并启用 drift detection |
 | Gitea upgrade plan | 规划两跳升级：chart `12.6.0` + 显式 Gitea `1.26.4`，再到 chart `12.7.0` + 显式 Gitea `1.27.3`；每个 minor 都先以 suspended desired state 合并、停机建立 CNPG/PVC 一致回滚点，再用独立 PR 激活。当前 CNPG 无连续备份、local-path PVC 无 snapshot class，因此禁止无备份直接触发数据库 migration |
 | Gitea 1.26 preparation | 将第一跳目标写入 Git：chart 固定为 `12.6.0`、rootless 镜像显式固定为 `1.26.4`，同时重新设置 HelmRelease `suspend: true`；该准备 revision 合并后只更新 desired state，不触发 Pod replacement 或数据库 migration |
+| Gitea 1.26 backup | 预拉取 `1.26.4-rootless` 后，在 HelmRelease suspended 状态将 Gitea scale 到 0；生成并校验 539355-byte CNPG custom dump、2609188-byte PVC tar 和 2848667-byte GPG encrypted bundle，随后恢复旧版 `1.25.5` 并验证内外 API 与 Flux source。按明确决定不上传 OCI，本阶段接受只有节点本地回滚点的风险 |
+| Gitea 1.26 activation | 停机一致备份门槛完成后，激活变更只移除 HelmRelease 的 `suspend`；chart `12.6.0`、显式 `1.26.4-rootless` image、values、数据库与 PVC 均保持已 review 的准备状态 |
+
+### Incident: Gitea 备份后的恢复命令被 stdin 校验阻塞
+
+最初把本地 custom-format dump 通过 `kubectl exec -i` 输送给 CNPG Pod 内的
+`pg_restore --list`；远端 stdin 没有正常结束，组合脚本因此停在校验步骤，尚未执行
+后面的 scale-up。Deployment 保持预期的 0，没有失败 Pod 或数据写入。发现后终止
+会话、先恢复 Gitea，再把 dump 临时复制到 CNPG 可写数据卷完成校验并立即删除。
+旧版 Gitea 恢复后内外 API 和 Flux source 均正常；后续 runbook 不再把 stdin 管道与
+恢复命令放进同一个 shell transaction。
 
 `Carried forward`: complete the two-stage zero-change `gitea` HelmRelease
 adoption, migrate its remaining manual OIDC Secret to OpenBao/ESO, then upgrade

apps/gitea/README.md

@@ -24,6 +24,6 @@ Gitea 是 Flux GitRepository 的上游。升级或重启期间 Git source 暂时
 跨 minor 的执行顺序、停机一致备份和失败恢复步骤见
 [`../../docs/gitea-upgrade-plan.md`](../../docs/gitea-upgrade-plan.md)。
 
-当前 Git desired state 已准备第一跳 chart `12.6.0` / Gitea `1.26.4`，但
-HelmRelease 保持 `suspend: true`。合并该准备状态不会运行 migration；必须先按升级
-计划取得停机一致备份，再通过只移除 suspend 的独立激活 PR 执行升级。
+第一跳 chart `12.6.0` / Gitea `1.26.4` 的停机一致备份已经建立并校验；激活 PR
+只移除 HelmRelease 的 `suspend`。本阶段按明确决定只保留节点本地备份，没有上传
+OCI 或建立异机副本，因此其恢复冗余低于长期目标。

apps/gitea/helmrelease.yaml

@@ -20,7 +20,6 @@ spec:
       retryInterval: 5m
   interval: 30m
   releaseName: gitea
-  suspend: true
   targetNamespace: gitea
   timeout: 15m
   upgrade:

docs/gitea-upgrade-plan.md

@@ -117,6 +117,18 @@ patch 版本原则上保持数据库结构兼容；本计划的两个步骤都
 数据库 dump 与 PVC archive 是一个不可拆分的回滚点；禁止混用不同时间或不同阶段的
 两份备份。
 
+## 1.26.4 阶段执行记录
+
+- 目标 `1.26.4-rootless` 镜像已经预拉取到 k3s 节点；
+- Gitea 停写后生成了 custom-format PostgreSQL dump 与保留 owner/ACL/xattr 的 PVC
+  tar，两者分别通过 `pg_restore --list`、`tar --list` 和 SHA-256 校验；
+- 本地回滚点位于
+  `/var/backups/homelab/gitea/20260910T060400Z-1.25.5/`，权限为 0700；其中另有使用
+  个人 GPG 公钥加密并通过 packet 检查的 bundle；
+- 操作者明确选择不上传 OCI，因此本阶段接受只有节点本地副本的风险例外；
+- 备份后旧版 `1.25.5` 已恢复，Pod 内与统一域名 API、Gitea API 和 Flux Git source
+  均验证正常。
+
 ## 后续但不并入升级
 
 - 将 `gitea-oidc-secret` 等剩余手工 Secret 迁入 OpenBao/ESO；