将 Zeabur 安装到已有集群

先在 Zeabur Identity 注册 Zeabur 客户端，将 client secret 存入集群，再安装 Helm chart。完成后，打开 Zeabur 网址，用通行密钥登录并查看已有的 Namespace。

先准备登录与 HTTPS

• 可管理目标集群的 kubeconfig，以及 kubectl、Helm 4 和 zeabur-identityctl。
• Kubernetes 1.30 或更高版本。chart 默认会创建项目成员角色，并用 ValidatingAdmissionPolicy 限制开发者可以修改的 Namespace 字段。这个 API 从 1.30 起正式可用。
• 已支持 HTTPS 登录的 Zeabur Identity，且 kube-apiserver 已信任它签发的 Kubernetes 令牌。安装方法见 Zeabur Identity 入门。
• Zeabur 的 HTTPS 域名、可用的 Ingress controller，以及该域名的 TLS 机密变量。以下使用 Traefik、zeabur.example.com 和 zeabur-tls。
• 要安装的 Zeabur 版本。chart 发布在 oci://ghcr.io/zeabur-oss/charts/zeabur，默认镜像已固定为同一版本的 digest。下载与验证方法见发布产物。以下用 <version> 表示版本号。

Zeabur 自身的登录域名与之后部署服务的公开域名需要分别配置。先确保能登录管理界面，再准备应用的 DNS 和证书。

注册 Zeabur 客户端

以下使用 https://identity.example.com 作为 Identity issuer。将两个域名替换为实际值，并使用集群管理员的 kubeconfig 运行：

zeabur-identityctl client create zeabur \
  --type confidential \
  --audience kubernetes \
  --display-name Zeabur \
  --redirect-uri https://zeabur.example.com/auth/callback \
  --home-url https://zeabur.example.com/ \
  | kubectl apply -f -

命令会在 stderr 显示一次 client secret。创建 Namespace 后，在 Bash 中交互式读取这个值，不放入命令参数：

kubectl create namespace zeabur
read -rs CLIENT_SECRET
printf %s "$CLIENT_SECRET" | kubectl -n zeabur create secret generic zeabur-oidc \
  --from-file=client-secret=/dev/stdin
unset CLIENT_SECRET

运行 read 后粘贴 client secret，再按 Enter。这个值不在命令参数中，同一台机器上的其他用户就无法从进程列表中看到。chart 只记录机密变量的名称，实际值不会进入 Helm 的 release 记录。

安装管理界面

先确认 zeabur-tls 已位于 zeabur Namespace，再运行：

helm install zeabur oci://ghcr.io/zeabur-oss/charts/zeabur \
  --version <version> \
  --namespace zeabur \
  --set clusterName=production \
  --set publicUrl=https://zeabur.example.com \
  --set issuer.url=https://identity.example.com \
  --set issuer.clientSecret.existingSecret=zeabur-oidc \
  --set ingress.enabled=true \
  --set ingress.className=traefik \
  --set ingress.tls.secretName=zeabur-tls
kubectl -n zeabur rollout status deployment/zeabur

clusterName 是界面显示的集群名称。publicUrl 要与客户端的 callback 域名一致。chart 会拒绝使用 HTTP 或包含路径的公开网址。

这次安装会新增 Zeabur 的 Deployment、Service、Ingress、配置、签署检查变更的密钥，以及项目成员使用的 ClusterRole 和 Namespace admission policy。chart 不会将成员角色绑定给任何人。登录后，管理员在成员中设置每个人的访问范围。

管理员使用管理员账号登录后，就有整个集群的权限，无需在 Zeabur 中另外配置。管理员账号、登录时间和设置页中的登录设置，见权限。

登录并确认现有服务

打开 https://zeabur.example.com，完成通行密钥登录。进入项目，在其他 Namespace 中找到已有应用，打开查看服务。

要将这个 Namespace 固定列为项目，选择使用这个 Namespace，检查并应用。这只会添加项目标签，不会移动其中的 Deployment、Service 和数据。

如果能登录却看不到服务，先确认该用户的 Kubernetes 权限：Zeabur 使用登录者自己的令牌读取集群，Zeabur 自己的 ServiceAccount 只能在 zeabur-terminals 中使用 kubectl 终端的副本。管理员可以在成员中授予项目角色。

让新服务有公开网址

准备应用域名，例如 apps.example.com。将 *.apps.example.com 的 DNS 指向 Ingress controller 的入口，并准备可签发证书的 cert-manager ClusterIssuer，例如 letsencrypt。更新同一个 release：

helm upgrade zeabur oci://ghcr.io/zeabur-oss/charts/zeabur \
  --version <version> \
  --namespace zeabur --reset-then-reuse-values \
  --set 'domains.suffixes={apps.example.com}' \
  --set domains.clusterIssuer=letsencrypt

