Kibotos

在一台机器上试用

本页在一台 Linux 机器上装好 ctrl、node，以及它们依赖的 PostgreSQL 与对象存储，再构建一个 Template，最后创建第一个 Workspace，下载之外的步骤十几分钟就能做完。适合在正式部署前先评估 Kibotos。

这样装出的部署只适合评估：所有组件只监听本机，对象存储直接用管理员凭证，数据只在这一台机器上。正式部署见安装概览。

概述

装完后这台机器上运行着：

组件来源监听
PostgreSQL发行版的包127.0.0.1:5432
Silo，一个 S3 兼容的对象存储Silo 发布的 Debian 包127.0.0.1:9000
ctrl发布包里的 kibotos-ctrl127.0.0.1:18092（API）、127.0.0.1:18101（node 接入）
node，使用 KiboVM 后端发布包里的 kibotos-node127.0.0.1:18091（数据面）
kibo 与 kibo-build发布包不监听

ctrl 与 node 的证书按名字签发。本页把 ctrl.kibotos.test 与 node-a.nodes.kibotos.test 两个名字写进 /etc/hosts，都指向 127.0.0.1。kibo 也在这台机器上运行。

前提条件

  • 一台 Debian 13 amd64 机器，本页在它上面验证过。至少 4 个 CPU、8 GiB 内存、40 GiB 空闲磁盘。
  • 存在 /dev/kvm 与 /dev/net/tun，使用 cgroup v2，开启了时间同步。虚拟机里试用要打开嵌套虚拟化。
  • 可以用 sudo，能访问公网：要下载发布包、Silo 和 Template 用的容器镜像。
  • 发布包从 GitHub 下载，需要一个对 Kibotos 源码仓库有读取权限的 GitHub 账号。
  • 这台机器上没有运行 Docker。Docker 会把 FORWARD 链的默认策略改成 DROP，Workspace 就不能访问网络，见排查。

下面的步骤在同一个终端里依次执行，后面的步骤会用到前面设置的变量。

步骤

1. 检查宿主机

确认虚拟化设备、cgroup 版本与时间同步：

ls -l /dev/kvm /dev/net/tun
stat -fc %T /sys/fs/cgroup
timedatectl show -p NTPSynchronized

第二条应输出 cgroup2fs，第三条应输出 NTPSynchronized=yes。

2. 下载发布包

安装用到的工具，登录 GitHub，然后下载并校验一个版本的发布包。把 version 换成要试用的版本：

sudo apt-get install -y gh jq curl openssl
version=1.2.3
gh auth login
gh api -H 'Accept: application/vnd.github.raw' \
  "repos/felinics/kibotos/contents/scripts/fetch-release.sh?ref=v$version" > fetch-release.sh
bash fetch-release.sh "v$version"
cd "kibotos-releases/v$version"
sha256sum --check SHA256SUMS

之后的命令都在这个目录里执行。

3. 安装 PostgreSQL 与 Silo

安装 PostgreSQL，为 ctrl 建一个账号和数据库：

sudo apt-get install -y postgresql
db_password=$(openssl rand -hex 16)
sudo -u postgres psql -c "CREATE ROLE kibotos LOGIN PASSWORD '$db_password'"
sudo -u postgres createdb -O kibotos kibotos

下载并安装 Silo，让它只监听本机，数据放在 /var/lib/silo：

silo_release=https://github.com/pgsty/silo/releases/download/RELEASE.2026-09-16T00-00-00Z
curl -fLO "$silo_release/silo_20260916000000.0.0-1PGSTY_amd64.deb"
curl -fLO "$silo_release/silo_20260916000000.0.0-1PGSTY_amd64.deb.sha256sum"
sha256sum --check silo_20260916000000.0.0-1PGSTY_amd64.deb.sha256sum
sudo apt-get install -y ./silo_20260916000000.0.0-1PGSTY_amd64.deb
silo_password=$(openssl rand -hex 16)
sudo install -d -o silo -g silo -m 0700 /var/lib/silo
sudo install -m 0600 /dev/null /etc/default/silo
sudo tee /etc/default/silo >/dev/null <<EOF
MINIO_VOLUMES="/var/lib/silo"
MINIO_OPTS="--address 127.0.0.1:9000 --console-address 127.0.0.1:9001"
MINIO_ROOT_USER="kibotos"
MINIO_ROOT_PASSWORD="$silo_password"
EOF
sudo systemctl enable --now silo.service

创建 ctrl 使用的 bucket。curl 用 S3 签名直接调用 Silo 的 API：

until curl -fsS http://127.0.0.1:9000/minio/health/live; do sleep 1; done
curl -fsS --aws-sigv4 'aws:amz:us-east-1:s3' --user "kibotos:$silo_password" \
  -X PUT http://127.0.0.1:9000/kibotos-artifacts

4. 准备名字

把 ctrl 与 node 的名字指向本机：

