使用配置文件和命令安装
将安装选项写入 YAML，用 plan 检查、apply 安装，适合重复安装和版本控制。
将安装选项写入 /etc/zeabur-installer/config.yaml，用 plan 查看安装步骤，再用 apply 安装。这种方式适合将配置纳入版本控制、在多台机器上重复相同的安装，或通过自动化工具安装。
网页界面和命令读写同一份配置文件，安装的内容相同。你也可以在网页界面的“确认”步骤下载配置文件，再用命令安装。
准备服务器和 installer
Section titled “准备服务器和 installer”按照快速开始的服务器要求准备主机，并下载与架构匹配的 installer。
创建配置文件
Section titled “创建配置文件”以 root 权限创建 /etc/zeabur-installer/config.yaml。使用公开域名时，最小配置如下：
access: mode: domain identity: login.example.com zeabur: zeabur.example.com将这两个域名替换为要使用的域名。公开域名模式的 DNS 和端口要求，见快速开始的连接方式。
未填写 enable 和 disable 时安装默认组件，未填写 profile 时使用 single-node，未填写 distribution 时安装 K3s。服务器有 8 GiB 及以上内存，或以后想用三台服务器运行控制平面，就加上 distribution: rke2。
测试机可以改用 local 模式：
access: mode: local identity: login.<地址>.sslip.io zeabur: zeabur.<地址>.sslip.io将 <地址> 替换为服务器地址。
所有字段见 Installer 配置。sources 是可选字段，用于改用自行构建的 Catalog、镜像和 chart。未填写时使用 installer 固定的版本。
查看安装步骤
Section titled “查看安装步骤”运行：
sudo zeabur-installer planplan 会检查主机，并列出以下内容，不会改动主机：
- Kubernetes 的类型和版本（K3s 或 RKE2）。
- 组件和 chart。
- Namespace。
- 存储类。
- 网址。
- 空闲内存估算和警告。
如果有检查项未通过，输出会指出 apply 将停止。先解决这些问题，再开始安装。
需要 JSON 输出时，运行：
sudo zeabur-installer plan --jsonplan --json 不会检查主机。
没有配置文件时，plan 会根据这台服务器的地址生成 sslip.io 名称，以默认组件提供参考。服务器有公网地址时使用 domain 模式，否则使用 local 模式。运行 apply 前必须创建配置文件。
确认配置后运行：
sudo zeabur-installer applyapply 会先检查主机。只要有一项失败，就会在做出任何改动前停止。
检查通过后，依次配置主机、安装完成 CIS 加固的 K3s 或 RKE2、Namespace 和连接规则、存储空间、选定的组件，再安装 Zeabur Identity 和 Zeabur。
apply 根据运行时的配置计算安装内容。如果在运行 plan 后修改 YAML，apply 就会按新内容安装。
中断后继续安装
Section titled “中断后继续安装”解决中断原因后，用同一份配置重新运行：
sudo zeabur-installer apply每一步都会先检查已完成的部分，并从中断处继续。
注册管理员并登录
Section titled “注册管理员并登录”安装完成后，终端会输出：
- Zeabur 网址。
- Zeabur Identity 网址。
- 首位管理员的通行密钥注册链接。
使用 local 模式时，先将以下证书导入浏览器或系统的信任列表：
/var/lib/rancher/zeabur-installer/local-ca.crt打开注册链接，注册通行密钥，再打开 Zeabur 网址登录。
检查安装结果
Section titled “检查安装结果”运行：
sudo zeabur-installer doctor这会检查 K3s 或 RKE2、组件、默认存储类、Zeabur Identity 和 Zeabur。
| 退出码 | 结果 |
|---|---|
0 | 正常 |
1 | 警告 |
2 | 严重 |
3 | 无法运行检查，例如未以 root 身份运行 |
常见停止原因与处理方式
Section titled “常见停止原因与处理方式”| 遇到的情况 | 处理方式 |
|---|---|
| 端口被占用，例如还有其他 Kubernetes 在运行 | 先停止占用端口的程序，或换一台干净的主机，再运行 apply |
domain 模式的证书尚未签发 | 检查两个域名的 DNS，以及能否从外部访问 TCP 80 端口。修正后重新运行 apply |
local 模式下，浏览器提示证书不受信任 | 将 /var/lib/rancher/zeabur-installer/local-ca.crt 导入浏览器或系统的信任列表 |
| 首位管理员的注册链接已过期 | 在服务器上运行 sudo zeabur-installer setup-link，生成新链接 |
用 AI Agents 安装
Section titled “用 AI Agents 安装”要让 Claude Code、Codex 这类 AI Agent 按这一页的流程帮你安装，见让 AI Agent 帮你安装。
命令参考与添加节点
Section titled “命令参考与添加节点”gui、doctor、node add、uninstall 等命令及所有选项，见 Installer 命令。
要添加更多节点，见添加与维护节点。