zeabur-oss/zeabur · 上手攻略

  • 仓库：zeabur-oss/zeabur
  • 链接：https://github.com/zeabur-oss/zeabur
  • 分类：engineering / self-hosted PaaS / Kubernetes
  • 作者：spark
  • 更新：2026-10-30

0. 自检清单

项 状态
GitHub URL 已 fetch ✅ README（master 分支）+ API 元数据已拉取
Release tag / 版本 ✅ v0.1.1，GitHub API 确认 prerelease: true，发布于 2026-10-28
README 关键子模块 anchor ✅ Zeabur Catalog（独立仓库 zeabur-oss/catalog，Apache-2.0）、Zeabur Identity、Zeabur Builder + zot、Keel、CloudNativePG、Velero
官方文档 ✅ oss.zeabur.com/docs/zeabur/（英 / 繁中 / 简中）
顶会 / 论文 anchor ❌ 无（工业项目，非学术仓库，不适用）
提交基线 最后提交 2026-10-30；本攻略核对于 2026-10-30

⚠️ 版本浮动提示：仓库 README 自述状态为 pre-alpha (0.1.1)，API 可能继续变动。本文所有安装命令均按 v0.1.1 撰写；v0.1.x 与后续 v0.2+ 的子命令可能不兼容，请以你实际下载的 tag 的 SHA256SUMS 与文档为准。不要把它指向你承受不起损坏的集群。

1. 是什么

Zeabur 是一个自托管的 PaaS，但它的关键设计不是"再造一个 PaaS"，而是把你现有的 Kubernetes 集群包装成一个看得懂的图形界面。它由 Rust 编写（Apache-2.0），官方描述是 "Simple, secure deployments on your own Kubernetes."

四个特征值得注意：

  1. 无状态。 README 明确写着 "keeps no state of its own: no database, no custom resources"。Zeabur 不引入自己的 CRD、不引入自己的元数据库，它读你集群里已经存在的 Deployment / Service / Ingress。所以关掉 Zeabur，你的应用照跑——这是它和 Coolify、CapRover、 Dokku 这类"自带状态存储"的工具最本质的区别。
  2. 权限不越界。 "never acts with more rights than you have"——它用你自己的 kubeconfig 权限去操作你已经有权限的对象。
  3. 操作可审计。 每次创建服务前，界面会先列出将要创建的 Deployment / Service / Ingress 及其 YAML，让你 review 后再执行。这在自托管平台里是罕见的克制。
  4. 诊断用人话。 界面不止显示"CrashLoopBackOff"，而是告诉你服务为什么反复崩溃、证据是什么、该怎么修。

当前形态包含：把集群映射成"项目（project）"和"服务（service）"两层、诊断面板、滚动发布进度与 CPU/内存用量对比、域名与可达性检查、数据库连接信息与备份缺失告警、集群层面的 Kubernetes 版本 EOL 提示与节点内存/磁盘压力监控。

2. 解决什么问题

传统自托管部署的痛点在于：Kubernetes YAML 是给专家的工具，而绝大多数小团队的运维者不是专家。典型场景：

  • 你有一台 VPS，想在上面跑 3~5 个小服务，不想为了一个后端项目去背 Ingress、证书、存储类这些概念。
  • 你已经有 K8s 集群，但需要给不熟 K8s 的同事一个安全的图形入口，避免他们直接 kubectl apply 误删生产资源。
  • 你在用商业 PaaS（Zeabur 本身有商业版 SaaS），想把同样的体验搬到自己的机器上。

Zeabur 打的正是这个位置："像 PaaS 一样部署，但产出物就是标准 Kubernetes 对象"。

3. 快速安装

3.1 单机安装（推荐路径）

服务器要求（官方 quickstart 明确列出）：

  • Linux + systemd，amd64 或 arm64
  • root 权限
  • 内存 ≥ 4 GiB（低于此值只能选 "Just me" 个人模式）
  • /var/lib/rancher 剩余空间 ≥ 10 GiB（低于 30 GiB 安装器会告警）
  • TCP 端口 80、443、6443、10250 空闲；选 RKE2 还需 9345
  • 机器上不能已有 kubeadm / k0s / MicroK8s / KubeSolo，也不能有别的 K3s/RKE2

下载与运行：

