--- url: /zh/paas/system-runner.md description: > 介绍系统管理员如何在 admin 管理平台添加 Linux/Mac/Windows 构建机作为云原生构建/云原生开发 Runner， 包含系统托管和自托管两种模式的配置说明。 --- ## 概述 系统管理员可在 `管理后台` 添加机器作为 `云原生构建`/`云原生开发` 的 Runner，供用户使用。 CNB 支持 Linux、Mac 和 Windows 构建机。 ### 两种托管模式 具体使用方式见[管理端配置](#添加-runner-到系统)和[Runner 配置](#配置过程)。 #### 系统托管（默认） 由 CNB 平台调度管理的机器，需与平台双向互通，通过 `ip:port` 方式添加。 #### 自托管 由用户自行管理的机器，仅需能访问 CNB 平台即可，通过唯一标识方式添加。 ### 接入主体 * **系统管理员**：在 `管理端 / 系统管理 / 云原生构建 / Runner 管理` 中接入，作为全平台共享的 Runner 资源。 * **根组织管理员**（可选）：当系统管理员开启「允许添加自定义 Runner」开关后， 根组织管理员可在 `组织设置 / 构建节点` 自助接入 Mac/Windows 构建机，仅供本组织使用。 详见下文 [根组织自定义 Runner](#根组织自定义-runner)。 ## 系统环境要求 ### Linux 构建机 * TencentOS 3.2 / TencentOS 3.1 / CentOS 8 及衍生版 * 内核版本推荐 5.4+ * Docker >= 26.1.5 * 8087、8088 端口未被占用，且允许本机监听 ### Mac 构建机 * Git >= 2.43.0 * 8087、8088 端口未被占用，且允许本机监听 由于 Mac 不支持 `OverlayFS`，秒级克隆会降级为普通克隆。 ### Windows 构建机 * 建议 Windows 10 及以上 * Git >= 2.43.0 * 8087、8088 端口未被占用，且允许本机监听 由于 Windows 不支持 `OverlayFS`，秒级克隆会降级为普通克隆。 ## 配置过程 ### ==1. 配置 Linux 构建机 （标准方案）== @[code-tree title="初始化 RUNNER 脚本" height="800px"](./system-runner) ### ==2. 配置自托管构建机=={.info} #### ==2.1=={.info} 管理后台创建自托管 RUNNER ::: note 配置的标签以 `cnb` 开头。 ::: ![创建自托管 RUNNER](/images/system-runner/create-system-runner.zh.png) ① 在管理后台下载证书。 ② 将证书压缩包上传到构建机配置目录，并解压。 * Linux: ==`/etc/orange-ci`== * Mac: ==`$HOME/orange-ci/etc/orange-ci`== * Windows: ==`C:/etc/orange-ci`== ③ 安装脚本会根据指定目录下是否有 `orange-ci.pem`、`orange-runner.crt`、`orange-runner.key`，来决定是否开启 TLS 校验。 #### ==2.2=={.info} 接入自托管 RUNNER {#self-hosted-runner-onboarding} ::: note ① 构建节点需能访问当前 CNB 站点域名。 ② 创建 Runner 后，点击行尾的「连接指引」；首次安装时在弹窗内点击「获取一次性安装码」。 ③ Windows 请注意脚本和配置文件编码，避免隐藏后缀或 BOM 头导致启动失败。 ::: ##### Linux 1. \==一键接入脚本== ```shell curl -fsSL https://docs.cnbprod.alpha.qq.com/system-runner/scripts/linux.sh \ | CONNECTOR_ENDPOINT=wss://connector.cnbprod.alpha.qq.com \ SELF_HOSTED_ID=xxxx-xxxx-xxxx ENROLLMENT_TOKEN=REPLACE_WITH_TOKEN_FROM_CONNECTION_GUIDE bash ``` 2. \==配置和存储目录== ```shell 默认目录和路径： ① 配置证书目录: `/etc/orange-ci` ② RUNNER 配置文件: `/etc/orange-ci/runner-config.json` ③ 数据存储目录: `/data/orange-ci` 如何修改: ① 修改配置目录: 配置环境变量 `ORANGE_RUNNER_CONFIG_DIR` ② 修改数据目录: 配置环境变量 `ORANGE_RUNNER_DATA_DIR`。 ``` 3. \==其他常用命令== ```shell # 安装服务 orange-runner install # 启动服务 orange-runner start # 停止服务 orange-runner stop # 卸载 service orange-runner uninstall # 删除全局命令 rm /usr/local/bin/orange-runner # 查询 service 运行状态 orange-runner status # 查看日志 tail -f /data/orange-runner/logs/app.log ``` ##### Mac 1. \==一键接入脚本== ```shell curl -fsSL https://docs.cnbprod.alpha.qq.com/system-runner/scripts/mac.sh \ | sudo env CONNECTOR_ENDPOINT=wss://connector.cnbprod.alpha.qq.com \ SELF_HOSTED_ID=xxxx-xxxx-xxxx bash ``` 2. \==配置和存储目录== ```shell 默认目录和路径： ① 配置目录: `$HOME/orange-ci/etc/orange-ci` ② RUNNER 配置文件: `$HOME/orange-ci/etc/orange-ci/runner-config.json` ③ 数据存储目录: `$HOME/orange-ci/data/orange-ci` 如何修改: ① 修改配置目录: 配置环境变量 `ORANGE_RUNNER_CONFIG_DIR` ② 修改数据目录: 配置环境变量 `ORANGE_RUNNER_DATA_DIR`。 ``` 2. \==其他常用命令== ```shell # 安装服务 orange-runner install # 启动服务 orange-runner start # 停止服务 orange-runner stop # 卸载 service orange-runner uninstall # 删除全局命令 rm /usr/local/bin/orange-runner # 查询 service 运行状态 orange-runner status # 查看日志 tail -f $HOME/orange-ci/data/orange-runner/logs/app.log ``` ##### Windows 1. \==一键接入脚本== ```shell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Confirm:$False -Force invoke-webrequest https://docs.cnbprod.alpha.qq.com/system-runner/scripts/windows.ps1 \ -outfile windows.ps1 $env:CONNECTOR_ENDPOINT='wss://connector.cnbprod.alpha.qq.com' $env:SELF_HOSTED_ID='xxxx-xxxx-xxxx' $env:ENROLLMENT_TOKEN='REPLACE_WITH_TOKEN_FROM_CONNECTION_GUIDE' ./windows.ps1 ``` 2. \==配置和存储目录== ```shell 默认目录和路径： ① 配置证书目录: `C:/etc/orange-ci` ② RUNNER 配置文件: `C:/etc/orange-ci/runner-config.json` ③ 数据存储目录: `C:/data/orange-ci` 如何修改: ① 修改配置目录: 配置环境变量 `ORANGE_RUNNER_CONFIG_DIR` ② 修改数据目录: 配置环境变量 `ORANGE_RUNNER_DATA_DIR`。 ``` 3. \==常用命令== ```shell # cd 到 orange-runner.exe 所在目录 cd $HOME\Downloads\orange-runner # 启动服务 .\orange-runner.exe start # 停止服务 .\orange-runner.exe stop # 卸载 service .\orange-runner.exe uninstall # 删除 exe 文件 Remove-Item -Path .\orange-runner.exe # 查询 service 运行状态 .\orange-runner.exe status # 查看日志 Get-Content 'C:\data\orange-runner\logs\app.log' -Wait -Tail 10 ``` ## 根组织自定义 Runner 除了由系统管理员统一接入构建节点，平台还允许根组织管理员自助接入 Mac/Windows 构建机，作为该组织专属的构建资源。 ### 1. 系统管理员开启开关 进入 `管理端 / 系统管理 / 云原生构建 / 自定义 Runner`，打开 `允许添加自定义 Runner` 开关。 开启后，所有根组织的「组织设置」中将显示 `构建节点` 入口，根组织管理员可自助新增 Runner。 ### 2. 根组织管理员接入构建机 1. 进入 `根组织 / 组织设置 / 构建节点`，点击 `+ 新增 Runner`，填写名称、标签等信息。 2. 创建后节点初始为「离线」状态，点击行尾的 `连接指引`；在弹窗中点击 「获取一次性安装码」，再复制生成的完整脚本。安装码 1 小时内有效，无需手动替换 `SELF_HOSTED_ID` 或拼接 token。 3. 在目标 Mac/Windows 构建机上执行对应平台的脚本，节点状态变为「在线」即接入成功。 如果连接指引提示 secret 已过期或本地 `state.json` 丢失，点击“重置 Runner 并获取安装码”， 然后使用新命令重新安装；不要复用旧命令或旧 token。 ::: tip 重置后的生效时间 服务端对 Runner 凭证有最多 5 分钟的鉴权缓存。重置、清空机器指纹等操作在缓存过期后完全生效， 原机器在此期间可能仍能连接，新机器也可能短暂被拒。属正常现象，等待后重试即可，无需重复操作。 ::: 脚本内容、配置目录与常用命令与上文 [接入自托管 RUNNER](#self-hosted-runner-onboarding) 一致。 ### 3. 在 `.cnb.yml` 中调度 参见用户文档 [构建节点 - 根组织自定义 Runner](../build/build-node.md#根组织自定义-runner)。 ### 限制 * 仅支持 **Mac** 与 **Windows** 构建机，Linux 自托管节点仍由系统管理员统一接入。 * 自定义构建机需要能够**访问 CNB 站点** （用于注册节点、上报心跳、拉取流水线任务及上传日志/制品）； 若机器位于内网，请确保已开通对应出网策略。 * 自定义 Runner 默认**不开启 Docker**：`runner.cpus` 配置无效，且无法使用基于镜像的构建环境。 * **仅限云原生构建**使用，不能用于云原生开发（远程开发）任务。 * 在使用范围限制、证书放置等高级能力方面，与系统级自托管 Runner 保持一致。 ## 常见问题 ### Linux 构建机 1. docker buildx 多平台构建 arm 镜像时，出现报错： `Error while loading /usr/sbin/dpkg-split: No such file or directory` 解决办法： ```bash docker run --rm --privileged multiarch/qemu-user-static --reset -p yes --credential yes ``` 2. 宿主机 git clone 正常，但流水线容器内 clone 代码时端口超时。 原因：需开启 IPv4 转发，`cat /proc/sys/net/ipv4/ip_forward` 应为 `1`。如未开启，执行以下命令编辑： ### 自托管构建机 1. 什么情况下适合使用自托管 Runner？ * 需要 Windows 或 Mac 构建环境 * CNB 提供的构建机无法访问目标网络，而自托管机器可以 2. 自托管 Runner 能做什么？不能做什么？ * 只能在裸机上执行命令 * 只能运行 CI 任务 * 不能运行远程开发任务 3. 能否限制自托管 Runner 被哪些仓库和组织使用，防止机器被滥用？ ```json { "allowUseThisRunner": { "groups": [], "projects": [] } } ``` 在 `runner-config.json` 中添加以下配置，使用全等匹配，不符合预期时可查看 Runner 日志。