升级 Zeabur

查看当前的 Zeabur 版本，按安装方式用 zeabur-installer、Helm、Argo CD、Flux 或 zeaburctl 升级，并在升级后确认新版本。

先看你是怎么安装的，再按对应的小节升级。升级不会自动发生，Zeabur 只会告诉你有新版本。

查看版本

集群页面始终显示 Zeabur v<版本>。有新版本时，页面会出现通知，附上新版的版本号和发行说明链接。“设置”›“关于”也会显示版本。在这两个地方点击“升级方法”，都会按你的安装方式列出步骤，附上可以复制的命令和这一页的链接。

用 zeaburctl ui 打开时，页面显示的是 zeaburctl 自己的版本。检查更新的细节，以及怎么关掉通知，见检查更新。

升级前

到 GitHub Releases 阅读要升级的版本的发行说明。
读升级须知，跨过几版就读那几节，先把每一版要做的事做完。
先给服务器或集群留一份快照。需要退回旧版时，只能还原升级前的快照，见退回旧版。
项目的数据另外用 Velero 备份，见备份集群并从备份还原。

用 zeabur-installer 升级

团队使用和个人使用的做法相同。

到发行文件与验证下载新版的 zeabur-installer-v<版本>-linux-<架构>.tar.gz，验证后解压，用它替换服务器上原来的 zeabur-installer，例如 /usr/local/bin/zeabur-installer。服务器上没有 gh 或 cosign 的话，可以在自己的电脑上下载和验证，再把压缩包传到服务器。
用同一份配置文件预览变更：
```
sudo zeabur-installer plan
```
集群里有安装记录时，plan 的开头是 Changes since the last apply，列出会升级的 K3s、RKE2 或 KubeSolo 版本、Zeabur 和 Zeabur Identity 的版本、会改的主机文件、新增或移除的组件，以及要换版的 chart。
确认后应用：
```
sudo zeabur-installer apply
```

K3s、RKE2 或 KubeSolo 的版本或主机文件有变时，apply 会重启 k3s、rke2-server 或 kubesolo。Kubernetes API 约有 10 秒不响应，运行中的应用照常服务。

每版 installer 固定一个 K3s、RKE2 或 KubeSolo 版本，由 apply 安装。Kubernetes 只能这样升级：用其他方式升级（例如 System Upgrade Controller 的 Plan），下次 apply 会装回 installer 固定的版本。

集群还有其他节点，而 plan 把 replicated-storage/longhorn 列为新增时，也要在每个节点换上新版 installer 并运行 sudo zeabur-installer apply。它会在该节点安装 Longhorn 需要的软件包和内核模块，再重启该节点的 Longhorn manager，因为 manager 只在启动时检查节点。

服务器内存低于新版对团队使用的最低要求时，已在运行的安装仍会升级，plan 会显示警告，并保留现有的组件。

用 AI Agents 升级

也可以让 Claude Code、Codex 这类 AI Agents 按上面的步骤帮你升级。请先给服务器留一份快照，再让 AI Agent 能用 SSH 连到服务器，账号要能运行 sudo，并用密钥登录。

把下面这段粘贴给 AI Agent，并把 <user>@<server> 换成你的服务器：

请帮我升级 <user>@<server> 这台服务器上的 Zeabur，用 SSH 连接，需要 root 的命令用 sudo。

1. 运行 zeabur-installer --version 查当前的版本。目标版本是 https://github.com/zeabur-oss/zeabur/releases 上最新的发行版，除非我另外指定。把两个版本告诉我。
2. 把 /etc/zeabur-installer/config.yaml 复制一份备份。
3. 按 https://oss.zeabur.com/zh-CN/docs/zeabur/reference/releases/ 的“下载与验证可执行文件”，下载目标版本的 zeabur-installer，按服务器的 `uname -m` 选择 linux-amd64 或 linux-arm64。验证 SHA256SUMS 的签名、文件的 SHA-256 和构建来源，三项都通过才解压。任何一项没通过就停下来告诉我，不要为了让验证通过而修改验证参数。服务器上没有 gh 或 cosign 的话，在这台电脑上验证，再把压缩包传到服务器。解压后，把旧的 zeabur-installer 改名留着，换上新版。
4. 读 https://oss.zeabur.com/zh-CN/docs/zeabur/upgrade/notes/，对当前版本到目标版本之间的每一节，按“用 zeabur-installer 安装”的步骤修改配置文件，把改了哪些地方给我看。要删除组件或数据的步骤，先告诉我，等我同意再做。
5. 用新版运行 sudo zeabur-installer plan，把新增和移除的组件、要换版的部分、警告和没通过的检查整理给我看，等我确认再继续。
6. 我同意后运行 sudo zeabur-installer apply。中途失败时，先修好原因，再用同一份配置重新运行。
7. 升级须知要求其他节点重新加入时，问我每个节点怎么用 SSH 连接，再照着做。
8. 运行 sudo zeabur-installer doctor，汇报结果。退出码 1 表示只有警告。

用 Helm 升级

把 <版本> 换成要升级的版本：

helm upgrade zeabur oci://ghcr.io/zeabur-oss/charts/zeabur \
  --version <版本> \
  --namespace zeabur --reset-then-reuse-values
kubectl -n zeabur rollout status deployment/zeabur

--reset-then-reuse-values 会先采用新版 chart 的默认值，包括镜像，再应用你之前设置的值。用 --reuse-values 的话，镜像会停在旧版。

用 Argo CD 升级

把 Argo CD Application 里的 chart 版本改成新版，再同步。Argo CD 不连集群就生成 manifest，所以要事先创建固定的签名密钥并设置 planKey.existingSecret，做法见用 GitOps 管理 chart。

用 Flux 升级

把 Flux HelmRelease 里的 chart 版本改成新版，提交后等 Flux 同步。

用 zeaburctl ui 升级

Zeabur 运行在你自己的电脑上，没有服务器要升级。到发行文件与验证下载新版 zeaburctl，验证后替换旧文件，再运行一次 zeaburctl ui。

升级后

Zeabur 的副本换新后，所有人都要重新登录。chart 只运行一个副本，会话保存在内存里。
运行 zeabur-installer --version 或 zeaburctl --version，或打开集群页面，确认版本。
Helm、Argo CD 和 Flux 可以运行 kubectl -n zeabur rollout status deployment/zeabur，等新的副本就绪。

退回旧版

要退回旧版 installer，还原升级前的快照。较新版的 installer 写过安装记录后，旧版的 plan 和 apply 会停下，并写明要改用哪一版，见 Installer 命令。