安装概览

本页介绍首次部署 Kibotos 涉及哪些机器、外部依赖与前提条件。

各组件的安装步骤按下面的顺序：

重装与升级见重装与升级，卸载见卸载。只想先在一台机器上评估时，见在一台机器上试用。

概述

一次部署涉及下面几类机器，每种角色各有自己的文档。

角色	需要什么	使用的凭证	文档
构建机（release host）	Debian 13 或 Ubuntu 24.04 amd64、固定的工具链、两个 VM runtime 的精确输入	下载上游输入的访问权限	构建发布包
Operator 工作机	`kibo`，能访问 ctrl 的 HTTPS 端口与 artifact store	由 ctrl 签发的 Operator 身份	身份与注册
Template 构建机（build host）	`kibo-build`、源码、独立账户和构建目录，以及相应的构建工具	不需要任何 Operator、ctrl 或 store 凭证	在构建机上构建并发布
ctrl 宿主机	`kibotos-ctrl` 包，外部 PostgreSQL 与 artifact store	ctrl 自己的 PKI、数据库与 store 凭证	安装 ctrl
node 宿主机	`kibotos-node` 包，systemd、cgroup v2、可读写的 KVM/TUN 设备，能访问 ctrl 与 store	加入集群时获得的 node 身份	安装 node
E2B 网关宿主机（可选）	`kibotos-e2b` 包与 HTTPS 反向代理（无状态；每个实例需要自己的身份）	网关专用的 Operator 身份与对外 API key	安装 E2B 网关
Exposure 网关宿主机（可选）	`kibotos-gw` 包，以及接到专用域名的 tunnel（无状态；每个实例需要自己的身份）	网关专用的 Operator 身份；tunnel 凭证只留在运行 tunnel 的宿主机上	安装 Exposure 网关

ctrl、E2B 网关与 Exposure 网关也可以用发布的容器镜像运行在 Kubernetes 或 Docker 上，见用容器运行。node 只装在宿主机上，见安装 node。

外部依赖：

PostgreSQL 与 S3 兼容的 artifact store 由部署方自行运营，包括可用性与备份。
ctrl 的全部读写都要发到 PostgreSQL 主库，中间可以有连接代理或连接池；kibotos-ctrl migrate 要直连主库，见数据库的连接方式。
ctrl 只用自己宿主机的时钟写入和判定时间（发布、到期、Exposure 的截止时刻），PostgreSQL 服务器的时钟不参与。托管数据库的时钟偏差不影响 ctrl，但 ctrl 与每台 node 的宿主机都要开启时间同步，见时间同步。
公共 DNS 与 HTTPS 反向代理只有接入 E2B SDK 时才需要。Kibotos 自己的 PKI 不依赖公共 CA。
实例指标存储只有要让 E2B SDK 读取 sandbox 指标时才需要，同样由部署方运营，见实例指标存储。
服务与集群的指标、日志由部署方采集，见集群与服务指标与日志。trace 存储同样可选，见链路追踪。

宿主机运行 Debian 13、Ubuntu 24.04 或更新版本，amd64。
首次安装时所有组件来自同一个发布包。之后 ctrl 与 node 可以是同一发布线（同一 MAJOR.MINOR 的正式版本与 -rc.N 版本）上的不同版本，见同一 MINOR 内逐台升级。
源码仓库尚未公开，发布包从 GitHub Release 下载需要有仓库读取权限的账号。用 GitHub CLI 登录一次，再用源码仓库里的 scripts/fetch-release.sh 下载。脚本可以单独复制到宿主机运行，它下载指定版本的全部附件到 ./kibotos-releases/<tag>/，核对每个文件的大小与摘要、检查 SHA256SUMS 覆盖了全部文件，并恢复二进制的可执行位；任何一步失败都不会留下目录。目标目录已存在时不覆盖，根目录可用 --dir 改：

gh auth login
bash fetch-release.sh v1.2.3
cd kibotos-releases/v1.2.3

sha256sum --check SHA256SUMS
./kibo_1.2.3_linux_amd64 version --client --json

发布包里只有 Operator CLI 是可直接执行的文件，其余组件都以 Debian 包交付。它们的版本在装包之后核对，例如 kibotos-ctrl version --json。

包依赖与系统账户：

ctrl 包依赖 ca-certificates、systemd、systemd-sysv。
node 包还依赖 libguestfs-tools、e2fsprogs 1.47.0 或更新版本，以及 AppArmor 4 或更新版本。
每个包创建自己的系统账户：ctrl 包创建 kibotos-ctrl，node 包创建 kibotos-vmm 与 kibotos-egress，E2B 网关包创建 kibotos-e2b，Exposure 网关包创建 kibotos-gw。kibotos-vmm 属于 kvm 组；kibotos-egress 是出口进程的运行账户，见出口进程。
node 宿主机必须实际存在 /dev/kvm 和 /dev/net/tun。包依赖不检查设备。

每台 ctrl 与 node 宿主机都要开启时间同步。 node 用自己的时钟验证数据面凭证；ctrl 在每次与 node 对账时测量两边的时钟偏差，偏差超过 30 秒的 node 不再接收新的 Workspace，它上面已有的 Workspace 照常运行。

chrony 与 systemd-timesyncd 都可以。所有宿主用同一类时间源：闰秒抹平的源（云厂商的内网时间服务多是这种）与不抹平的源（例如 pool.ntp.org）不要混用，闰秒前后两类源会差出将近一秒。

ctrl 与 node 的服务单元排在 time-sync.target 之后。要让开机时真正等到时钟同步，启用对应的等待服务：

sudo systemctl enable chrony-wait.service            # chrony
sudo systemctl enable systemd-time-wait-sync.service # systemd-timesyncd

确认同步：timedatectl show -p NTPSynchronized 应输出 NTPSynchronized=yes。用 chrony 时，chronyc tracking 的 System time 一行是本机与时间源的偏差。
node 加入集群后，kibo node get <node> 的 Latest session 一节有两行：Clock offset 是 ctrl 最近一次测得的偏差（node 减 ctrl），Clock sync 是 node 宿主内核报告的同步状态。kibo node list 的 CLOCK 列显示偏差，超过 30 秒时标 (over)，ctrl 日志也会记一条。修好时间同步后，下一次对账（最多 1 分钟）这台 node 就恢复接收 Workspace。