Skip to content
Subaya

自托管运行器

自托管运行器是一个小型代理 subaya-runner，它在你掌控的机器上而不是在 Subaya 云中运行 Subaya 构建。当工具链已安装在该机器上（例如已授权的 Quartus 安装），或构建必须在你自己的 硬件上进行时，请使用它。

运行器通过安全的 WebSocket 向外连接到 Subaya。它不需要入站端口、VPN 或公网 IP。 Subaya 通过该连接向它推送构建。

运行器为其所属组织执行构建，所用命令由平台从该组织的项目中派生。构建以运行器的权限在你拥有的机器上运行 — 与 GitHub 自托管运行器相同的信任模型。它不是沙箱。

要求

Section titled “要求”
  • x86_64 上的 Linux。其他平台稍后支持。
  • 到 subaya-dev.com 的出站 HTTPS（端口 443）。
  • 构建所需的工具已安装，并位于运行运行器的用户的 PATH 中。运行器只报告它找到的内容， 不会安装任何东西。
  • 可选：Docker 或 Podman，用于配方指定了容器镜像的构建。

安装

Section titled “安装”

在控制台中打开 Settings → Runners 并选择 Add runner。为运行器命名后，Subaya 会 显示三条已填入一次性注册令牌的命令。该令牌只能使用一次，并在 1 小时后过期。

下载并解压运行器：

Terminal window
curl -fsSL -o subaya-runner.tar.gz https://subaya-dev.com/cli/runner/latest/subaya-runner_linux_amd64.tar.gz && tar xzf subaya-runner.tar.gz

进行配置。这一步会用注册令牌换取运行器自己的凭据，并生成一个永不离开本机的密钥对：

Terminal window
./subaya-runner configure --url https://subaya-dev.com --token srt_... --name 'lab-quartus-01'

在前台运行：

Terminal window
./subaya-runner run

若要在重启后继续运行，请改为将其安装为 systemd 服务：

Terminal window
./subaya-runner install-service

以你自己的用户运行时，会安装为 systemd 用户服务；以 root 运行时，会安装为系统级服务。除非为你的账户启用 lingering，否则用户服务会在你注销时停止：

Terminal window
sudo loginctl enable-linger "$USER"

几秒钟内，运行器会在 Settings → Runners 中显示为 online，并列出它检测到的工具和版本。

向运行器发送构建

Section titled “向运行器发送构建”

使用 --runner 按名称指定运行器：

Terminal window
suya build <app> --source . --runner lab-quartus-01 --wait

在接受构建之前，Subaya 会检查运行器是否已报告构建所需的每个工具。如果运行器离线，构建会 在队列中等待，并在运行器重新连接后开始。

记录的内容

Section titled “记录的内容”

构建开始时，运行器会报告它实际测得的工具链：每个工具的版本字符串、路径及其二进制文件的 SHA-256。运行记录的是这个测得的工具链，而不是项目所要求的。

如果项目显式固定了工具版本（例如使用 suya tools set quartus-pro 26.1.1），而运行器上 安装的版本与之不符，构建将被拒绝并以 toolchain_pin_mismatch 失败，不会执行任何内容。 如果没有显式固定，则使用运行器上安装的版本。

吊销运行器

Section titled “吊销运行器”

在 Settings → Runners 中，对该运行器选择 Revoke。吊销立即生效：运行器的凭据失效， 其连接被关闭，不再向它发送任何构建，正在运行的构建会失败。吊销无法撤销 — 若要再次使用 该机器，请将其添加为新的运行器，并使用新令牌运行 ./subaya-runner configure --replace。

若还要从机器上移除该服务：

Terminal window
./subaya-runner uninstall-service

故障排查

Section titled “故障排查”

运行器显示为离线。 检查进程或服务是否在运行，以及机器能否通过端口 443 访问 subaya-dev.com：

Terminal window
./subaya-runner status

网络中断后，运行器会自动重新连接。连接断开时正在运行的构建会以 runner_disconnected 失败；请重新运行。

运行器以“upgrade required”退出。 运行器版本低于 Subaya 接受的最低版本。使用上面的 下载命令获取最新版本，替换二进制文件后重新启动。其配置会被保留。

构建被 422 runner_missing_tool 拒绝。 运行器没有报告构建所需的某个工具。请安装该 工具，确认它位于运行器的 PATH 中，然后重启运行器，使其重新报告工具链。错误信息会指明 缺少的工具。

注册令牌被拒绝。 令牌只能使用一次，并在一小时后过期。请通过 Add runner 创建新令牌。

后续步骤

Section titled “后续步骤”