官方文档：https://docs.github.com/en/actions

本文参考：https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/add-runners

为企业生产环境搭建 GitHub 自托管 Runner 需要谨慎操作。下面我为你整理了支持 amd64 和 arm64 架构的 Linux 服务器的权威安装步骤。流程和关键信息参考了 GitHub 官方文档和社区实践，力求清晰可靠。

首先，你可以通过下面的表格了解核心安装步骤：

接下来是每个步骤的详细说明。

📋 前期准备

1. 获取注册 Token：

   • 访问你的 GitHub 仓库 (或组织) 的 Settings -> Actions -> Runners。
   • 点击 New self-hosted runner。
   • 选择操作系统 (Linux) 和架构（x64/amd64 或 ARM64/ARM），页面会生成一个唯一的 Token。请妥善保管此 Token，它有效期很短。

2. 服务器准备：

   • 确保你的 Linux 服务器（amd64 或 arm64 架构）可以稳定访问 GitHub。

   • 安装基础依赖，通常包括：

     # 对于基于 Debian/Ubuntu 的系统
     sudo apt-get update
     sudo apt-get install -y curl tar
     
     # 对于基于 RHEL/CentOS/Rocky 的系统
     sudo yum check-update || true
     sudo yum install -y curl tar

   • (可选但建议) 创建一个专用的非特权用户来运行 Runner，例如 github-runner：

     sudo useradd -m -d /home/github-runner -s /bin/bash github-runner

📥 下载与安装 Runner

1. 创建目录并下载：
   在你的服务器上，依次执行以下命令。请务必将 <architecture> 替换为你的服务器架构：amd64 或 arm64。

   # 创建 runner 目录，可自定义
   mkdir actions-runner && cd actions-runner
   
   # 下载对应架构的 Runner 压缩包
   # 对于 AMD64 (x86-64) 架构：
   curl -o actions-runner-linux-x64-2.317.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.317.0/actions-runner-linux-x64-2.317.0.tar.gz
   
   # 对于 ARM64 架构：
   # curl -o actions-runner-linux-arm64-2.317.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.317.0/actions-runner-linux-arm64-2.317.0.tar.gz
   
   # (可选) 验证哈希值，建议生产环境进行
   # 下载哈希文件，例如对于 amd64：
   # curl -o actions-runner-linux-x64-2.317.0.tar.gz.sha256 -L https://github.com/actions/runner/releases/download/v2.317.0/actions-runner-linux-x64-2.317.0.tar.gz.sha256
   # 验证
   # echo "$(cat actions-runner-linux-x64-2.317.0.tar.gz.sha256)  actions-runner-linux-x64-2.317.0.tar.gz" | shasum -a 256 -c

   注意：Runner 版本号（此例中的 v2.317.0）会不断更新。建议前往 GitHub Actions Runner Releases 页面查看最新稳定版本，并替换下载链接中的版本号。

2. 解压压缩包：

   # 解压
   tar xzf ./actions-runner-linux-x64-2.317.0.tar.gz

   解压后你会看到 config.sh, run.sh, bin/ 等文件和目录。

🖊️ 注册 Runner

1. 运行配置脚本：
   使用之前从 GitHub 页面上获取的 Token 和 URL 运行配置脚本。

   ./config.sh --url https://github.com/your-organization/your-repository --token YOUR_REGISTRATION_TOKEN

   • 将 https://github.com/your-organization/your-repository 替换为你的仓库或组织的真实 URL。
   • 将 YOUR_REGISTRATION_TOKEN 替换为准备步骤中获取的 Token。

2. 交互式配置：
   执行命令后，你会进入交互式配置流程：

   • Runner 名称（Enter the name of the runner）：输入一个易于标识此 Runner 的名称（如 prod-runner-linux-amd64），默认为服务器主机名。
   • Runner 标签（Enter any additional labels）：你可以添加自定义标签（如 linux, prod, amd64），用逗号分隔。标签用于在 Workflow 中通过 runs-on 指定使用哪个 Runner。
   • 执行器（Enter the executor）：对于生产环境，通常选择 shell（直接在主机 shell 运行）或 docker（使用 Docker 容器运行，更安全）。根据你的需求选择。

   注册成功后，你会看到 Runner successfully added 的提示。配置信息会保存在当前目录下的 .runner 文件和相关配置文件中。

🚀 运行与管理 Runner

1. 安装为系统服务（推荐）：
   为了确保 Runner 在后台稳定运行并在服务器重启后自动启动，强烈建议将其安装为系统服务。GitHub Runner 包提供了便捷的脚本：

   注意：执行完 ./config.sh --url https://github.com/brinnatt/kubeauto --token xxx 才会生成 svc.sh 脚本。

   # 安装服务（如果您创建了专用用户，请使用 --user 参数指定，如 sudo ./svc.sh install github-runner）
   sudo ./svc.sh install
   
   # 启动服务
   sudo ./svc.sh start
   
   # 查看服务状态
   sudo ./svc.sh status

   安装为服务后，Runner 会在后台持续运行并监听 GitHub 的作业任务。

2. （可选）直接运行：
   仅用于测试或不适合安装服务的环境，可以在前台运行：

   ./run.sh

   注意：这种方式终端关闭后进程会结束。

🔒 权限与安全建议（企业生产环境必读）

• 专用用户：如前所述，务必使用专用的非 root 用户（如 github-runner）来安装和运行服务 (sudo ./svc.sh install github-runner)，遵循最小权限原则。
• 目录权限：确保 actions-runner 目录及其文件的所有权和权限设置恰当，避免使用 sudo 运行 Runner 的命令或脚本。
• Token 安全：注册 Token 是临时的，一旦 Runner 注册成功，服务会自动管理后续的认证。切勿泄露 Token。
• 网络与防火墙：确保服务器能访问 github.com 以及 GitHub Actions 所需的其它网络资源（如软件包源）。根据企业安全策略配置防火墙。
• 标签策略：为不同用途（如生产、测试）、不同架构（amd64, arm64）的 Runner 设置清晰且具有区分度的标签（labels），以便在 Workflow 中精确指定 runs-on: [self-hosted, your-specific-label]。
• 监控与日志：Runner 的服务日志通常由 systemd 管理，可使用 journalctl -u actions.runner.service -f 等命令查看。定期检查 Runner 状态和日志。

🐛 验证与故障排除

1. 验证：回到 GitHub 仓库的 Settings -> Actions -> Runners 页面。稍等片刻，你应该能看到新注册的 Runner，状态会从 Offline 变为 Idle（绿色），表示已就绪。

2. 运行测试工作流：创建一个简单的 .github/workflows/test-runner.yml 文件来测试：

   name: Test Self-Hosted Runner
   on:
    workflow_dispatch: # 允许手动触发
   jobs:
    test:
      runs-on: [self-hosted, YOUR_RUNNER_LABEL] # 使用你为此 Runner 设置的标签
      steps:
        - name: Check Architecture
          run: uname -m

   推送此工作流后手动触发，如果成功，Runner 会执行作业，你可以在 GitHub 上看到输出结果（例如 aarch64 或 x86_64）。

3. 常见问题：

   • Must not run with sudo：如果配置时遇到此错误，请确保你没有使用 root 用户执行脚本，或者设置 RUNNER_ALLOW_RUNASROOT="1" 环境变量来允许（非必要不推荐）。
   • 404 Not Found when registering：通常表示 Token 已过期。Token 有效期很短，请从 GitHub 界面获取新的 Token 并重新注册。
   • 架构不匹配：确保下载的 Runner 压缩包架构与你的服务器架构完全一致。