GitHub Actions 自托管 Runner 配置避坑指南：3 类常见故障与 5 步维护流程

1. 三类故障不是偶然，是配置逻辑没对齐我接手过七个用自托管 Runner 的项目，其中六个在上线两周内都出现过至少一次“任务卡死但进程不报错”的情况。最典型的一次：一个本该 90 秒跑完的单元测试 Job，在 Runner 上挂了 27 分钟，日志最后一行停在npm install，ps aux | grep npm却查不到任何进程。重启 Runner 后立刻恢复——这根本不是资源不足的问题，而是配置层面对 GitHub Actions 执行模型的理解偏差。很多人把自托管 Runner 当成“更听话的 GitHub-hosted Runner”，以为只要装上 agent、注册进组织，剩下的就交给 YAML 文件。但事实是：自托管 Runner 的稳定性，80% 取决于你是否理解它和 GitHub Actions 平台之间的契约关系。这个契约不是靠文档读出来的，是靠三次以上服务中断后翻日志、改配置、再验证才刻进肌肉记忆的。比如，AI 编程工具（如 Cursor、Trae、Claude Code）在生成 CI 配置时，常默认使用ubuntu-latest的语义，自动补全runs-on: self-hosted却不显式声明标签（labels）。结果就是：当你的 Runner 标签是linux-amd64-gpu，而.yml里只写runs-on: self-hosted，GitHub 就会把它和所有其他self-hostedRunner 放进同一个调度池—