Gitea Actions Runner实战排错手册从部署到稳定的全链路解决方案在私有化代码托管场景中Gitea Actions正成为越来越多开发团队构建轻量级CI/CD的首选方案。但当我们将GitHub Actions的工作流迁移到自托管环境时Runner的配置过程往往充满各种惊喜——无效的注册令牌、突然离线的Runner实例、卡在Pending状态的任务队列或是因网络问题导致的Actions拉取失败。本文将基于真实运维场景拆解这些典型问题的根因与解决方案。1. Runner注册失败的深度排查当执行act_runner register命令后看到Invalid token或Failed to register runner提示时多数开发者会本能地重新生成令牌再次尝试。但注册失败往往暗示着更深层次的配置问题。令牌失效的四种常见场景令牌生命周期过期Gitea生成的Runner注册令牌默认有效期为1小时超时后需在仓库设置中重新生成实例地址格式错误--instance参数需使用完整的Gitea基础URL如http://192.168.1.100:3000缺少协议头或端口号会导致连接失败反向代理配置问题当Gitea通过Nginx反向代理时需确保proxy_set_header Connection $http_connection;等WebSocket相关配置已正确设置防火墙规则限制Runner默认通过端口3000与Gitea通信企业内网环境可能需开放3000/tcp出站规则提示使用./act_runner --config config.yaml register --no-interactive --instance url --token token命令时建议先通过curl -v gitea_url/api/v1/actions/runners/registration-token验证令牌是否可被API读取。若确认令牌有效但仍注册失败可检查Runner主机的DNS解析配置。在Windows环境下执行nslookup your_gitea_domain在Linux环境下dig your_gitea_domain short确保域名能正确解析到Gitea服务器IP。对于离线环境需在hosts文件中添加静态解析记录192.168.1.100 gitea.company.com2. 配置文件陷阱与优化实践默认生成的config.yaml可能成为后续问题的根源。以下是一个经过生产验证的配置模板labels: [ubuntu:latest] # 必须与工作流中runs-on标签匹配 workdir_parent: /opt/gitea-runner/_work container: network: host privileged: true # 需要Docker in Docker时启用 cache_dir: /opt/gitea-runner/_cache关键参数对比分析参数默认值推荐值风险说明networkbridgehostbridge模式下容器间通信需额外配置privilegedfalsetrue非特权模式无法运行Docker命令workdir_parent系统临时目录固定路径临时目录可能导致工作流文件丢失对于需要执行Docker构建的工作流还需在Runner主机上配置/etc/docker/daemon.json{ insecure-registries: [192.168.1.100:5000], registry-mirrors: [https://mirror.gcr.io] }配置完成后建议使用测试工作流验证基础功能name: Validation Pipeline on: [push] jobs: test-container: runs-on: ubuntu:latest steps: - name: Check Docker run: docker --version - name: Test Network run: curl -I http://gitea-server:30003. 网络问题全场景解决方案私有部署环境中Runner无法拉取GitHub Actions是最常见的故障点。我们推荐三级解决方案方案一本地镜像关键Actions从官方仓库迁移actions/checkout到自建Gitea实例修改工作流引用路径为本地地址- uses: http://gitea/internal/actions/checkoutv3方案二搭建本地缓存代理对于无法迁移的第三方Actions可在内网部署缓存代理# 使用Nginx搭建简易缓存 location /actions/ { proxy_pass https://github.com/actions/; proxy_cache actions_cache; proxy_cache_valid 200 302 7d; }方案三离线包预分发对于完全隔离的网络环境可预先下载Actions组件包# 获取Actions组件树 git clone --depth1 https://github.com/actions/toolkit /opt/actions-cache然后在Runner配置中指定本地路径env: ACTIONS_CACHE_PATH: /opt/actions-cache网络连通性测试脚本保存为network_test.sh#!/bin/bash function check_connection() { if curl -s -I $1 /dev/null; then echo [OK] $1 else echo [FAIL] $1 exit 1 fi } check_connection http://gitea-server:3000 check_connection https://github.com check_connection https://registry-1.docker.io4. Runner稳定性保障体系Runner意外离线通常表现为任务长时间卡在Pending状态。以下是维持稳定运行的黄金法则进程守护方案对比方案实现方式适用场景缺点systemdRestartalwaysLinux生产环境需root权限Supervisorautorestarttrue多进程管理额外安装计划任务每分钟检测Windows环境有延迟Linux下推荐使用systemd单元文件/etc/systemd/system/gitea-runner.service[Unit] DescriptionGitea Actions Runner Afternetwork.target [Service] ExecStart/usr/local/bin/act_runner daemon --config /etc/gitea-runner/config.yaml Restartalways Usergit Groupgit [Install] WantedBymulti-user.targetWindows环境下可通过PowerShell脚本实现自愈$process Get-Process -Name act_runner -ErrorAction SilentlyContinue if (!$process) { Start-Process -FilePath D:\runner\act_runner.exe -ArgumentList daemon --config config.yaml }资源监控指标阈值指标警告阈值临界阈值检查命令CPU使用率70%90%top -bn1内存占用1GB2GBps -o rss -p $(pgrep act_runner)磁盘空间10%剩余5%剩余df -h /opt/gitea-runner当Runner需要处理高并发任务时可采用水平扩展策略# 启动多个Runner实例 for i in {1..4}; do nohup ./act_runner daemon --config config-$i.yaml /var/log/gitea-runner-$i.log 21 done在实际生产环境中我们曾遇到一个典型案例某嵌入式团队发现Runner在编译任务中随机崩溃。最终定位是MDK编译器的许可证检查机制与容器环境冲突。解决方案是在config.yaml中显式声明host网络模式并添加特定环境变量envs: ARMLMD_LICENSE_FILE: 27000license-server LM_LICENSE_FILE: /opt/license.dat