Ubuntu 22.04 安装 GitHub Actions Runner 指南

目标：在 Ubuntu 22.04 上通过「官方 tar.gz 在线下载」与「国内加速镜像（离线/内网）」两种方式安装 GitHub Actions 自托管 Runner 2.338.0，并完成注册、systemd 服务托管与连通性验证。所有命令与回显已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
系统架构：x86_64
逻辑核数：6
包管理器：apt（apt-get）
Runner 版本：2.338.0（当前最新稳定版，官方 GitHub 发布）
官方下载地址：https://github.com/actions/runner/releases/download/v2.338.0/actions-runner-linux-x64-2.338.0.tar.gz
安装目录：/opt/data/github-actions/actions-runner
数据目录：/opt/data/github-actions
服务管理：systemd 单元 actions.runner.{owner}-{repo}.{runner-name}.service
Runner 运行用户：root（需设置 RUNNER_ALLOW_RUNASROOT=1 环境变量）
仓库示例：https://github.com/quzuo-ops/demo-app

二、前置条件

拥有 root 权限（runner 默认以 root 账号长期运行，需显式允许）
服务器可访问外网（下载 runner 安装包并与 GitHub API 通信）
已安装基础工具：curl、wget、tar、git、gpg、ca-certificates
已规划安装目录（建议放在独立数据盘，如 /opt/data/github-actions/actions-runner）

apt-get update
apt-get install -y curl wget tar git gpg ca-certificates
mkdir -p /opt/data/github-actions

💡 说明：curl/wget 用于下载安装包，tar 用于解压，git 供 checkout 动作与更新使用，gpg/ca-certificates 用于校验与证书信任。

三、版本选型说明

Runner 官方只发布预编译二进制 tar.gz（GitHub Releases），不提供 apt 软件源，因此「在线源」指 GitHub 官方发布页直连，「离线」指先把 tar.gz 下载/拷贝到目标机器后安装。

来源	版本	特点
GitHub 官方 Releases（在线直连）	2.338.0	官方唯一权威来源，国内网络可能直连失败，需重试或换镜像；本文方案 A
GitHub 官方 releases（国内加速镜像，在线）	2.338.0	走 `ghfast.top` 等加速节点，下载稳定，适合国内服务器；本文方案 B
离线 tar.gz（内网/断网部署）	2.338.0	在能联网的机器下载好 tar.gz 后拷贝到目标机，流程同方案 B

💡 说明：版本号以官方 releases/latest 为准，可通过 curl -s https://api.github.com/repos/actions/runner/releases/latest | grep tag_name 实时查询，不建议硬编码未来版本。

四、方案 A：官方 GitHub Releases 在线下载安装（推荐）

4.1 下载安装包

cd /tmp
curl -fsSL -o actions-runner-linux-x64-2.338.0.tar.gz \
  https://github.com/actions/runner/releases/download/v2.338.0/actions-runner-linux-x64-2.338.0.tar.gz
ls -lh actions-runner-linux-x64-2.338.0.tar.gz

执行结果：

-rw-r--r-- 1 root root 218M Oct  9 12:20 actions-runner-linux-x64-2.338.0.tar.gz

⚠️ 注意：直连 GitHub 在部分网络环境下可能报 curl: (56) OpenSSL SSL_read: Connection reset by peer（传输中断）。此时改用方案 B 的国内加速镜像，或加 --retry 5 --retry-delay 3 重试。

4.2 校验 SHA256 摘要

sha256sum actions-runner-linux-x64-2.338.0.tar.gz

执行结果：

af4b794c1bc41d73d40535e3fe092a39f9679cd8d965954c2aca25a05ca41d32  actions-runner-linux-x64-2.338.0.tar.gz

⚠️ 说明：应将本机计算出的值与该版本在 GitHub 官方发布页（Release 说明中的 sha256 表）标注的值比对一致后再解压，防止包损坏或被篡改。

4.3 解压到安装目录

mkdir -p /opt/data/github-actions/actions-runner
cd /opt/data/github-actions/actions-runner
tar xzf /tmp/actions-runner-linux-x64-2.338.0.tar.gz

解压后的顶层文件：

bin
config.sh
env.sh
externals
run-helper.cmd.template
run-helper.sh.template
run.sh
safe_sleep.sh

4.4 验证安装（版本 / 提交号）

./bin/Runner.Listener --version

执行结果：

2.338.0

RUNNER_ALLOW_RUNASROOT=1 ./config.sh --version
RUNNER_ALLOW_RUNASROOT=1 ./config.sh --commit

执行结果：

2.338.0
197ca027b90de199464dee3bb9ff198a1db60967

💡 说明：Runner.Listener 是真正的 Run 监听进程；config.sh 为注册配置脚本。以 root 运行时脚本默认拒绝，必须加环境变量 RUNNER_ALLOW_RUNASROOT=1（详见"四、4.5"）。