# 从 GitHub Releases 下载对应架构的安装器（v0.1.1 为例）
# 文件名：zeabur-installer-v0.1.1-linux-<amd64|arm64>.tar.gz
sudo zeabur-installer gui

安装器默认只监听 127.0.0.1:8085，终端会打印带 token 的链接和一条已经填好服务器地址的 SSH 隧道命令：

# 另开一个本地终端执行
ssh -L 8085:127.0.0.1:8085 root@203.0.113.10

然后在浏览器打开 http://127.0.0.1:8085/?token=…，走五步向导：Server → Access → Components → Review → Install。

关键选择项：

  • Kubernetes 发行版：K3s（建议，内存占用小，适合 <8 GiB 服务器）或 RKE2（≥8 GiB，或计划三节点控制平面时）。两者硬化程度相同。
  • 域名：需要两个——"Zeabur"（访问面板）和 "Sign-in"（Zeabur Identity 登录）。没有域名可选 sslip.io 免 DNS 方案（zeabur.<ip>.sslip.io），Let's Encrypt 照样能签发证书。
  • 证书模式："Public domain" 用 Let's Encrypt；"Test server" 用服务器本地自建 CA——此时必须先下载并信任该 CA，否则 passkey 注册会失败。
  • 组件预设："Minimal"（Ingress + 证书 + metrics-server）/ "Standard"（默认，额外含 Zeabur Builder + zot、Keel 镜像更新、CloudNativePG PostgreSQL）/ "Hardened"（再加运行时威胁检测、漏洞扫描、入侵防御）。

安装耗时约 10~20 分钟（官方估计）。完成后：

sudo zeabur-installer doctor

退出码含义：0 健康 / 1 有告警 / 2 严重问题 / 3 无法执行检查（例如没用 root 跑）。

⚠️ 安全注意：官方明确写道——"Zeabur Builder 在特权 buildkitd 中构建，构建一旦逃出沙箱就等于拿到节点权限"，因此只应把 builder-system 和 zot 命名空间的管理权限给管理员。不需要 Git 部署的话，直接在组件列表里清掉 Zeabur Builder。

3.2 装进已有 K8s 集群

用 Helm chart：

helm install zeabur oci://ghcr.io/zeabur-oss/charts/zeabur \
  --namespace zeabur-system --create-namespace

登录走 Zeabur Identity。Chart 的 image.digest 在发布时已锁定到该 release 的镜像索引，所以用默认参数装出来的就是对应版本的镜像。

3.3 只给自己用（个人模式）

服务器内存 < 4 GiB 或你只有一个人时：

zeaburctl ui          # 监听随机 loopback 端口，自动开浏览器
zeaburctl ui --context <name>   # 换成别的 kubeconfig context

它用你当前的 kubeconfig context 发起所有请求，不需要在集群里装任何东西。

3.4 从源码构建

需要 Nix 开发环境（它提供全部工具链）：

git clone https://github.com/zeabur-oss/zeabur && cd zeabur
nix develop
./scripts/build-ui.sh
ZEABUR_UI_DIST="$PWD/web/dist" cargo build --release --locked -p zeaburctl
./target/release/zeaburctl ui

4. 核心用法

Zeabur 的日常使用主要在 Web 界面完成，命令行侧的关键工具是 zeaburctl。

# 查看版本
./zeaburctl --version

# 打开 UI（个人模式）
zeaburctl ui

# 指向其他 context
zeaburctl ui --context staging

4.1 发布第一个服务

界面流程：新建项目 → 新建服务 → 选择来源（Git 仓库或容器镜像）→ 绑定域名 → 看滚动发布进度。官方在 README 封面图里强调的核心承诺是：每次 review 一个新服务，它会把要创建的 Deployment、Service、Ingress 及其 YAML 列给你看，然后才创建。

4.2 诊断崩溃服务

界面里选中反复崩溃的服务，"What needs you" 面板会用日常语言说明原因、证据和修复动作，并按"问题来自哪里"分组（集群级 / 项目级 / 服务级），让你知道这个问题该找谁解决。

4.3 发布与域名

滚动发布面板给出实时进度，并把 CPU / 内存与 limits 对照显示；域名面板逐个检查"这个域名现在能不能从浏览器访问"，而不仅是"Ingress 是否创建成功"。

