GitHub Actions 的免费额度不够用？本文记录如何用一台 Orange Pi 5 Pro 搭建 GitHub Self-hosted Runner，把 go test、docker build、自动部署这些任务从 GitHub 云 Runner 迁移到自己的服务器上，并附上整个过程中踩过的坑。

需求背景

GitHub Actions 的免费额度用完，不想为此付费，于是想到：

利用自己的服务器（Orange Pi 5 Pro）运行 CI/CD，而不是使用 GitHub 提供的云 Runner。

最终选择的方案是 GitHub Self-hosted Runner——GitHub 的 Actions 任务不再跑在云端，而是下发到我们自己的机器上执行。

1
2
3
4
5
6
7
8
9
10
11
GitHub Repository
        |
        | Actions Job
        ↓
Orange Pi 5 Pro
        |
        ↓
GitHub Actions Runner
        |
        ↓
go test / docker build / deploy

一、安装 Runner

服务器信息：

1
2
3
4
Orange Pi 5 Pro
系统：Linux ARM64
用户：orangepi
目录：/opt/actions-runner

创建目录并进入：

1
2
mkdir -p /opt/actions-runner
cd /opt/actions-runner

接下来从 GitHub 官方 Releases 页面下载对应版本的 Runner 压缩包。注意 Orange Pi 是 ARM 架构，一定要选择 Linux ARM64 的包（actions-runner-linux-arm64-x.x.x.tar.gz），不要下成 x64。

下载后解压：

1
tar -xzf actions-runner-linux-arm64-*.tar.gz

二、踩坑一：权限错误

执行 ./config.sh 时报错：

1
2
3
touch: cannot touch '.env': Permission denied

Access to the path '/opt/actions-runner/_diag' is denied

原因

之前可能是用 root 用户下载/解压的 Runner，导致 /opt/actions-runner 目录的 owner 是 root：

1
2
3
/opt/actions-runner
        |
        owner=root

而现在用 orangepi 用户运行，自然没有写入权限。

解决

把目录所有权交给运行用户：

1
sudo chown -R orangepi:orangepi /opt/actions-runner

⚠️ 注意：配置和运行 Runner 时不要加 sudo。GitHub Runner 明确禁止以 root 运行，会直接报错：

1
Must not run with sudo

正确姿势是直接执行：

1
./config.sh

三、注册 Runner

执行配置命令（url 换成自己的仓库，token 在 GitHub 仓库的 Settings → Actions → Runners → New self-hosted runner 页面获取）：

1
2
3
./config.sh \
 --url https://github.com/binbatlab/DI-TING \
 --token xxxx

配置过程有几步交互式提问，很容易填错，逐个说明：

1. Runner Group：直接回车

1
Enter the name of the runner group

这里直接回车，使用默认的 Default 分组。

❌ 错误示范：输入了仓库名（比如 binbatlab），会报：

1
Could not find any self-hosted runner group named "binbatlab"

2. Runner Name：这里才填名字

1
Enter the name of runner

例如：

1
DI-TING

或者用机器名：

1
orangepi5pro

3. Labels：默认即可

默认标签是：

1
2
3
self-hosted
Linux
ARM64

因为 Orange Pi 是 ARM64 架构，这些标签后面写 workflow 时会用到，先保留默认即可。

配置成功会看到：

1
2
3
√ Runner successfully added

√ Settings Saved

四、启动测试

运行：

1
./run.sh

看到以下输出说明 Runner 已经在线：

1
2
3
4
5
√ Connected to GitHub

Current runner version: '2.336.0'

Listening for Jobs

Listening for Jobs 表示 Runner 已连上 GitHub，正在等待任务下发。

五、让 Runner 后台常驻：systemd

直接 ./run.sh 有两个问题：

  • SSH 断开后进程退出
  • 重启机器后 Runner 消失

所以要用 systemd 托管。GitHub 官方在解压目录里自带了脚本 svc.sh，推荐直接用：

1
2
3
4
cd /opt/actions-runner

sudo ./svc.sh install
sudo ./svc.sh start

查看状态：

1
sudo ./svc.sh status

这样以后 Orange Pi 一开机，systemd 就会自动拉起 Runner，完全不用管：

1
2
3
4
5
6
7
Orange Pi 开机
      |
      ↓
systemd
      |
      ↓
GitHub Runner 自动启动

六、踩坑二：多仓库问题

给另一个仓库配置时：

1
2
./config.sh \
 --url https://github.com/Bin-hy/documentsRag

报错：

1
Cannot configure the runner because it is already configured

原因

当前目录已经绑定到了 binbatlab/DI-TING。Runner 的配置保存在：

1
2
/opt/actions-runner/.runner
/opt/actions-runner/.credentials

一个 Repository Runner 不能直接改绑另一个仓库。

方案 A：Organization Runner（推荐长期使用）

注册时 url 填组织而不是具体仓库：

1
2
3
./config.sh \
 --url https://github.com/Bin-hy \
 --token xxxx

效果：组织下的所有仓库共享这一个 Runner：

1
2
3
4
5
6
7
8
9
10
11
12
Bin-hy Organization

├── DI-TING
├── documentsRag
├── BinCut
└── Vistack


          |
          ↓

     Orange Pi Runner

方案 B：多个 Runner

复制多个目录，每个 Runner 绑定一个仓库：

1
2
3
/opt/actions-runner-diting

/opt/actions-runner-rag

每个目录分别执行 config.sh 注册到各自的仓库。

七、修改工作流 YAML

以前用的是 GitHub 云 Runner：

1
2
3
jobs:
  build:
    runs-on: ubuntu-latest

改成使用自己的 Orange Pi：

1
2
3
jobs:
  build:
    runs-on: self-hosted

更精准一点，用标签组合限定架构：

1
2
3
4
5
6
jobs:
  build:
    runs-on:
      - self-hosted
      - Linux
      - ARM64

⚠️ 特别注意：runs-on 匹配的是 label（标签），不是 Runner 名字。所以像下面这样写是无效的：

1
2
3
4
jobs:
  build:
    runs-on:
      - DI-TING   # ❌ 这是 Runner 名字，不是 label

八、最终架构

整套流程的目标架构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
              GitHub

                 |
                 |
          Actions Workflow

                 |
                 ↓

       Orange Pi 5 Pro

       systemd
          |
          |
   GitHub Self-hosted Runner

          |
          |
   ------------------
   |                |
go test        docker build

          |
          ↓

     Docker Compose

          |
          ↓

       Dokploy/Caddy

到目前为止已经完成：

✅ Orange Pi 上安装 Runner
✅ Runner 注册成功
✅ Runner 可以监听 Job
✅ systemd 后台常驻运行
✅ 掌握 YAML 修改方式
✅ 理解 Repository Runner 与 Organization Runner 的区别

下一步计划

  1. CI 自动测试：
1
2
3
git push
 ↓
go test
  1. CD 自动部署：
1
2
3
4
5
git push
 ↓
docker build
 ↓
docker compose up -d
  1. 与 Dokploy 集成：
1
2
3
4
5
6
7
8
9
GitHub
 ↓
Actions Runner
 ↓
Docker Image
 ↓
Dokploy
 ↓
公网服务

到这一步，一套完整的个人 DevOps 平台基本就成型了。