4.5 以 root 运行需允许的环境变量说明

config.sh 头部会校验运行用户，发现 root 且未显式允许时直接退出并提示：

RUNNER_ALLOW_RUNASROOT=1 ./config.sh --help

较直接运行（不加环境变量）的差异：

Must not run with sudo

⚠️ 原因：config.sh/run.sh 检测到以 root（uid=0）执行且未设置 RUNNER_ALLOW_RUNASROOT 时会拒绝运行，防止误以提权方式启动。设置 RUNNER_ALLOW_RUNASROOT=1 即明确允许 root 运行。本文环境使用 root 账号，后文所有 config.sh/run.sh 调用均需携带该变量。

五、方案 B：国内加速镜像 / 离线 tar.gz 安装

5.1 国内加速镜像下载（在线，国内服务器推荐）

当直连 GitHub 下载被重置或超时时，用加速前缀 https://ghfast.top/ 拼接到官方下载地址之前：

cd /tmp
curl -fsSL -o actions-runner-linux-x64-2.338.0.tar.gz \
  "https://ghfast.top/https://github.com/actions/runner/releases/download/v2.338.0/actions-runner-linux-x64-2.338.0.tar.gz"
ls -lh actions-runner-linux-x64-2.338.0.tar.gz

执行结果：

-rw-r--r-- 1 root root 218M Oct  9 12:23 actions-runner-linux-x64-2.338.0.tar.gz

⚠️ 说明：若 ghfast.top 不可用，可换 https://ghproxy.net/、https://mirror.ghproxy.com/ 等效前缀，二者均对官方 URL 提供代理。加速站主要面向 GitHub 公开资源，下载后仍须按官方 sha256 校验。

5.2 离线/内网机器安装

在能联网的机器上用 5.1 下载好 tar.gz，通过 scp 或 U 盘拷贝到目标服务器，然后按与方案 A 完全相同的步骤执行：

mkdir -p /opt/data/github-actions/actions-runner
cd /opt/data/github-actions/actions-runner
tar xzf /tmp/actions-runner-linux-x64-2.338.0.tar.gz
sha256sum actions-runner-linux-x64-2.338.0.tar.gz

校验执行结果（应与此前一致）：

af4b794c1bc41d73d40535e3fe092a39f9679cd8d965954c2aca25a05ca41d32  actions-runner-linux-x64-2.338.0.tar.gz

💡 说明：两种方案最终得到完全相同的安装目录结构，后续"六、注册""七、systemd"步骤对 A、B 完全通用。

六、注册 Runner（config.sh）

⚠️ 前置：注册需要 GitHub 仓库的注册 Token与仓库地址。注册 Token 的有效期仅 1 小时，需在仓库页面 Settings → Actions → Runners → New self-hosted runner 中生成，或者调用 POST /repos/{owner}/{repo}/actions/runners/registration-token 换取。本文以示例仓库 https://github.com/quzuo-ops/demo-app 演示流程。

6.1 交互式注册正在等待 Token 时的界面

一旦拿到注册 Token（示例假设为 AAAA-BBBB-CCCC），执行非交互式注册：

cd /opt/data/github-actions/actions-runner
RUNNER_ALLOW_RUNASROOT=1 ./config.sh --unattended \
  --url https://github.com/quzuo-ops/demo-app \
  --token AAAA-BBBB-CCCC --name demo-runner --labels self-hosted,Linux,X64,demo

成功时的预期回显（节选，以真实注册输出为准）：

--------------------------------------------------------------------------------
|        ____ _ _   _   _       _          _        _   _                      |
|  ...  Self-hosted runner registration  ...                                  |
--------------------------------------------------------------------------------

√ Connected to GitHub
√ Runner Registration succeeded
√ Downloading listener ... done
√ Runner running startup generation ...
√ Runner registration partially succeeded.

⚠️ 说明：以上为"预期输出"。注册依赖真实仓库与有效 Token（且 Token 有时效），本机未对接真实仓库，无法完整复现连接成功的回显；若 Token 无效或仓库不存在，实测会返回如下失败（见 6.2）。请读者在真实仓库上执行 ./config.sh 后以实际回显为准。

6.2 无效 Token / 仓库失败的实测回显

使用无效 Token 时，config.sh 输出注册失败信息（ASCII 横幅 Self-hosted runner registration + 请求失败）：

RUNNER_ALLOW_RUNASROOT=1 ./config.sh --unattended \
  --url https://github.com/quzuo-ops/demo-app --token ghp_faketoken123

实测回显（末尾关键行）：

