From 31d2a6322343cfe4375d08068804a656c88ff9ea Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Thu, 10 Sep 2026 07:22:22 +0000 Subject: [PATCH] =?UTF-8?q?docs(gitea):=20=E8=AE=B0=E5=BD=95=E7=B2=BE?= =?UTF-8?q?=E7=AE=80=E5=8D=87=E7=BA=A7=E9=AA=8C=E6=94=B6=E7=AD=96=E7=95=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 11 ++++++----- apps/gitea/README.md | 27 +++++++++++++++++++++------ docs/gitea-upgrade-plan.md | 22 ++++++++++++++++++++-- 3 files changed, 47 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c98d27..9a99f6b 100644 --- a/CHANGELOG.md +++ b/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 -adoption, migrate its remaining manual OIDC Secret to OpenBao/ESO, then upgrade -Gitea and add credential-free PR plan output before ordering the remaining Helm -migrations by dependency and blast radius. Root Flux prune remains disabled -until brownfield ownership is audited. +`Carried forward`: migrate Gitea's remaining manual OIDC Secret to OpenBao/ESO, +then add credential-free PR plan output and order the remaining Helm migrations +by dependency and blast radius. Root Flux prune remains disabled until +brownfield ownership is audited. ## 2026-09-09 diff --git a/apps/gitea/README.md b/apps/gitea/README.md index 31e832e..6e267e5 100644 --- a/apps/gitea/README.md +++ b/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 均 -通过。第二跳 desired state 已准备为 chart `12.7.0` / Gitea `1.27.3`，HelmRelease -的激活变更只移除 `suspend`。第二跳按明确决定跳过新的 1.26.4 停机一致回滚点；若 -1.27 migration 后失败，现有 1.25.5 本地备份只能恢复到更早状态，不能无损回退到 -1.26.4。第一阶段备份也没有上传 OCI 或建立异机副本，因此恢复冗余低于长期目标。 +当前 release 是 chart `12.7.0` / Gitea `1.27.3-rootless`。两次跨 minor migration、 +API、OIDC、Git/Flux 和 runner 均已验证。第二跳按明确决定跳过了新的 1.26.4 停机 +一致回滚点；现有 1.25.5 本地备份没有 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 时也立即升级为完整 +故障流程。 diff --git a/docs/gitea-upgrade-plan.md b/docs/gitea-upgrade-plan.md index 00b6fd6..856ceef 100644 --- a/docs/gitea-upgrade-plan.md +++ b/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、统一域名 - API 与 Flux GitRepository 均 Ready。 +- 升级前没有 deprecation 或 error；启动会报告若干数据库 default 比较及内网明文 SMTP + 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；