printf '%s\n' '127.0.0.1 ctrl.kibotos.test node-a.nodes.kibotos.test' | sudo tee -a /etc/hosts >/dev/null
getent hosts ctrl.kibotos.test node-a.nodes.kibotos.test

5. 安装并启动 ctrl

安装 ctrl 的包，写配置：

sudo apt-get install -y "./kibotos-ctrl_${version}_amd64.deb"
sudo install -o kibotos-ctrl -g kibotos-ctrl -m 0600 /dev/null /etc/kibotos/ctrl/config.toml
sudo tee /etc/kibotos/ctrl/config.toml >/dev/null <<EOF
[database]
dsn = "postgresql://kibotos:$db_password@127.0.0.1:5432/kibotos"

[identity]
trust_domain = "kibotos.test"
host = "ctrl.kibotos.test"

[storage]
root = "/var/lib/kibotos/ctrl"

[api]
listen = "127.0.0.1:18092"

[node_api]
listen = "127.0.0.1:18101"

[data_plane]
host_suffix = "nodes.kibotos.test"

[template_artifact_store]
endpoint = "127.0.0.1:9000"
region = "us-east-1"
bucket = "kibotos-artifacts"
namespace = "trial"
secure = false
path_style = true
credential_source = "static"
access_key_id = "kibotos"
secret_access_key = "$silo_password"
EOF

初始化 ctrl，签发第一个 Operator 的注册密钥，然后启动服务：

sudo -u kibotos-ctrl kibotos-ctrl init --config /etc/kibotos/ctrl/config.toml
sudo -u kibotos-ctrl kibotos-ctrl migrate --config /etc/kibotos/ctrl/config.toml
sudo -u kibotos-ctrl kibotos-ctrl enrollment create \
  --config /etc/kibotos/ctrl/config.toml --operator admin \
  --output /var/lib/kibotos/ctrl/operator-enrollment.key
sudo systemctl enable --now kibotos-ctrl.service

6. 安装 kibo 并注册

安装 kibo，用刚才的密钥建立 Operator 身份：

sudo install -m 0755 "kibo_${version}_linux_amd64" /usr/local/bin/kibo
(umask 077; sudo cat /var/lib/kibotos/ctrl/operator-enrollment.key > operator-enrollment.key)
sudo rm /var/lib/kibotos/ctrl/operator-enrollment.key
kibo context enroll --endpoint https://ctrl.kibotos.test:18092 --key-file operator-enrollment.key
rm operator-enrollment.key
kibo version

kibo version 的输出里应有 Compatible yes。

7. 安装 node 并加入

为 node 签发注册密钥，安装 node 的包，打开 IPv4 转发：

kibo enrollment create --node node-a --output node-enrollment.key
sudo apt-get install -y "./kibotos-node_${version}_amd64.deb"
printf '%s\n' 'net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/60-kibotos-forward.conf >/dev/null
sudo sysctl -p /etc/sysctl.d/60-kibotos-forward.conf

写 node 的配置。它给 Workspace 2 个 CPU、4 GiB 内存，从默认路由所在的网卡访问公网：

uplink=$(ip -4 route show default | awk '{print $5; exit}')
sudo install -m 0600 /dev/null /etc/kibotos/node/config.toml
sudo tee /etc/kibotos/node/config.toml >/dev/null <<EOF
[backend]
type = "kibovm"

[resources]
cpu_limit = 2
memory_limit = "4G"

[storage]
root = "/var/lib/kibotos/node"
template_cache_limit = "10G"

[[storage.pool]]
id = "node-a"
path = "/var/lib/kibotos/node"

[runtime]
socket_root = "/run/kibotos/node"

[data_plane]
listen = "127.0.0.1:18091"
advertise = "https://node-a.nodes.kibotos.test:18091"

[ctrl]
endpoint = "https://ctrl.kibotos.test:18101"

[host_network]
address_families = ["ipv4"]
ipv4_pool = "100.64.0.0/16"

[host_network.public_internet]
ipv4_upstream_interface = "$uplink"
resolvers = ["1.1.1.1"]
EOF

初始化存储池，加入集群并启动：

sudo kibotos-node storage-pool init --id node-a --path /var/lib/kibotos/node
sudo kibotos-node join --config /etc/kibotos/node/config.toml --key-file node-enrollment.key
rm node-enrollment.key
sudo systemctl enable --now kibotos-node.service

等 node 变成 READY，再给它的存储池设置容量：

until kibo node get node-a | grep -q READY; do sleep 2; done
kibo storage-pool set-capacity node-a 20G
kibo node list

8. 发布 Platform

Platform 是 Workspace 启动用的内核与 guest 程序，发布包里已经构建好。发布、批准并设为默认：

kibo platform publish "kibotos-platform-kibovm_v${version}_amd64.tar.zst" --json > platform.json
platform_revision=$(jq -er '.result.platform.revision' platform.json)
kibo platform approve "$platform_revision"
kibo platform set-default "$platform_revision"

9. 构建并发布 Template