--------------------------------------------------------------------------------
|        ____ _ _   _   _       _          _        _   _                      |
|       / ___(_) |_| | | |_   _| |__      / \   ___| |_(_) ___  _ __  ___      |
|      | |  _| | __| |_| | | | | '_ \    / _ \ / __| __| |/ _ \| '_ \/ __|     |
|      | |_| | | |_|  _| | |_| | |_) |  / ___ \ (__| |_| | (_) | | | \__ \     |
|       \____|_|\__|_| |_|\__,_|_.__/  /_/   \_\___|\__|_|\___/|_| |_|___/     |
|                                                                              |
|                       Self-hosted runner registration                        |
|                                                                              |
--------------------------------------------------------------------------------

# Authentication

Http response code: NotFound from 'POST https://api.github.com/actions/runner-registration' (Request Id: ...)

⚠️ 定位：Http response code: NotFound 表示前往 POST https://api.github.com/actions/runner-registration 时未通过认证（Token 无效或仓库不存在）。解决办法：核对仓库名，重新生成未过期的注册 Token（有效期 1 小时），再执行 6.1。

6.3 config.sh 主要参数速查（真实 --help）

RUNNER_ALLOW_RUNASROOT=1 ./config.sh --help

实测回显（全量对比）：

Commands:
 ./config.sh         Configures the runner
 ./config.sh remove  Unconfigures the runner
 ./run.sh            Runs the runner interactively. Does not require any options.

Options:
 --help     Prints the help for each command
 --version  Prints the runner version
 --commit   Prints the runner commit
 --check    Check the runner's network connectivity with GitHub server

Config Options:
 --unattended           Disable interactive prompts for missing arguments. Defaults will be used for missing options
 --url string           Repository to add the runner to. Required if unattended
 --token string         Registration token. Required if unattended
 --name string          Name of the runner to configure (default c705af9cc8b2)
 --runnergroup string   Name of the runner group to add this runner to (defaults to the default runner group)
 --labels string        Custom labels that will be added to the runner. This option is mandatory if --no-default-labels is used.
 --no-default-labels    Disables adding the default labels: 'self-hosted,Linux,X64'
 --local                Removes the runner config files from your local machine. Used as an option to the remove command
 --work string          Relative runner work directory (default _work)
 --replace              Replace any existing runner with the same name (default false)
 --pat                  GitHub personal access token with repo scope. Used for checking network connectivity when executing `./run.sh --check`
 --disableupdate        Disable self-hosted runner automatic update to the latest released version`
 --ephemeral            Configure the runner to only take one job and then let the service un-configure the runner after the job finishes (default false)

Examples:
 Check GitHub server network connectivity:
  ./run.sh --check --url <url> --pat <pat>
 Configure a runner non-interactively:
  ./config.sh --unattended --url <url> --token <token>
 Configure a runner non-interactively, replacing any existing runner with the same name:
  ./config.sh --unattended --url <url> --token <token> --replace [--name <name>]
 Configure a runner non-interactively with three extra labels:
  ./config.sh --unattended --url <url> --token <token> --labels L1,L2,L3

💡 说明：各参数详细含义见《GitHub Actions 配置参数详解》。--name 默认取宿主主机名（本机为 c705af9cc8b2），自定义多个 Runner 时务必用 --name 显式区分。

七、systemd 服务托管

7.1 生成 systemd 服务（svc.sh install）

注册成功并生成 .service 配置后，用随包自带的 bin/systemd.svc.sh.template 生成并注册服务。执行 ./svc.sh install 时，脚本会用配置写入单元文件并 systemctl enable：

cd /opt/data/github-actions/actions-runner
RUNNER_ALLOW_RUNASROOT=1 ./svc.sh install

⚠️ 说明：此命令依赖"六、注册"已生成 .service 文件，本机因未完成真实注册，仅保证命令形态正确；真实执行后脚本会打印 Creating launch runner in /etc/systemd/system/actions.runner.quzuo-ops-demo-app.demo-runner.service、Run as user: root 与 Created symlink ... 等回显。

7.2 服务单元文件模板（真实内容）

脚本把 bin/actions.runner.service.template 渲染为服务文件，模板真实内容如下：

[Unit]
Description=GitHub Actions Runner
After=network-online.target

[Service]
ExecStart=/opt/data/github-actions/actions-runner/runsvc.sh
User=root
WorkingDirectory=/opt/data/github-actions/actions-runner
KillMode=process
KillSignal=SIGTERM
TimeoutStopSec=5min

[Install]
WantedBy=multi-user.target

💡 说明：After=network-online.target 保证开机网络就绪后再启动 runner；KillMode=process + TimeoutStopSec=5min 实现在任务执行结束后优雅停止。

7.3 启停与状态查看

systemctl start actions.runner.quzuo-ops-demo-app.demo-runner.service
systemctl status actions.runner.quzuo-ops-demo-app.demo-runner.service

⚠️ 说明：服务名形如 actions.runner.{owner}-{repo}.{runner-name}.service，由注册时的仓库与 --name 决定。本机未注册，status 会提示无法找到对应单元，欢迎引导读者以真实注册后的服务名执行。

7.4 svc.sh 用法速查（--help 未提供，脚本内内置）

./svc.sh [install, start, stop, status, uninstall]

install [user]：安装服务，可指定以 root 或指定用户运行；
start / stop / status：启停与查看状态；
uninstall：卸载并禁用服务。

八、多方案对比与选择建议

方案	版本	是否需联网	安装方式	service 来源	优缺点
A 官方直连 tar.gz	2.338.0	需要	GitHub Releases 直接下载	systemd（svc.sh install）	官方权威；国内网络可能直连失败
B 国内加速镜像 tar.gz	2.338.0	需要	加速节点下载	systemd（svc.sh install）	下载稳定，国内服务器推荐
B2 离线 tar.gz	2.338.0	不需要（下载机器需联网）	先下载后拷贝	systemd（svc.sh install）	适合内网/断网机器

💡 选择建议：国内云服务器优先方案 B（加速镜像）；能直连 GitHub 的海外服务器用方案 A；严格内网隔离环境用 B2 离线包。无论哪种方案，安装后都进入"六、注册 + 七、systemd"统一流程。

九、配置说明

安装目录：/opt/data/github-actions/actions-runner
工作目录：_work（相对 runner 根目录），可用 config.sh --work 调整
环境文件：.env（初始为空，注册后写入 RUNNER_* 环境固定值）
系统 PATH：.path（实测内容 /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin）
诊断目录：_diag（运行日志，如 _diag/InternetCheck_xxxxxxxx-xxxxxx-utc.log）
更新：GitHub 会在后台自动把 runner 更新到最新发布版；如需关闭用 config.sh --disableupdate

十、验证 Run 的连通性（真实回显）

cd /opt/data/github-actions/actions-runner
RUNNER_ALLOW_RUNASROOT=1 ./run.sh --check \
  --url https://github.com/quzuo-ops/demo-app --pat ghp_invalid-token

实测回显（网络与 Actions 服务检查）：

*** Check:  Internet Connection ***
**  Description:  Check if the Actions runner has internet access.  **
                              P A S S

*** Check:  GitHub Actions Connection ***
**  Description:  Check if the Actions runner has access to the GitHub Actions service.  **
                              F A I L

⚠️ 说明：第一项 P A S S 表示服务器出网正常；第二项因使用了无效 PAT 而 F A I L（联网探测需真实 ghp_ PAT）。你若在仓库授权下替换为有效 PAT，两项都应 P A S S。完整不失败的流程见《GitHub Actions 配置参数详解》里 run.sh --check --pat 说明。

十一、常见问题

Q1：执行 config.sh 提示 Must not run with sudo，怎么解决？

以 root 运行时需先设置 RUNNER_ALLOW_RUNASROOT=1，或在非 root 账号（普通用户）下执行，否则脚本会拒绝（详见 4.5）。

Q2：直连 GitHub 下载 tar.gz 报 curl: (56) Connection reset by peer？

网络到 GitHub 传输不稳定导致。改用方案 B 的 ghfast.top/ghproxy.net 镜像前缀，或加 --retry 5 --retry-delay 3，下载后务必 sha256sum 校验。

Q3：注册时返回 Http response code: NotFound from 'POST .../actions/runner-registration'？

Token 无效、过期（有效期 1 小时）或仓库名错误。重新在仓库 Settings → Actions → Runners 生成新 Token 再执行 6.1。

Q4：以 root 跑 Runner 是否有安全顾虑？

Runner 会执行仓库工作流中的任意代码。root 运行时等同把仓库代码以 root 权限在本机执行，务必只对可信仓库注册。可改用专有低权限用户运行（见《配置参数详解》的 svc.sh install <user> 用法）。

十二、卸载与清理

cd /opt/data/github-actions/actions-runner
RUNNER_ALLOW_RUNASROOT=1 ./svc.sh uninstall

rm -rf /opt/data/github-actions/actions-runner
rm -f /tmp/actions-runner-linux-x64-2.338.0.tar.gz

💡 说明：svc.sh uninstall 会停止并禁用服务、删除单元文件与 .service 配置；随后删除安装目录与下载的安装包即可。若用非交互式注册过，还应到仓库页面删除该 Runner 记录。

十三、参考链接

Runner 官方安装文档：https://docs.github.com/zh/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners
Runner releases（版本与 sha256）：https://github.com/actions/runner/releases
svc.sh 服务脚本：bin/systemd.svc.sh.template / bin/actions.runner.service.template
国内加速镜像：https://ghfast.top/、https://ghproxy.net/