CI/CD / 系统课时

在 Linux 注册自托管 Runner

在 Linux 注册自托管 Runner

自托管 Runner 让 GitHub Actions 的任务进入你控制的 Linux 主机执行。本节完成从下载 Runner、注册仓库到安装系统服务的完整链路,并验证机器能够持续在线接收工作流任务。

学习目标

  • 完成 Linux Runner 的下载、配置与仓库注册
  • 理解注册令牌、Runner 身份与工作目录的作用
  • 将 Runner 安装为系统服务并验证任务能够执行

注册前准备

Runner 所在主机需要能够访问 GitHub,并准备一个专用目录。生产环境建议使用权限受限的独立系统用户运行 Runner,而不是长期以 root 身份执行工作流。

在 GitHub 仓库中进入 Settings → Actions → Runners → New self-hosted runner,选择 Linux 和对应 CPU 架构。页面会给出当前 Runner 版本对应的下载地址以及临时注册令牌。注册令牌具有时效性,不应写入脚本、仓库或日志。

下载并注册 Runner

下面以 GitHub 注册页面给出的版本号、下载地址和令牌为准。不要照抄已经过期的版本或令牌;<PATH>、<URL>、<TOKEN> 和 <RUNNER_NAME> 都需要替换成当前环境的实际值。

bash
mkdir -p <PATH>/actions-runner
cd <PATH>/actions-runner
curl -L -o actions-runner.tar.gz <URL>
tar xzf actions-runner.tar.gz
./config.sh --url https://github.com/<OWNER>/<REPO> --token <TOKEN> --name <RUNNER_NAME> --work _work

预期输出

text
√ Connected to GitHub
√ Runner successfully added
√ Settings Saved.

不同 Runner 版本的提示文本可能略有差异;关键验证点是成功连接 GitHub、Runner 被添加并保存配置。注册完成后,仓库的 Runners 页面应出现该 Runner。

Linux 自托管 Runner 注册与执行链路

安装为系统服务

直接执行 ./run.sh 时,终端退出后 Runner 也会停止。需要长期接收任务的主机应使用 Runner 自带的服务管理脚本安装并启动服务。以下命令需要具有相应系统权限的账户执行。

bash
cd <PATH>/actions-runner
sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

预期输出

text
Active: active (running)

svc.sh status 的完整输出会因 Linux 发行版、systemd 和 Runner 版本不同而变化,因此重点检查服务是否处于运行状态。此时 GitHub 仓库的 Runners 页面应将节点显示为在线且空闲,等待匹配的 Job。

用工作流验证执行

创建一个最小工作流,让任务明确进入自托管 Runner。self-hosted 是自托管节点自动拥有的默认标签之一,后续还可以组合操作系统、架构或自定义标签进一步限制路由。

yaml
name: verify-self-hosted

on:
  workflow_dispatch:

jobs:
  verify:
    runs-on: self-hosted
    steps:
      - name: Show runner host
        run: |
          hostname
          uname -s

预期输出

text
<RUNNER_HOST>
Linux

<RUNNER_HOST> 会随实际主机名变化。手动触发工作流后,只要 Job 被该节点领取并成功输出 Linux 主机信息,就说明 GitHub 到 Runner 的任务分发和 Runner 本地执行链路均已打通。

注册失败时怎么查

如果 config.sh 无法连接,先检查主机到 GitHub 的网络、DNS、代理和 TLS,再确认仓库地址是否正确。若提示令牌无效或过期,应回到 Runners 页面重新生成注册命令,而不是反复使用旧令牌。

如果注册成功但 Job 一直排队,则检查 Runner 是否在线、服务是否仍在运行,以及工作流的 runs-on 是否能匹配该节点。服务正常、标签匹配且节点空闲时,Runner 才能领取对应任务。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

在 Linux 注册自托管 Runner

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通