构建节点

1465 字约 5 分钟

构建节点 是云原生构建执行任务的机器：平台把构建任务分发到各节点，并以指定的 Docker 镜像作为构建环境。

使用场景：当需要为流水线指定 CPU 核数、选择特定架构（如 arm64/v8、GPU）节点时，按本篇查看可用节点并配置 runner.tags 与 runner.cpus。

配置方式

通过 pipeline.runner.tags 指定构建节点，pipeline.runner.cpus 配置 CPU 核数。

可用节点

Tags	架构	CPU 核数	GPU 显存	最大时间
`cnb:arch:amd64`	amd64	1 ~ 64	-	18 小时
`cnb:arch:arm64:v8`	arm64/v8	1 ~ 16	-	18 小时
`cnb:arch:amd64:gpu`	amd64	固定 16	48GB	18 小时
`cnb:arch:amd64:gpu:L40`	amd64	固定 16	48GB	18 小时

提示

CPU 核数：cnb:arch:amd64 和 cnb:arch:arm64:v8 的 CPU 核数默认为 8。

注意

为防止滥用，集群可能会对最大时长进行动态管控，以实际管控为准。

示例

构建流水线中选择节点：

.cnb.yml
main:
  push:
    - runner:
        tags: cnb:arch:amd64
        cpus: 8
      stages:
        - name: uname
          script: uname -a
    - runner:
        tags: cnb:arch:arm64:v8
        cpus: 8
      stages:
        - name: uname
          script: uname -a

云原生开发环境中选择节点：

.cnb.yml
$:
  vscode:
    - runner:
        tags: cnb:arch:amd64:gpu
      services:
        - vscode

根组织自定义 Runner

除了平台官方提供的构建节点外，根组织管理员还可以自助接入 Mac、 Windows、Linux 构建机，作为本组织专属的构建资源，满足特定构建需求（例如 iOS 构建、Windows 桌面应用打包、Linux ARM 服务端构建）。

接入构建节点

进入 根组织 / 组织设置 / 构建节点 页面，点击 + 新增 Runner，填写名称、标签等信息保存。
新创建的节点初始为「离线」状态，点击 Runner 行尾的 连接指引 按钮，弹窗会展示对应平台（Mac、Windows、Linux）的一键接入脚本，并自动注入该节点的唯一标识，无需手动替换。
在目标 Mac/Windows/Linux 构建机上执行对应平台的脚本，节点状态变为「在线」即接入成功。

在流水线中使用

接入并启用后，通过 runner.namespace + runner.tags 即可调度到该节点：

runner.namespace 设为 group，表示使用当前仓库所属根组织下的自托管构建节点。
runner.tags 必须是节点已声明标签的子集（"与"关系，列出的每个 tag 都需出现在节点标签上）。例如节点标签为 [mac, arm64, xcode15] 时，配置 tags: [mac, arm64] 即可命中。

Mac 节点示例

.cnb.yml
main:
  push:
    - runner:
        # 使用当前仓库所属根组织下的自托管构建节点
        namespace: group
        # 列出的每个 tag 都需出现在节点标签上（节点标签为超集）
        # 例如节点标签为 [mac, arm64, xcode15] 时，下面这组可命中
        tags:
          - mac
          - arm64
      stages:
        - name: build-on-mac
          script: |
            # 查看系统信息（验证确实跑在 mac 节点）
            sw_vers
            uname -m
            # 常见构建工具（已安装则展示版本，便于排查环境；未安装也不影响流水线）
            command -v xcodebuild >/dev/null && xcodebuild -version || echo "xcodebuild not installed"
            command -v brew >/dev/null && brew --version || echo "brew not installed"

Windows 节点示例

.cnb.yml
main:
  push:
    - runner:
        # 使用当前仓库所属根组织下的自托管构建节点
        namespace: group
        # 列出的每个 tag 都需出现在节点标签上（节点标签为超集）
        # 例如节点标签为 [windows, win11, msvc2022] 时，下面这组可命中
        tags:
          - windows
      stages:
        - name: build-on-windows
          script: |
            # 查看系统信息（验证确实跑在 windows 节点）
            # 注：self-hosted Windows runner 上 stage script 默认走 PowerShell，
            # ver 是 cmd 内置命令，需通过 `cmd /c` 调用
            cmd /c ver
            systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
            # git 是自托管 windows runner 的基本依赖，必装
            git -v

Linux 节点示例

.cnb.yml
main:
  push:
    - runner:
        # 使用当前仓库所属根组织下的自托管构建节点
        namespace: group
        # 列出的每个 tag 都需出现在节点标签上（节点标签为超集）
        # 例如节点标签为 [linux, arm64, ubuntu22.04] 时，下面这组可命中
        tags:
          - linux
          - arm64
      stages:
        - name: build-on-linux
          script: |
            # 查看系统信息（验证确实跑在 linux 节点）
            uname -a
            cat /etc/os-release
            # git 是自托管 linux runner 的基本依赖，必装
            git --version

节点调度

根组织自定义 Runner 命中同一组标签的已启用节点会全部参与轮转分配。

限制

支持 Mac、Windows、Linux 构建机；其中 Linux 构建机 仅支持 arm64/aarch64 架构，暂不支持 x86_64/amd64。
自定义构建机需要能够访问 CNB 站点（用于注册节点、上报心跳、拉取流水线任务及上传日志/制品）；若机器位于内网，请确保已开通对应出网策略。
自定义 Runner 默认不开启 Docker 能力，构建脚本直接运行在宿主机上，因此：
- runner.cpus 配置无效（资源限额由 Docker cgroups 实现，宿主机直跑时整机资源直接可用），不参与核时计费。
- 不能使用基于 Docker 镜像的构建环境（pipeline.docker.image 等不会生效）。
- OverlayFS 不可用，秒级克隆会自动降级为普通 git clone。
自定义 Runner 仅限云原生构建使用，不支持云原生开发（远程开发）任务。
流水线命中该 Runner 时，如节点暂时不可用（离线、被临时禁用，或资源使用达到管理员为该节点配置的上限，如 CPU/内存、同时运行流水线数等），系统会自动尝试重新分配到其他可用节点；若始终没有其他可用节点，流水线会失败。

提示

若 根组织 / 组织设置 中没有看到 构建节点 入口，说明平台尚未对当前组织开放该能力，请联系平台管理员。