Gitea Action实战避坑：从config.yaml配置到act_runner容器网络，我的踩坑记录

Gitea Action实战避坑指南：从config.yaml到容器网络的深度排错手册

当你在深夜调试Gitea Action时，控制台不断刷新的红色错误日志是否让你感到绝望？作为一款轻量级的自托管CI/CD解决方案，Gitea Action虽然设计理念与GitHub Actions兼容，但在实际部署中却暗藏诸多"坑点"。本文将分享我在生产环境中趟过的那些雷区，从config.yaml的魔鬼细节到容器网络的诡异行为，带你直击问题本质。

1. config.yaml配置陷阱：那些官方文档没告诉你的细节

初次接触Gitea Action的开发者往往会直接复制官方示例的config.yaml，但这正是噩梦的开始。这个看似简单的配置文件里，每个参数都可能成为工作流无法触发的元凶。

1.1 网络模式：选错等于自杀

network参数的三种配置方式在实际环境中表现天差地别：

• host模式：看似简单但隐患最大，当宿主机已占用8080端口时，你的工作流容器会静默失败
• bridge模式：默认选择，但需要特别注意DNS解析问题
• 自定义网络：最安全的方案，但要求预先创建Docker网络

container: network: "gitea_net" # 推荐使用预先创建的docker网络

提示：使用前务必执行docker network create gitea_net，否则runner启动时会报网络不存在错误

1.2 特权模式的危险平衡

privileged: true几乎是所有Docker-in-Docker方案的必经之路，但这也意味着：

• 容器获得宿主机root权限
• 可能被恶意工作流利用进行提权攻击
• 某些企业环境中直接被安全策略拦截

container: privileged: false # 除非必须，否则保持关闭 options: "--security-opt=seccomp=unconfined" # 更安全的替代方案

1.3 缓存配置的典型误区

很多教程会教你启用cache配置，但以下数据来自我们对50个故障案例的统计：

正确的缓存配置应该是：

cache: enabled: true dir: "/mnt/runner_cache" # 需确保目录存在且可写 host: "runner-network-alias" # 使用Docker内网DNS port: 3268 # 固定端口便于排查

2. Runner注册的六大诡异现象

即使config.yaml完美无缺，runner注册阶段仍是故障高发区。以下是我们在社区收集的典型case：

2.1 注册成功但显示离线

症状：控制台显示注册成功，但Gitea后台始终显示offline
排查步骤：

1. 检查docker logs中的心跳日志
2. 确认fetch_interval不小于2秒
3. 测试Gitea实例URL能否从容器内访问

# 进入runner容器执行网络测试 docker exec -it gitea-runner curl -v http://gitea-server:3000

2.2 Token失效的隐藏原因

注册令牌的失效不仅因为过期，还可能由于：

• Gitea版本升级未重启
• 使用HTTPS但证书不受信任（需设置insecure: true）
• 反向代理配置错误导致API端点不可达

2.3 多runner的资源争夺

当多个runner共享同一配置目录时，会出现：

• .runner文件锁冲突
• 缓存数据损坏
• 日志互相覆盖

解决方案：

runner: file: "/data/${HOSTNAME}.runner" # 为每个runner分配独立文件

3. 容器网络：最棘手的黑暗森林

Gitea Action的容器网络问题就像量子物理——你不观察时一切正常，一旦开始测试就崩溃。

3.1 服务发现的正确姿势

工作流中访问其他服务时，传统方案是使用host.docker.internal，但在Linux环境下需要：

container: options: "--add-host=host.docker.internal:host-gateway"

3.2 跨runner通信方案

当需要多个job容器相互访问时，推荐网络架构：

1. 创建overlay网络
2. 为每个job分配固定别名
3. 通过环境变量传递访问地址

docker network create -d overlay gitea-action-net

3.3 端口冲突的预防性设计

动态端口分配是万恶之源，建议：

• 为常用服务预留端口段
• 在job中检查端口可用性
• 使用nc命令进行预检

# 在job步骤中添加端口检查 - name: Check port run: | if nc -z localhost 8080; then echo "Port 8080 in use!" exit 1 fi

4. 工作流调试的终极武器

当常规手段失效时，这些高阶调试技巧能救你于水火：

4.1 实时日志追踪术

组合使用多条命令实现立体监控：

# 三屏监控大法 watch -n 1 'docker ps --format "{{.ID}}\t{{.Status}}"' docker logs -f --tail=50 gitea-runner journalctl -u docker --follow

4.2 容器验尸报告

对失败容器进行"尸检"：

# 保存现场证据 docker inspect <dead-container> > inspection.json docker export <dead-container> > corpse.tar

4.3 压力测试方法论

使用artillery模拟高并发场景：

- name: Load test run: | npm install -g artillery artillery quick --count 20 -n 10 http://your-service:8080

5. 性能调优：从能用变好用

默认配置只能应付小型项目，要提升性能需要：

5.1 资源配额控制

通过cgroups限制单个job的资源消耗：

container: options: "--cpus=2 --memory=4g --blkio-weight=500"

5.2 镜像预热策略

在runner启动时预拉常用镜像：

FROM gitea/act_runner:nightly RUN docker pull ubuntu:22.04 && \ docker pull node:18-alpine

5.3 分布式runner部署

当单机性能达到瓶颈时，考虑：

• 按项目分组部署专用runner
• 使用标签系统进行路由
• 实现自动扩缩容机制

# 注册时添加标签 docker run ... -e LABELS=prod,large ...

在经历数十次生产环境部署后，我发现最危险的往往不是那些报错的问题，而是那些静默失败的场景。比如曾经有个runner因为磁盘inode耗尽而无法创建新容器，但所有日志都显示正常。这也让我养成了在每台runner主机上部署监控探针的习惯，现在我的标准部署模板里永远包含这组命令：

# 监控关键指标 df -i | grep -v tmpfs docker system df -v ss -tulnp | grep dockerd