加上 --reset-then-reuse-values 后，Helm 会先采用新版 chart 的默认值（包括镜像），再套用你设置过的值。改用 --reuse-values 时，Helm 会连旧版 chart 的默认值一起保留，镜像就停在旧版。

之后部署 shop 项目的 web 时，表单会建议使用 web-shop.apps.example.com。可以用逗号分隔多个应用域名，默认使用第一个。之后也能在集群页的域名区域修改，那里会检查 DNS 记录并列出需要添加的记录，方法见配置 DNS 记录。如果 domains.suffixes 留空，需要手动填写完整域名。如果 domains.clusterIssuer 留空，新服务的公开网址会使用 HTTP。

这里仅指定服务使用的签发者名称。需要提前准备好 ClusterIssuer 和 DNS，Zeabur 不会根据这两个值创建 ClusterIssuer 或 DNS 记录。

信任私有 CA

如果 Zeabur Identity、Registry、对象存储或 GitHub Enterprise 使用私有 CA 签发的证书，或集群通过会检查 TLS 的代理服务器访问外网，将 CA 证书放入 Zeabur 所在 Namespace 的配置文件，再设置 extraTrustedCA.configMap：

kubectl -n zeabur create configmap corp-ca --from-file=ca.crt=corp-ca.pem
helm upgrade zeabur oci://ghcr.io/zeabur-oss/charts/zeabur \
  --version <version> \
  --namespace zeabur --reset-then-reuse-values \
  --set extraTrustedCA.configMap=corp-ca

如果证书存放在机密变量中，改为设置 extraTrustedCA.secret。两者只能选一个。键名默认为 ca.crt，可以用 extraTrustedCA.key 修改，一个文件可以存放多张证书。

Zeabur 登录 Identity、读取镜像、读取对象存储中的备份、连接 GitHub 时，除了内置的 Mozilla CA，也会信任这些证书。Zeabur 只在启动时读取这个文件，修改配置文件后需要运行 kubectl -n zeabur rollout restart deployment/zeabur。

issuer.caBundle 和 builds.caBundle 由 zeabur-installer 设置，分别指向签发 Identity 证书的本地 CA 和 Zot 的 CA。Zeabur 会同时信任这两个 CA 和 extraTrustedCA，无需自行配置。

常见失败

情况	检查位置
浏览器无法打开 Zeabur	核对公开 DNS、Ingress class、TLS 机密变量和入口连接。先确认 Deployment 就绪，再检查入口。
登录后无法返回 Zeabur	核对 publicUrl、Identity 注册的 /auth/callback 和 issuer.url。
Identity 使用私有 CA	配置 extraTrustedCA，让 Zeabur 信任签发 Identity 证书的 CA。见信任私有 CA。
登录后读取请求遭拒	在 Identity 中确认成员身份与组，再核对目标 Namespace 的 RoleBinding。见权限参考。
新服务已就绪，但网址无法访问	核对应用域名的 DNS 和证书。管理界面与应用使用不同的域名，需要分别配置。
升级后需要重新登录	chart 只运行一个 Zeabur 副本，会话保存在内存中，副本替换后需要重新登录。

用 GitOps 管理 chart

Zeabur 用一个密钥签署已检查的变更。chart 在首次安装时创建这个密钥，之后通过 helm upgrade 升级时会读取并复用它。Argo CD 或 helm template 不连接集群就生成 manifest，每次都会生成新密钥，导致已检查但尚未应用的变更失效。这时先创建固定的密钥，再设置 planKey.existingSecret：

kubectl -n zeabur create secret generic zeabur-plan-key \
  --from-literal=plan-key="$(openssl rand -hex 32)"

将 planKey.existingSecret 设为 zeabur-plan-key。chart 的所有配置可用 helm show values oci://ghcr.io/zeabur-oss/charts/zeabur --version <version> 查看。

安装 Zeabur 需要的组件

如果集群不是用 zeabur-installer 安装的，Zeabur 的组件页只会显示状态，不会替你安装。用 zeaburctl components export 输出组件的 manifest，再用 kubectl 应用，或提交到 GitOps 仓库：

zeaburctl components export certificates/cert-manager --format flux > cert-manager.yaml

如果集群是 K3s 或 RKE2，使用默认的 helmchart 格式，交给内置的 helm-controller 安装。其他集群使用 helm、flux 或 argocd。

移除管理界面

helm uninstall zeabur --namespace zeabur

应用和提供入口、证书、存储空间的组件都会保留。chart 创建的成员角色会随 release 一起移除，成员的权限需要另外接管。完整保留清单与登录迁移步骤见移除 Zeabur。