Merge pull request '记录 Gitea 后续精简升级策略' (#28) from docs/gitea-upgrade-policy into main

Reviewed-on: #28

AGENTS.md

@@ -4,6 +4,8 @@
 - `apps/http-echo/` and `archive/traefik/` contain Kubernetes/Gateway API manifests; inspect their parent Gateway references before applying archived or brownfield resources.
 - `apps/tailscale/helm.sh` contains live Tailscale OAuth values; do not copy, print, or commit those values anywhere else.
 - Preserve the existing README intent in `apps/http-echo/` and `archive/traefik/` when updating manifests.
+- `CHANGELOG.md` 是冻结的历史快照，不再更新。持久的服务状态与运维知识写入对应
+  README/runbook；单次变化由 commit 和 PR 记录，agent 陷阱写入 `CLAUDE.md`。
 - 在 homelab 工作中，所有提交到 `git.ddupan.top` 的 commit message、PR、issue
   和项目文档默认优先使用中文。代码标识符、命令、配置键、上游专有名称，以及
   使用英文能避免歧义的技术字段可保留英文。

CLAUDE.md

@@ -132,9 +132,10 @@ recovered, so `.vault_pass.gpg` is the authoritative recovery path.
 
 ## Working rules
 
-- **Record changes in `CHANGELOG.md`.** One dated section per day, newest first; incidents
-  get their own subsection. Traps and procedures belong *here* in CLAUDE.md, not there —
-  the changelog is for humans reading what changed.
+- **Do not update `CHANGELOG.md`.** It is a frozen historical snapshot; requiring every PR
+  to append to one shared text file caused needless conflicts and duplicated Git/PR history.
+  Put durable service state and operational knowledge in the component README or runbook,
+  agent-facing traps here, and let commits/PRs record individual changes.
 - **Verify, don't assert.** Check the end state (`pvesm status`, `linstor node list`,
   `kubectl get pod`, `show ip route`) rather than trusting that a command "should have" worked.
   Several confident diagnoses in this repo's history were wrong until measured.

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 时也立即升级为完整
+故障流程。

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；

docs/superpowers/RETIRED.md

@@ -20,7 +20,7 @@ SUB-SKILL", checkbox task lists) that only ever suited one migration. Design
 documents now live directly in `docs/` — see `../cicd.md` — and the split that
 matters is:
 
-- `CHANGELOG.md` — what changed, for humans
+- `CHANGELOG.md` — frozen historical snapshot; Git commits and PRs now record changes
 - `CLAUDE.md` — traps and procedures, for agents
 - `docs/*.md` — design docs for work not yet built
 - `<service>/README.md` — how a service actually works