Template 决定 Workspace 里装了什么。这里从 Docker Hub 的官方镜像 buildpack-deps:trixie-curl 导入一个带 curl 的 Debian 系统。安装构建工具，查出镜像的精确摘要，写定义文件：

sudo apt-get install -y "./kibo-build_${version}_amd64.deb"
digest=$(skopeo inspect --format '{{.Digest}}' docker://docker.io/library/buildpack-deps:trixie-curl)
sudo install -d /srv/templates/debian
sudo tee /srv/templates/debian/template.json >/dev/null <<EOF
{
  "schema": "kibotos.template-definition/v1",
  "template_id": "debian",
  "display_name": "Debian 13 with curl",
  "description": "Imported from docker.io/library/buildpack-deps:trixie-curl",
  "platform": "linux/amd64",
  "architecture": "x86_64",
  "source": {
    "kind": "registry",
    "reference": "docker.io/library/buildpack-deps@$digest"
  },
  "platform_requirements": {
    "guest_protocol": 1,
    "rootfs_contract": 2
  },
  "guest": {
    "capabilities": ["filesystem.v1", "process.v1", "application-config.v1"],
    "ready_semantics": "vsock-http-ready/v1"
  },
  "required_capabilities": {},
  "rootfs": {
    "size_mib": 1024
  },
  "process_defaults": {
    "shell": "/bin/bash"
  }
}
EOF

构建，然后发布、批准并设为默认：

template_result=$(sudo kibo-build template /srv/templates/debian/template.json)
kibo template publish "$template_result" --json > template.json
template_revision=$(jq -er '.result.template.revision' template.json)
kibo template approve debian --revision "$template_revision"
kibo template set-default debian --revision "$template_revision"
kibo template list

10. 创建第一个 Workspace

创建一个 Workspace，在里面运行命令，再删除它：

workspace_id=$(kibo workspace create --template debian -q)
kibo workspace exec "$workspace_id" -- cat /etc/debian_version
kibo workspace delete "$workspace_id" --yes

第一次使用一个 Template 时，node 要先下载并解压 rootfs，创建会多花一些时间。

到这里部署已经可以使用。接下来按快速开始的第 3 步往后操作，Template 用 debian。

注意

  • 所有组件只监听 127.0.0.1，kibo 只能在这台机器上使用。要从别的机器访问，把配置里的监听地址改成 0.0.0.0，并让那台机器把两个名字解析到这台机器的地址。发布 Template 直接上传到对象存储，所以还要让 Silo 监听可达的地址，并把 ctrl 配置里对象存储的 endpoint 改成这个地址。
  • 对象存储用的是 Silo 的管理员凭证。正式部署给 ctrl 一个只能访问自己 bucket 的身份，见准备 bucket 与权限。
  • 数据只在这台机器上，没有备份。ctrl 的 PKI 在 /var/lib/kibotos/ctrl，丢了要让所有 node 与 Operator 重新注册。
  • 正式部署可以把 ctrl 与 node 装在不同机器上，按安装概览的顺序进行。

排查

现象原因处理
kibotos-ctrl.service 反复重启数据库或对象存储连不上，或凭证不对看 sudo journalctl -u kibotos-ctrl.service -n 50，reason 字段说明是哪一项
node 一直不是 READYnode 没有启动，或连不上 ctrl看 sudo journalctl -u kibotos-node.service -n 50
创建 Workspace 失败存储池还没有设置容量，或 Platform、Template 没有设为默认按错误信息补做第 7 步的最后一段，或第 8、9 步
node 日志有 node offers no public internet egress没有打开 IPv4 转发，或 FORWARD 链的默认策略是 DROP（例如装了 Docker）按日志里写的原因修好，执行 sudo systemctl restart kibotos-node.service
kibo-build 下载镜像失败这台机器访问不了 Docker Hub换一个能访问的镜像仓库，把定义文件里的 reference 改成那里的镜像

卸载

停止服务，卸载各个包，再删除本页创建的数据：

sudo systemctl disable --now kibotos-node.service kibotos-ctrl.service silo.service
sudo apt-get purge -y kibotos-node kibotos-ctrl kibo-build silo
sudo rm -rf /etc/kibotos/node /etc/kibotos/ctrl /var/lib/kibotos/node /var/lib/kibotos/ctrl \
  /var/lib/kibotos/build /var/lib/silo /etc/default/silo /srv/templates/debian \
  /etc/sysctl.d/60-kibotos-forward.conf
sudo -u postgres dropdb kibotos
sudo -u postgres dropuser kibotos
sudo sed -i '/ctrl\.kibotos\.test/d' /etc/hosts
rm -rf ~/.config/kibo/context

下一步

安装概览

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

本页内容

概述前提条件步骤1. 检查宿主机2. 下载发布包3. 安装 PostgreSQL 与 Silo4. 准备名字5. 安装并启动 ctrl6. 安装 kibo 并注册7. 安装 node 并加入8. 发布 Platform9. 构建并发布 Template10. 创建第一个 Workspace注意排查卸载下一步