---
url: /zh/build/build-node.md
description: >
  介绍 PAAS 版云原生构建的构建节点配置方式，包括通过 runner.tags 选择节点、 runner.cpus 配置 CPU 核数，以及管理员通过系统
  Runner 添加自定义构建节点的方法。
---
云原生构建基于 Docker 生态，将构建任务分发到各构建节点执行，并使用指定的 Docker 镜像作为构建环境。

## 配置方式

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

管理员可参考 [系统 Runner 配置](../../paas/system-runner.md) 添加构建节点并配置默认标签。

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

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

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: uname
          script: uname -a
```

**使用 `arm64/v8` 架构节点**：

```yaml title=".cnb.yml"
main:
  push:
    - runner:
        tags: cnb:arch:arm64:v8
      stages:
        - name: uname
          script: uname -a
```

## 使用组织自托管构建节点

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

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

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

```yaml title=".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 服务端构建）。

### 前置条件

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

### 添加并接入构建节点

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

具体的脚本与目录约定，可参考 [系统级 Runner 接入](../../paas/system-runner.md#self-hosted-runner-onboarding) 文档；
连接指引弹窗中已根据当前节点信息生成可直接复制运行的脚本，无需手动替换 `SELF_HOSTED_ID`。

### 在流水线中使用

接入并启用后，在 `.cnb.yml` 中通过 `runner.namespace: group` + `runner.tags` 即可调度到该节点。
`tags` 必须是节点已声明标签的子集（「与」关系，列出的每个 tag 都需出现在节点标签上）。
例如节点标签为 `[mac, arm64, xcode15]` 时，配置 `tags: [mac, arm64]` 即可命中。

#### Mac 节点示例

```yaml title=".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 节点示例

```yaml title=".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 节点示例

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