4.4 数据库与备份

数据库页面给出连接详情，并在没有任何实例会接管（即单实例 + 无备份）时告警。这是很多自托管事故的经典起点。

4.5 集群健康

集群页汇总：Kubernetes 版本的支持周期（会提示已 EOL 的版本）、节点内存与磁盘压力、备份状态、通知配置、已安装组件。

4.6 验证下载产物（供应链安全）

Zeabur 用 Sigstore keyless 签名 + GitHub attestation 做完整的可验证构建链，官方文档给了可复制的三步验证法：

version=0.1.1
platform=darwin-arm64      # 或 linux-amd64 / linux-arm64
binary=zeaburctl           # 或 zeabur / zeabur-installer
signer='^https://github\.com/zeabur-oss/\.github/\.github/workflows/release\.yml@'

gh release download "v$version" --repo zeabur-oss/zeabur \
  --dir "zeabur-$version" \
  --pattern SHA256SUMS \
  --pattern SHA256SUMS.sigstore.json \
  --pattern "$binary-v$version-$platform.tar.gz"

cd "zeabur-$version"

# 1) 校验签名者身份
cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp "$signer" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-github-workflow-repository zeabur-oss/zeabur \
  --certificate-github-workflow-ref "refs/tags/v$version" \
  SHA256SUMS

# 2) 校验文件内容
sha256sum --check --ignore-missing SHA256SUMS

# 3) 校验构建来源
gh attestation verify "$binary-v$version-$platform.tar.gz" \
  --repo zeabur-oss/zeabur \
  --signer-workflow zeabur-oss/.github/.github/workflows/release.yml \
  --source-ref "refs/tags/v$version"

三项全过之后才解压运行。macOS 上浏览器下载的文件带 quarantine 属性，还需 xattr -d com.apple.quarantine zeaburctl。官方态度很明确：签名/issuer/attestation 不匹配就别跑，也不要为了通过而放宽校验参数。

5. 典型适用场景

  • 小团队自托管：2~10 人团队，需要 Git push 即部署，但不想维护 K8s YAML。
  • 给非 K8s 同事的安全入口：把集群的一部分权限开放给团队成员，同时通过 YAML review 和权限不越界降低误操作风险。
  • 迁移出口：从商业 PaaS 迁回自托管，想要 PaaS 级 UI 但保留标准 K8s 对象。
  • 个人多服务托管：一台小服务器跑自己的 blog、API、数据库、静态站，zeaburctl ui 就够。
  • 多环境管理：用不同 kubeconfig context 切 staging / production。

6. 坑与注意

坑 1：它现在是 pre-alpha，官方明确说"别指向你承受不起损坏的集群"。 现象：功能/UI/文案都可能大改；影响：生产集群直接用有风险；修复：只在测试集群或你自己的小机器上试。修法：把安装配置存进版本控制，方便复现与回滚。

坑 2：磁盘未加密的告警不会阻断安装，但后果真实存在。 现象：安装器警告"secrets 已加密，但卷和数据库里的文件没有"；影响：数据库文件、备份文件在宿主机上是明文；修复：敏感数据选磁盘加密的 VPS 方案。很多 VPS 方案事后无法加密系统盘，所以这个选择要在购买时就做对。

坑 3："Test server" 模式必须先信任 CA，否则 passkey 注册直接失败。 现象：浏览器显示证书警告，注册 passkey 被拒；影响：卡死在安装最后一步；修复：安装向导里"Trust the certificate authority"下载证书并导入系统/浏览器信任。且其他访问你应用域名的电脑也要导入同一个 CA。

坑 4：sslip.io 免 DNS 方案有隐性前提。 现象：Test server + sslip.io 时，提示"这些域名必须通过 DNS 解析到本机，只改 hosts 文件是不够的"；影响：多副本时解析失败（副本不读 hosts）；修复：用真实 DNS 记录，或保证只有单副本。

坑 5：端口冲突。 现象：80/443/6443/10250（RKE2 另需 9345）被占用；影响：安装器检查失败、Install 按钮变灰；修复：Install 按钮在检查未过或内存估算为 "Not enough" 时是禁用的，先解决冲突。

