安装 Exposure 网关

本页介绍如何安装 Exposure 网关，让 Workspace 里的 HTTP 服务可以通过公开 URL 访问。

Exposure 让接入方为 Workspace 内一个 HTTP 端口换来一条 https:// 地址。本页安装它需要的两个部署级组件：kibotos-gw，以及把公网流量送进来的 tunnel。没有这两样时 ctrl 不宣告 Exposure 能力，创建请求会被拒绝。

前提条件复制标题链接

• ctrl、node 与至少一个可用的 Template 已按安装概览的顺序就位。
• 一个专供此用的可注册域名。它不能与 ctrl 的 identity.host 或 node 的 data_plane.host_suffix 同源：Workspace 里跑的是接入方写的代码，它产出的页面是不可信内容，共用域名会把 cookie 作用域、同源假设与钓鱼面牵连到控制面。
• 该域名的 tunnel provider 账号。首版支持 cloudflared。
• 为网关准备一份专用的 Operator 身份：一把注册密钥，或一份按身份与注册注册好的身份目录。
• 网关与 ctrl、node 使用同一个发布包。

1. 在 ctrl 上声明 zone复制标题链接

在 /etc/kibotos/ctrl/config.toml 里填 [exposure] zone，重启 ctrl。留空表示这个部署不提供 Exposure。

[exposure]
zone = "preview.example.com"

ctrl 会拒绝与 identity.host 或 data_plane.host_suffix 同一可注册域名的 zone。

2. 安装包并填写配置复制标题链接

set -eu
sudo apt-get install ./kibotos-gw_1.2.3_amd64.deb
sudo test ! -e /etc/kibotos/gw/config.env
sudo install -o root -g root -m 0600 \
  /usr/share/doc/kibotos-gw/gw.example.env /etc/kibotos/gw/config.env
sudoedit /etc/kibotos/gw/config.env

安装包创建 kibotos-gw 账户和服务单元，不启动也不启用服务。网关的全部配置都写在这个环境文件里，完整示例见 gw.example.env。

3. 准备身份并启动复制标题链接

网关以一份专用的 Operator 身份调用 ctrl，每个运行中的实例需要自己的身份。本步骤对两种网关都适用，命令以 Exposure 网关为例；E2B 网关换成它那一列的名字：

用密钥注册复制标题链接

最简单的做法是让网关自己注册：Operator 用 kibo enrollment create --operator kibotos-gw-a --output kibotos-gw-a.key 签发一把密钥，经安全渠道交给网关宿主。把它放到服务账户能读的位置并写进配置，再启动：

set -eu
sudo install -o kibotos-gw -g kibotos-gw -m 0600 kibotos-gw-a.key /var/lib/kibotos/gw/enrollment.key
echo 'KIBOTOS_GW_ENROLLMENT_KEY_FILE=/var/lib/kibotos/gw/enrollment.key' | sudo tee -a /etc/kibotos/gw/config.env >/dev/null
sudo systemctl enable --now kibotos-gw.service
sudo journalctl -u kibotos-gw.service -n 50 --no-pager

• 身份目录为空时，网关先注册、发布身份，然后才开始服务，日志里有一行 enrolled Operator identity。之后不再读取这个文件，可以删掉它。
• 密钥默认 1 小时内有效，过期、已被使用或被撤销时网关启动失败，换一把新密钥即可。

复制已注册的身份目录复制标题链接

不用密钥时，也可以把一份已注册的网关专用 Operator 身份目录完整复制到配置指定的位置。把 gateway_identity_source 替换为实际路径，只在首次准备身份时执行：

set -eu
gateway_identity_source=/absolute/path/to/enrolled-gateway-context
sudo test ! -e /var/lib/kibotos/gw/identity
sudo cp -a "$gateway_identity_source" /var/lib/kibotos/gw/identity
sudo chown -R kibotos-gw:kibotos-gw /var/lib/kibotos/gw/identity
sudo chmod -R u=rwX,go= /var/lib/kibotos/gw/identity
sudo systemctl enable --now kibotos-gw.service
sudo systemctl status kibotos-gw.service

身份的使用规则复制标题链接

• 服务以自己的非 root 账户运行，只能写 /var/lib/kibotos/gw（E2B 网关是 /var/lib/kibotos/e2b）。身份目录必须可写，网关会在其中续期证书。
• 每个实例需要自己的身份。不要把同一份身份目录拷到多台实例上，也不要复制 kibo 正在使用的 context 目录：使用者各自续期，ctrl 只接受当前与上一张证书，使用者超过两个时总有一个被拒绝。
• 一种网关要运行多个实例时，每个实例用自己的密钥注册，例如 kibotos-gw-a 与 kibotos-gw-b。
• Exposure 网关不持有常驻数据面凭证：每个请求向 ctrl 解析一次 hostname，ctrl 同时为那个精确端口签发一张只服务这一个请求的凭证。

4. 配置 tunnel复制标题链接

tunnel 的配置是静态的：整条 zone 指向网关，一次配好，此后创建和撤销 Exposure 都不触碰它。以 cloudflared 为例，ingress 只有两条规则，DNS 只有一条 wildcard 记录指向这条 tunnel：

tunnel: kibotos-exposure
credentials-file: /etc/cloudflared/kibotos-exposure.json
ingress:
  - hostname: "*.preview.example.com"
    service: http://127.0.0.1:18097
  - service: http_status:404

注意：

• 通配符证书由 provider 提供，部署方不需要为逐条 hostname 申请证书。
• provider 账号与 tunnel 凭证只存在于运行 tunnel 的宿主上，不进入 node 的 Workspace 执行路径，也不进入 guest。
• tunnel 转发整条 zone 的流量，看得见全部 Workspace 的请求。它不是安全边界：hostname 解析、执行世代绑定与全部访问判定都在网关上完成。
• 需要冗余时为同一条 tunnel 起多个副本，由 provider 在多条连接间分发。

5. 确认复制标题链接

用 kibo 创建一条 Exposure 并打开返回的 url，用法见公开 URL。ctrl 没有配 zone 时，kibo exposure create 以 failed_precondition（CAPABILITY_UNAVAILABLE）失败。