GitHub Actions 自托管 Runner

FreeGuideOnline 最新 2026-07-11

bash

创建目录并下载

mkdir actions-runner && cd actions-runner curl -o actions-runner-linux-x64-2.319.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.319.0/actions-runner-linux-x64-2.319.0.tar.gz

验证哈希 (可选但推荐)

echo "abcdef... actions-runner-linux-x64-2.319.0.tar.gz" | shasum -a 256 -c tar xzf ./actions-runner-linux-x64-2.319.0.tar.gz


4. 配置 Runner：

```bash
./config.sh --url https://github.com/你的用户名/你的仓库 --token AUTH_TOKEN

注意：Token 有效期只有 1 小时，务必在有效期内完成配置。你也可以使用 GitHub App 或更高级的注册方式获得长期有效的注册令牌。

  1. 按照交互提示完成配置：

    • 填写 Runner 名称（默认是主机名）
    • 可选地添加标签（如 gpu,linux,production）
    • 选择工作目录（默认 _work）

  2. 运行 Runner：

./run.sh

此时，在仓库的 Runners 页面中，你会看到 Runner 状态变为 Idle，表明它正在等待作业。

组织级 Runner

将 Runner 注册到组织，可供多个仓库共享。

  1. 进入组织 Settings → Actions → Runners，点击 New runner。
  2. 跟随与仓库级类似的步骤，但 --url 改为 https://github.com/你的组织。
  3. 配置完成后，在任何仓库的工作流中使用时，需通过标签筛选，例如：
runs-on: [self-hosted, linux, org-runner]

企业级 Runner

用于 GitHub Enterprise Server 或 GitHub Enterprise Cloud 的企业账户。创建方式类似，但 --url 指向企业 URL。企业 Runner 可以被企业中所有组织使用。

配置 Runner 为服务

为了让 Runner 在后台运行并开机自启，推荐将其安装为系统服务。

# 先停止当前正在运行的 Runner（Ctrl+C）
sudo ./svc.sh install          # 安装服务
sudo ./svc.sh start            # 启动服务
sudo ./svc.sh status           # 查看状态

服务默认以 root 运行（Linux/macOS），可通过环境变量或修改服务文件调整用户。

在工作流中使用

在 .github/workflows/ 下的 YAML 文件中，将 runs-on 设置为 self-hosted 及你设定的标签：

name: 自托管 Runner 示例
on: push

jobs:
  build:
    runs-on: [self-hosted, linux, x64]
    steps:
      - uses: actions/checkout@v4
      - run: echo "跑在自己的机器上！"

标签的作用

  • self-hosted 是必需的标签，表明不使用 GitHub 托管 Runner。
  • 自定义标签用于精确匹配某一组 Runner，支持多标签 AND 逻辑。

如果你只有一个通用 Runner，可以只写 runs-on: self-hosted，但不建议在生产环境这样做。

安全实践

自托管 Runner 一旦被恶意利用，可能危及你的基础设施。务必遵循以下准则：

  • 绝不用于公共仓库的 PR：在仓库 Settings → Actions → General → Fork pull request workflows 中选择“Require approval”，或将工作流触发条件限制在非 fork 事件。
  • 使用临时 Runner：为每个构建使用全新的虚拟机或容器，构建后销毁，避免状态污染和凭证泄漏。
  • 最小权限：Runner 运行的服务器应仅授予必要权限，避免使用 root，推荐通过非特权用户运行。
  • 网络安全：将 Runner 置于防火墙后，仅允许出站连接 GitHub 服务；如需访问内部服务，严格控制网络策略。
  • 密钥管理：Runner 会自动注入仓库和组织 secrets，确保服务器本身不被未授权访问。

高级特性

使用容器运行 Runner

你可以将 Runner 打包在 Docker 容器中，实现快速扩缩和环境一致性。

官方基础镜像：myoung34/github-runner (社区维护的常用镜像)

docker run -d --restart unless-stopped --name runner \
  -e RUNNER_NAME=my-runner \
  -e RUNNER_TOKEN=你的token \
  -e RUNNER_REPOSITORY_URL=https://github.com/你的用户名/你的仓库 \
  myoung34/github-runner:latest

对于生产环境，建议使用 Kubernetes 运行 Runner，利用 actions-runner-controller 项目（ARC）实现自动扩缩容。

自动扩缩（Actions Runner Controller）

通过 ARC，根据作业队列动态创建和销毁 Pod，仅在实际需要时消耗资源。

关键步骤：

  1. 在 Kubernetes 集群中安装 ARC Controller（通过 Helm）。
  2. 创建 RunnerDeployment 自定义资源。
  3. 定义“组织 Runner”或“仓库 Runner”，设置标签和资源限制。
  4. Controller 会为每个作业请求启动一个新 Pod，执行完毕后自动删除。

持久化缓存

自托管 Runner 的工作目录默认不会被清理，但这反而有利于缓存。你可以利用 actions/cache 并配置自己的缓存存储（如 S3、MinIO），或者简单地将缓存目录挂载到主机持久化卷。

- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

因为文件系统不变，缓存命中率极高，大幅提速。

监控与维护

查看日志

Runner 自身的日志文件位于 _diag/ 目录下，包括 Runner_ 日志和 Worker_ 日志，可用于排查断连或作业失败问题。

升级 Runner

Runner 每隔一段时间会发布新版本。当有新版本时，GitHub 会强制旧版本不能接收作业。升级方法：

# 进入 Runner 目录
sudo ./svc.sh stop
# 下载新版并解压覆盖（无需重新配置）
curl -o actions-runner-linux-x64-<版本>.tar.gz -L <下载链接>
tar xzf ./actions-runner-linux-x64-<版本>.tar.gz
sudo ./svc.sh start

移除 Runner

cd actions-runner
./config.sh remove --token <REMOVE_TOKEN>