在 VPS 上运行一个自托管的 GitHub Actions Runner

GitHub 托管的 runner 是个不错的默认。在一次构建想要它们没有的东西的那一刻，你就不再需要它们了——你的私有软件包仓库、一个你厌倦了每次运行都重装的特定工具链版本、你自己网络上的一个数据库，或只是对机器多一点掌控。那时，一台 VPS 上的自托管 runner 就值它的钱了。

本指南把一个 runner 正经跑起来：装好、注册、在 systemd 下活着，以及——人们弄错的部分——安全。我们从最后这个开始，因为它是咬人的那部分。

那一条安全规则

一个 GitHub Actions 工作流跑任意代码——工作流文件里的一切，以及那代码拉进来的一切。在你自己的仓库上那是你的代码，没问题。在一个公开仓库上，一个陌生人的 pull request 能在你的 runner 上跑他们的代码。那不是 bug；是 CI 就这么运作的。GitHub 自己的文档直白地说：别把自托管 runner 用在公开仓库上。

所以规则很简单、也不可商量：自托管 runner 是给私有仓库的。 如果你的仓库是公开的，用 GitHub 托管的 runner、往前走。下面的一切都假设一个私有仓库。

runner 需要机器提供什么

它取决于构建，你该按你的来配置、而不是照抄页面上的一个数字：

• 一个典型的编译加测试任务 —— 2 核加 4-8 GB 就很舒服。Small（$8，4 vCPU / 4 GB）或 Medium（$12，6 vCPU / 6 GB）覆盖大多数这类。
• 更重的构建 —— 大的原生编译、大的 Docker 镜像构建、吃内存的测试套件——想要更多余量。看一次真实运行（构建时开 htop）、按你实际看到的配置，而不是靠希望。

磁盘也要紧：构建缓存、Docker 层和克隆的仓库会累加。盯着它、及时清理。

1. 准备机器

给 runner 创建一个非 root 用户——反正 GitHub 的安装器拒绝以 root 跑，你也想要这样：

sudo adduser --disabled-password --gecos "" runner
sudo usermod -aG sudo runner   # 只在你的构建真的需要 sudo 时

装上你构建需要的一切——一个语言工具链、Docker、构建工具。比如，如果你的任务构建容器：

sudo apt update && sudo apt install -y docker.io
sudo usermod -aG docker runner

2. 下载并注册 runner

在 GitHub 上你的仓库（或组织）里，去 Settings → Actions → Runners → New self-hosted runner。GitHub 给你确切的下载命令和一个注册令牌（它是短期的——现拿现用）。以 runner 用户身份：

sudo -iu runner
mkdir actions-runner && cd actions-runner
# 用 GitHub 为你的 OS/arch 显示的确切 URL：
curl -o actions-runner-linux-x64.tar.gz -L "URL_FROM_GITHUB"
tar xzf actions-runner-linux-x64.tar.gz
./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN

config.sh 问一个 runner 名字、标签和一个工作文件夹——起步用默认值就行。标签是你的工作流瞄准这个 runner 的方式（runs-on: self-hosted）。

3. 作为 systemd 服务来跑

runner 自带一个帮你安装 systemd 服务的辅助脚本——用它，好让 runner 熬过重启、失败时重启。仍然在 runner 用户的安装里，但服务命令需要 root：

sudo ./svc.sh install runner
sudo ./svc.sh start
sudo ./svc.sh status

那把 actions.runner.* 注册成一个以 runner 用户运行、开机启动的 systemd unit。日志进 journald：

sudo journalctl -u 'actions.runner.*' -f

回到 GitHub 的 Runners 页，你的 runner 现在显示 Idle——绿点。把一个工作流指向它：

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - run: make test

推送，任务就在你的机器上跑。

4. 保持干净

一个自托管 runner 在任务之间复用它的文件系统——那是速度收益（热缓存），也是那把走火的枪（残留状态）。两个习惯让它健康：

• 定期清理。 尤其是 Docker——docker system prune 放上 cron，否则磁盘会被死层悄悄填满。
• 别在机器上存机密。 用 GitHub Actions secrets、按每次运行注入，而不是躺在 runner 家目录里的文件。如果 runner 被攻陷，磁盘上的任何东西都随它一起走。

如果你需要每个任务一个真正干净的环境，就把每个任务放进一个容器步骤里跑——runner 留着，任务的烂摊子不留。

什么时候该自托管，诚实地

当你需要把自己的工具链烤进去、访问私有网络资源、或对机器有掌控时自托管。当一个干净、一次性的环境和他们的分钟数适合你时，留在 GitHub 托管的 runner 上——那确实更简单，而简单值点东西。而且永远、在公开仓库上，别自托管。那一条不是偏好。

如果你需要的是一个私有仓库 runner：挑一个套餐——轻构建用 Small（$8）、变重时用 Medium（$12）——用 USDC 或 USDT 付款（无需 KYC、不用文件），你大约 60 秒就有 root。然后照着这一页往下做，几分钟后你就有一个在领任务的 runner 了。

查看套餐并订购 VPS →