安装 ctrl
本页介绍如何在宿主机上安装并初始化 ctrl、签发第一个 Operator 注册密钥。
以下命令在已校验的发布包目录中执行，版本号按实际修改。
1. 安装包并填写配置
sudo apt-get install ./kibotos-ctrl_1.2.3_amd64.deb
sudo install -o kibotos-ctrl -g kibotos-ctrl -m 0600 \
/usr/share/doc/kibotos-ctrl/ctrl.example.toml /etc/kibotos/ctrl/config.toml
sudoedit /etc/kibotos/ctrl/config.toml在配置中填写数据库、artifact store、identity.host 和数据面的名称。全部表与键见 ctrl 配置。
注意：
- 配置文件只允许
kibotos-ctrl读取。使用dsn_file时，该文件也要能被这个账户读取。 - 要提供 E2B sandbox 指标时，在这里一并填写
[metrics]段，见ctrl 的配置。 - 要导出 ctrl 自己的指标与集群状态时，填写
[telemetry]段，见集群与服务指标。它与[metrics]无关。 - 状态目录固定为
/var/lib/kibotos/ctrl，服务只能写这个目录。 - 安装包只创建账户与目录并重载 systemd。初始化、迁移、启用和启动都由下面的步骤完成。
数据库的连接方式
database.dsn 可以指向主库自己，也可以指向连接代理或连接池，条件是全部读写都发到主库。
| 地址 | 能否使用 | 要注意什么 |
|---|---|---|
| 主库自己，或故障切换时指向新主库的高可用地址 | 能 | |
| 云数据库的连接代理，例如 Amazon RDS Proxy | 能 | |
云数据库的读写分离地址，例如阿里云 RDS 的数据库代理地址（主机名通常含 rwlb） | 只读实例的读权重为 0 时能 | 读流量发往只读实例时不能用：ctrl 要读到自己刚写的数据，只读实例落后时它会按旧状态判断 |
| PgBouncer 会话模式 | 能 | |
| PgBouncer 事务模式 | 能 | 要 1.21 或更新的版本，max_prepared_statements 大于 0；DSN 不能带 search_path 这类连接参数 |
| 只读副本 | 不能 |
经过代理或连接池时，影响的只是性能：只有一个 ctrl 执行，由数据库里的执行权保证，与连接和数据库会话无关；连同一个数据库的第二个 ctrl 只应答读请求，见执行权。
kibotos-ctrl migrate 要直连主库。迁移工具用会话级锁防止两次迁移同时进行，事务级连接池会把这把锁留在别的客户端使用的会话上。迁移时用一份 database.dsn 指向主库的配置文件，其余命令不受这条限制。
数据库的切换会让连接上已准备的语句失效。经过代理时 ctrl 的连接不会断开，每条连接最多失败一次就换新，调用方看到的是可重试的错误。
判断 DSN 连到的是不是主库，多查几次，每次的第一列都要是 f：
psql "$DSN" -Atc 'select pg_is_in_recovery()'数据库连接数
ctrl 运行时最多占用 database.max_connections 条 PostgreSQL 连接，默认 32。PostgreSQL 的 max_connections 要容得下这个数，再加上其他客户端，以及 kibotos-ctrl 一次性命令（迁移、签发注册密钥等）的少量短连接。
| 配置项 | 默认值 | 含义 |
|---|---|---|
workspace.execution_concurrency | 16 | 全部 node 上同时执行的 Workspace 命令数，创建、启动与 Transfer 恢复一组、停止、删除与数据面撤销一组，两组各自按这个数计算；Transfer 的导出与导入一组、存储对象的搬迁一组，各按这个数的一半（至少 1）计算 |
database.max_connections | 32 | ctrl 占用的连接总数，不能小于 8 |
- 执行中的命令只在读写数据库时占连接，所以调高
execution_concurrency不要求调高连接数。 kibotos_ctrl_db_acquire_waits_total持续增长、请求变慢时，调高max_connections。- 连接上限只能写在
database.max_connections，DSN 里写pool_max_conns会被拒绝。 - ctrl 启动时在日志里记录一行
database connections，给出实际的并发与连接上限。
2. 准备 bucket 与权限
在启动 ctrl 之前，由存储管理员创建配置中的 bucket，并给 ctrl 的运行身份授权。
- 所需权限（对象读写、删除、multipart 上传、按前缀列举）见示例 policy，部署时把资源替换成实际的 bucket 和 namespace。自动回收对象存储要用到其中的删除权限。
- 权限覆盖两个前缀：
kibotos-template/v1/<namespace>/存放 Template 产物，kibotos-transfer/v1/<namespace>/存放 Transfer 归档。 - 创建 bucket 使用单独的管理身份。管理凭证不要写进 ctrl 配置。
- Transfer 归档是用户 Volume 里的数据。给 bucket 打开静态加密和访问审计，并把能读这个 bucket 的身份限制在 ctrl 的运行身份。
ctrl 每次启动都会检查存储是否可用：在开放 API 和启动后台任务之前，用运行身份先后在 kibotos-template/v1/<namespace>/staging/ 和 kibotos-transfer/v1/<namespace>/ 下各写入一个随机的小对象，读回校验后删除。整个检查限时 10 秒。
- 任何一步失败，ctrl 都不会启动。journal 中的
operation字段说明失败在写入、读取、校验还是删除，reason字段区分 bucket 不存在、权限不足、配置错误和存储不可达，并给出修复建议。 - 检查只使用这两个前缀的对象权限，不创建 bucket，也不发起 multipart 上传。
- 检查失败时会尽量删除已写入的对象。超时或没有删除权限时可能留下小对象，需要为 staging 前缀配置生命周期规则来回收。
- 这个检查只证明基本读写可用。multipart 上传等能力在第一次发布 Template 时验证。
- 运行期间的发布失败会在 journal 中记录阶段和 command/session 标识。存储的短暂故障不会让运行中的 ctrl 退出。
不支持 S3 条件写或附加校验和的存储（例如阿里云 OSS）同样可用：ctrl 改用 OSS 的禁止覆盖头，并把发布的每个 blob 读回校验，代价是每个 blob 在存储与 ctrl 之间多传一次。
阿里云 OSS 只支持 virtual-hosted 寻址，配置里写 path_style = false，endpoint 用不带 bucket 的地域域名（如 oss-cn-shenzhen.aliyuncs.com），bucket 单独填写。
3. 初始化、签发第一个 Operator 密钥并启动
umask 077
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 operator-a \
--output /var/lib/kibotos/ctrl/operator-enrollment.key
sudo systemctl enable --now kibotos-ctrl.service
sudo journalctl -u kibotos-ctrl.service --no-pager -n 50- 三条
kibotos-ctrl命令都必须用sudo -u kibotos-ctrl以服务账号执行。直接sudo会以 root 建出pki/，服务账号进不去，服务启动时报load managed PKI state: ... permission denied。init发现状态目录不属于当前账号会直接拒绝，提示用哪个账号重跑。已经用 root 建过的，用sudo chown -R kibotos-ctrl:kibotos-ctrl /var/lib/kibotos/ctrl/pki交还后再以服务账号跑一次init。 init可以重复执行，已初始化时输出unchanged。任何一步失败都先处理错误再继续。- 开机时 PostgreSQL 可能比 ctrl 晚就绪，例如数据库跑在本机容器里。ctrl 连不上数据库时退出，systemd 每 5 秒重启一次，直到数据库可用；这个间隔不会触发 systemd 默认的启动次数上限（10 秒内 5 次），不需要手工
reset-failed。日志里会反复出现connect ctrl PostgreSQL: ... connection refused，数据库就绪后自行消失。 - 数据库长期不可用时 ctrl 会一直重试。想让 ctrl 等数据库的服务就绪后再启动，可以用
systemctl edit kibotos-ctrl.service加上对该服务的After=与Wants=。 - 注册密钥（enrollment key）由
kibotos-ctrl账户写入自己的状态目录，权限0600。管理员读取后通过安全渠道交给 Operator，不需要放宽文件权限。 - PKI 的续期与恢复见身份、配置与连接。
警告
serve 第一次启动时在 storage.root 下生成 credential-keys/，里面的密钥加密数据库中保存的调用方凭证（如 Egress 的用户名与口令）。它不进数据库，要和 pki/ 一起备份：丢失后这些凭证无法解密，只能由调用方重新写入。
自动回收对象存储
ctrl 启动 10 分钟后开始自动回收对象存储，之后每 24 小时一次。它只删除满足全部条件的 manifest 与 blob：撤回超过 7 天，并且目录中没有任何 Workspace、保留期或未撤回的 revision 还引用它。
回收记录、手工计划与执行，以及把某个 Launch 排除在回收之外，见 artifact 回收。
下一步：注册 Operator
Operator 在自己的工作机上用这把密钥建立 kibo 的连接配置，然后为每个 node 签发一把注册密钥。步骤见安装 Operator 并注册 node。
安装 node 用到的 node-enrollment.key 就来自那一步。