gitlab ci 的 retry 关键字通过限制重试次数与触发条件实现网络不稳定场景的自动化容错，适用于幂等的网络操作（如镜像拉取、包安装），需配合退避策略、缓存和超时设置提升效果。
在 Linux 环境下利用 GitLab CI 的 retry 关键字实现网络不稳定场景的自动化容错，核心是**让失败的作业自动重试、控制重试次数、避免无限循环，并配合合理的退避策略降低重试冲击**。它不是“失败就盲目重跑”，而是有节制、有依据的弹性恢复机制。
retry 基础配置：控制重试次数和触发条件
retry 是 .gitlab-ci.yml 中的作业级关键字，接受整数（最大 2）或映射结构。最常用的是指定最大重试次数，并可限定仅对特定失败原因重试：
- 简单写法（最多重试 2 次，即总共运行 3 次）：
retry: 2 - 精准控制（只在网络类错误时重试，其他错误如语法错误不重试）：
retry:<br> max: 2<br> when:<br> - runner_system_failure<br> - stuck_or_timeout_failure<br> - unknown_failure
这些值对应 GitLab 内置的失败类型，其中stuck_or_timeout_failure就涵盖网络超时、Docker pull 超时、镜像推送中断等典型弱网问题。
结合网络操作场景：哪些作业该加 retry？
不是所有作业都需要重试。应聚焦于**对外部网络依赖强、易受抖动影响、且幂等安全的操作**：
openclaw-gitcode-pr-monitor
下载
监控一个或多个 GitCode 仓库的 PR，通过 OpenClaw Gateway 自动执行 AI 审查，发布 PR 评论，并发送钉钉和企业微信通知。
-
Docker 镜像拉取与推送：比如
docker pull registry.example.com/app:latest或docker push，常因 DNS 解析慢、中间代理断连、仓库响应超时而失败； -
包管理器安装依赖：如
pip install -r requirements.txt、npm ci、apt-get update && apt-get install，在代理或源不稳定时容易中断； - 远程 API 调用类测试：比如调用测试环境的 Auth 服务、Mock Server 或第三方 SaaS 接口的集成测试；
- 避免用于：数据库迁移（非幂等）、文件写入类操作（可能重复导致脏数据）、或本地编译失败（通常是代码/配置问题，重试无意义）。
提升容错效果：retry 不是万能药，需配套措施
单纯设 retry: 2 可能造成短时间内密集重试，加剧网络拥塞或触发仓库限流。建议组合以下实践：
-
添加指数退避逻辑（脚本层）：GitLab 自身不提供等待间隔，但你可在
script中封装带延迟的命令。例如用 Bash 实现简单退避：for i in {0..2}; do<br> if docker push myapp:$CI_COMMIT_TAG; then break; fi<br> if [ $i -lt 2 ]; then sleep $((100 * (2 ** $i))); fi # 第1次等100ms，第2次等200ms<br>done -
使用缓存减少网络依赖：通过
cache缓存~/.cache/pip、node_modules或~/.m2，让后续重试更快命中本地资源，降低对外部源的请求频次； -
设置合理超时：配合
timeout关键字（如timeout: 15 minutes），防止某次重试卡死过久； -
日志中明确标记重试行为：在 script 开头打印
echo "Attempt #$CI_JOB_ATTEMPT of $CI_JOB_NAME"，便于排查是首次失败还是重试失败。
验证与观察：确认 retry 是否生效
配置后别只看最终成功——要主动验证容错能力：
- 在流水线页面点开某次失败的作业，查看其“Attempts”标签页，能看到每次重试的独立执行记录、耗时和日志；
- 故意模拟弱网：在 Runner 主机上用
tc（Traffic Control）注入丢包或高延迟，例如：sudo tc qdisc add dev eth0 root netem loss 20% delay 500ms，再触发流水线，观察是否触发重试并最终成功； - 检查 GitLab CI 的“Jobs”列表，若某作业状态显示为黄色感叹号（⚠️）而非红色叉号（❌），说明它失败但因
retry允许继续，这是预期行为。