坑 6：内存估算不足。 现象：组件选多了，估算显示 "Not enough"；影响：装完 OOM；修复：低配机器选 "Minimal" 预设，或按建议清掉用不到的组件；官方阈值是 4 GiB（个人）/ 8 GiB（RKE2）。

坑 7：Zeabur Builder 的特权 buildkitd 是真实的节点级攻击面。 现象：构建容器逃逸即可触达节点；影响：整台机器失守；修复：只把 builder-system 与 zot 命名空间的管理权给管理员；不用 Git 部署就清掉该组件。

坑 8：卸载只卸 Zeabur，不动集群。 现象：sudo zeabur-installer uninstall zeabur 后 K3s/RKE2、Zeabur Identity、应用全部还在；影响：以为"卸载干净了"其实留下了整套组件；修复：想彻底清理要走 /docs/zeabur/leave/uninstall 的完整卸载路径。

坑 9：macOS 只有 arm64 构建。 现象：Intel Mac 找不到二进制；影响：本地开发受阻；修复：Intel Mac 用 Linux 版（容器或远程），或直接在服务器上操作。

坑 10：管理员只有 passkey 一种登录方式，且 passkey 绑在注册设备上。 现象：换设备或丢失设备就无法登录；影响：把自己锁在集群外；修复：立刻注册第二个 passkey；日常操作用 Members 里的普通账号而不是管理员账号。注册链接过期可跑 sudo zeabur-installer setup-link 重新生成。

坑 11（待补）：API 与 CLI 子命令的具体稳定性。 ⚠️ README 只说明"API may still change"，没有给出 API 的版本化承诺或 CLI 子命令的兼容策略。v0.1.1 与后续版本的子命令是否同名同义，未见文档保证。跨版本使用前请先核对目标 tag 的 docs/reference/zeaburctl/。

7. 与同类对比

维度 Zeabur Coolify CapRover Dokku Argo CD
底层 K8s（K3s/RKE2） Docker Compose / K8s Docker Swarm Docker K8s
自身状态存储 无（不建 CRD、不建库） 有（Postgres） 有（Swarm 状态） 有（配置文件） 有（Redis）
权限模型 不超过你自己的 kubeconfig 权限 平台管理员权限 Docker group 即 root 等价 Docker group 即 root 等价 Argo 权限模型
核心交互 图形 + zeaburctl 图形 + CLI 图形 CLI 图形 + CLI
理念 把已有 K8s 包装成 PaaS 体验 自带一整套 PaaS 运行时 轻量、自包含 Git push 部署 GitOps 声明式同步

关键差异：Zeabur 不接管运行时。Coolify / CapRover / Dokku 会替你造出 Docker Compose 或 Swarm 的抽象；Argo CD 是 GitOps（声明期望状态、持续 reconcile），本质上是给懂 K8s 的人用的；Zeabur 站在中间——产出标准 K8s 对象，但用 PaaS 的语言和人话解释它们。

若你的团队已经是 K8s 熟手、想要声明式 + 审计追溯，Argo CD / Flux 更合适。若你连 K8s 都还没跑起来，Zeabur 的单机安装路径最省事。若你只想要"一个命令部署"，Dokku 更轻。

8. 一句话推荐结论

如果你有一台 Linux 服务器（或一个自管 K8s 集群）和一支不想学 YAML 的小团队，Zeabur 是目前最值得试的自托管 PaaS —— 它用标准 Kubernetes 对象换来 PaaS 级体验，且不引入自己的状态存储，代价是它现在仍是 pre-alpha(0.1.1)，请只在测试环境上手。

附：来源清单

  • https://raw.githubusercontent.com/zeabur-oss/zeabur/master/README.md（README 全文，已 fetch）
  • https://api.github.com/repos/zeabur-oss/zeabur（元数据：Rust / Apache-2.0 / 546 stars / pushed 2026-10-30）
  • https://api.github.com/repos/zeabur-oss/zeabur/releases（v0.1.1，prerelease，published 2026-10-28）
  • https://oss.zeabur.com/docs/zeabur/get-started/quickstart/（单机安装向导全文，已 fetch）
  • https://oss.zeabur.com/docs/zeabur/reference/releases/（产物校验与签名验证流程，已 fetch）
  • 仓库卡 organized/repo_cards/4728-zeabur-oss-zeabur.md