---
url: /zh/paas/system-runner.md
---
## 概述

系统管理员可以在 `admin 管理平台` 添加机器，作为 `云原生构建`/`云原生开发` 功能的 Runner，供用户使用。

CNB 支持 Linux、Mac 和 Windows 构建机。

### 两种托管模式

具体使用方式见[管理端配置](#添加-runner-到系统)和[Runner配置](#配置过程)

#### 系统托管（默认）

由 CNB 平台调度管理的机器，需要机器和平台可以互相访问，通过 ip:port 的方式添加。

#### 自托管

由用户自行管理的机器，仅要求机器能直接访问CNB平台即可，通过唯一标识的方式添加。

## 系统环境要求

### 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-runer.crt` `orange-runner.key`，来决定是否开启 TLS 校验。

#### ==2.2=={.info} 接入自托管 RUNNER

::: note
① `CONNECTOR_ENDPOINT`: 请务必确认当前环境是否开启了 HTTPS 和当前环境域名，wss://connector.yourdomain，并替换接入脚本的该变量。

② `SELF_HOSTED_ID`: 管理后台配置完成步骤 2 后，可以获得该 RUNNER 的唯一标识。

③ 在 `.\orange-runner.exe start` 或 `orange-runner start` 前，可以使用 `.\orange-runner.exe` 或  `./orange-runner` 启动服务可以直观的看到报错日志。

④ Windows 下文件找不到，关闭隐藏文件的后缀，确认是否符合预期。

⑤ Windows 创建文件可能有 Bom 头的问题，请注意检查。
:::

::: tabs
@tab Linux

1. \==一键接入脚本==

```shell
curl -fsSL https://docs.cnb.share.ralphlauren.cn/system-runner/scripts/linux.sh | CONNECTOR_ENDPOINT=wss://connector.cnb.share.ralphlauren.cn  SELF_HOSTED_ID=xxxx-xxxx-xxxx bash
```

2. \==配置和存储目录==

```shell
① 配置证书目录: `/etc/orange-ci`
② RUNNER 配置文件: `/etc/orange-ci/runner-config.json`
③ 数据存储目录: `/data/orange-ci`
```

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
```

@tab Mac

1. \==一键接入脚本==

```shell
curl -fsSL https://docs.cnb.share.ralphlauren.cn/system-runner/scripts/mac.sh | CONNECTOR_ENDPOINT=wss://connector.cnb.share.ralphlauren.cn  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`
```

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 /data/orange-runner/logs/app.log
```

@tab Windows

1. \==一键接入脚本==

```shell
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Confirm:$False -Force ; invoke-webrequest https://docs.cnb.share.ralphlauren.cn/system-runner/scripts/windows.ps1 -outfile windows.ps1; $env:CONNECTOR_ENDPOINT='wss://connector.cnb.share.ralphlauren.cn'; $env:SELF_HOSTED_ID='xxxx-xxxx-xxxx'; ./windows.ps1
```

2. \==配置和存储目录==

```shell
① 配置证书目录: `C:/etc/orange-ci`
② RUNNER 配置文件: `C:/etc/orange-ci/runner-config.json`
③ 数据存储目录: `C:/data/orange-ci`
```

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
```

:::

## 常见问题

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
```

1. 宿主机 git clone 正常。流水线容器内 clone 代码，访问端口超时

原因：需要开启 ipv4 转发，`cat /proc/sys/net/ipv4/ip_forward` 需要是 1 。如果没有开启，执行下面命令编辑：