Docker-GitHub Actions Runner 中Runner自动注销问题分析与解决方案

问题背景

在使用docker-github-actions-runner项目部署GitHub Actions Runner时，用户遇到了Runner无法自动注销的问题。当通过Docker Swarm部署多个Runner实例时，离线状态的Runner会长期保留在GitHub的Runner列表中，最终导致达到10000个Runner的组上限，新Runner无法注册。

技术分析

1. Runner生命周期管理机制

GitHub Actions Runner在设计上支持自动注销功能。当Runner容器正常停止时，会接收到SIGTERM信号，触发注销流程。这一机制在项目的entrypoint.sh脚本中实现，包含以下关键步骤：

1. 捕获SIGTERM信号
2. 调用Runner.Listener deregister命令
3. 从GitHub服务器移除Runner注册信息

2. Docker Swarm信号传递问题

在Docker Swarm环境中，Runner无法自动注销的根本原因是信号传递机制不完善。默认情况下，Swarm可能不会正确发送SIGTERM信号，或者发送的信号没有被容器正确处理。这导致Runner在停止时无法执行注销流程。

3. GitHub的自动清理机制

虽然GitHub会在14天后自动清理离线的Runner，但对于高频部署的场景，这个时间窗口过长，无法解决Runner数量快速积累的问题。

解决方案

方案一：配置Docker Compose信号处理

在docker-compose.yml中明确配置信号处理参数：

services:
  runner:
    ...
    stop_grace_period: 10s
    stop_signal: SIGTERM

这两个配置确保：

• 容器停止时发送SIGTERM信号
• 给予足够时间(10秒)完成注销流程

方案二：使用Ephemeral模式

通过修改启动命令启用临时Runner模式：

command: ["./bin/Runner.Listener", "run", "--startuptype", "service", "--ephemeral"]

Ephemeral模式的特点是：

• 每个Runner只执行一个任务后自动注销
• 适合短任务场景
• 避免Runner积累问题

方案三：定期清理脚本

对于大规模部署，可以编写定期清理脚本，通过GitHub API删除离线时间超过阈值的Runner。

最佳实践建议

1. 对于Swarm/Kubernetes环境，必须配置正确的信号处理参数
2. 根据任务类型选择Runner模式：
   • 长任务：常规模式+正确信号配置
   • 短任务：Ephemeral模式
3. 监控Runner数量，设置提醒机制
4. 定期检查离线Runner，必要时手动清理

实施效果验证

部署修改后，应检查以下指标确认问题解决：

1. 停止的Runner是否从GitHub界面消失
2. 新Runner能否正常注册
3. 系统日志中是否出现"Caught SIGTERM. Deregistering runner"记录

通过以上方案，可以有效解决Runner积累问题，保证CI/CD环境的稳定运行。