构建节点

1578 字约 5 分钟

云原生构建基于 Docker 生态，将构建任务分发到各构建节点执行，并使用指定的 Docker 镜像作为构建环境。

配置方式

通过 pipeline.runner.tags 选择构建节点，通过 pipeline.runner.cpus 配置所需的最大 CPU 核数。

管理员可参考系统 Runner 配置添加构建节点并配置默认标签。

用户可不配置 tags，使用默认标签下的构建节点。如需 arm64/v8 等特定架构，可由管理员添加对应架构的构建节点并配置标签。

使用默认节点（不配置 tags）：

.cnb.yml
main:
  push:
    - stages:
        - name: uname
          script: uname -a

使用 arm64/v8 架构节点：

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

使用组织自托管构建节点

通过 pipeline.runner.namespace 可指定使用组织下的自托管构建节点。

将 namespace 设为 group 可使用当前仓库所属根组织下的自托管构建节点，不设置时使用平台默认调度。

使用 group 时必须同时配置 runner.tags，用于匹配组织内的自托管构建节点。

.cnb.yml
main:
  push:
    - runner:
        namespace: group
        tags: my-runner
      stages:
        - name: build
          script: echo "running on self-hosted runner"

根组织自定义 Runner

除了系统管理员统一接入构建节点外，平台还支持「根组织管理员」自助接入 Mac、Windows、Linux 构建机，以满足组织内的特定构建需求（例如 iOS 构建、Windows 桌面应用打包、Linux ARM 服务端构建）。

前置条件

系统管理员已在 管理端 / 系统管理 / 云原生构建 / 自定义 Runner 中开启「允许添加自定义 Runner」。
根组织管理员已在 根组织 / 组织设置 / 构建节点 页面新增 Runner，并完成接入（节点状态显示为「在线」）。

添加并接入构建节点

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

具体的脚本与目录约定，可参考系统级 Runner 接入文档；连接指引弹窗中已根据当前节点信息生成可直接复制运行的脚本，无需手动替换 SELF_HOSTED_ID。

在流水线中使用

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