From 19cd0a938b26872eb64effbf06e289fa500621cd 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 --- AGENTS.md | 2 ++ CLAUDE.md | 7 ++++--- apps/gitea/README.md | 27 +++++++++++++++++++++------ docs/gitea-upgrade-plan.md | 22 ++++++++++++++++++++-- docs/superpowers/RETIRED.md | 2 +- 5 files changed, 48 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c98354b..313b223 100644 --- a/AGENTS.md +++ b/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 和项目文档默认优先使用中文。代码标识符、命令、配置键、上游专有名称，以及 使用英文能避免歧义的技术字段可保留英文。 diff --git a/CLAUDE.md b/CLAUDE.md index 9830a79..ed74093 100644 --- a/CLAUDE.md +++ b/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. 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； diff --git a/docs/superpowers/RETIRED.md b/docs/superpowers/RETIRED.md index c971323..a9181dc 100644 --- a/docs/superpowers/RETIRED.md +++ b/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 - `/README.md` — how a service actually works