cicd Roadmap
CI/CD 流水线排障专题
CI/CD 流水线排障专题：聚合 GitHub Actions、GitLab CI 和 Jenkins 的 Runner 离线与标签不匹配、缓存失效、构建 OOM、Docker 镜像拉取失败、secrets 未注入和 CI 本地不一致等常见问题的排障路径。
CI/CD 排障先区分是 YAML 配置错误、Runner 基础设施还是执行环境差异，再决定改流水线还是查 Runner；job 长时间 pending 通常是 Runner 离线或标签不匹配，而不是脚本本身写错。
Troubleshooting Path
推荐排障路线图
- 01
先确认流水线状态和失败位置
看 job 是 pending、失败还是卡住，定位到具体步骤和报错，而不是反复重试。
- 02
再查 Runner 在线与标签匹配
job 一直 pending 通常是 Runner 离线、标签不匹配或并发额度不足，而不是语法错误。
- 03
继续对比本地与 CI 环境差异
复现失败时对比 Docker socket、网络、secrets 注入和缓存路径，区分配置和环境问题。
- 04
最后校验缓存和密钥配置
确认缓存 key 用 lockfile hash、secrets 作用域正确，日志里不要打印敏感信息。
Common Issues
高频问题入口
Before You Change
执行前检查
- 排查前保留失败 job 的完整日志和触发上下文
- 调缓存 key 前确认路径覆盖真实依赖目录
- 调试时不要在日志中打印 secrets 或 token
- 本地复现用 act 或 gitlab-runner exec，避免直接在生产流水线试错
Start Here
优先阅读
CI 缓存失效排查方法
CI 缓存不命中、每次构建都从零安装依赖时，先对比 restore/save 步骤打印的 cache key 是否变化，再检查缓存路径配置、runner OS 前缀和 gh cache list 中的实际条目，常见根因是 key 把易变内容算入或 restore-keys 顺序不对。
排障CI 中 Docker 构建失败排查方法
CI 流水线 docker build 报错、层缓存失效或 permission denied 时，用 --progress=plain --no-cache 输出完整构建日志，检查 docker.sock 权限、buildx builder 和 Dockerfile 指令顺序，常见根因是 socket 无权限、上下文频繁变化或缓存未持久化。
排障GitHub Actions Runner 离线排查方法
GitHub Actions 自托管 Runner 显示 offline、job 一直 waiting for runner 时，用 systemctl status actions.runner.* 确认服务状态，查看 ~/actions-runner/_diag 日志中的连接错误，排查 registration token 过期和到 github.com 的网络代理与证书。
排障GitLab CI 流水线失败排查方法
GitLab CI 流水线失败、job 报错或 pending 不执行时，用 gitlab-runner verify 测试 Runner 与 GitLab 连接，检查 Runner tags 是否匹配 job、executor 类型（shell/docker/kubernetes）配置和 registration token，再用 journalctl 看 gitlab-runner 服务日志定位脚本或镜像问题。
Latest Updates
最近更新
All Runbooks
全部相关内容
CI 缓存失效排查方法
CI 缓存不命中、每次构建都从零安装依赖时，先对比 restore/save 步骤打印的 cache key 是否变化，再检查缓存路径配置、runner OS 前缀和 gh cache list 中的实际条目，常见根因是 key 把易变内容算入或 restore-keys 顺序不对。
排障CI 中 Docker 构建失败排查方法
CI 流水线 docker build 报错、层缓存失效或 permission denied 时，用 --progress=plain --no-cache 输出完整构建日志，检查 docker.sock 权限、buildx builder 和 Dockerfile 指令顺序，常见根因是 socket 无权限、上下文频繁变化或缓存未持久化。
排障GitHub Actions Runner 离线排查方法
GitHub Actions 自托管 Runner 显示 offline、job 一直 waiting for runner 时，用 systemctl status actions.runner.* 确认服务状态，查看 ~/actions-runner/_diag 日志中的连接错误，排查 registration token 过期和到 github.com 的网络代理与证书。
排障GitLab CI 流水线失败排查方法
GitLab CI 流水线失败、job 报错或 pending 不执行时，用 gitlab-runner verify 测试 Runner 与 GitLab 连接，检查 Runner tags 是否匹配 job、executor 类型（shell/docker/kubernetes）配置和 registration token，再用 journalctl 看 gitlab-runner 服务日志定位脚本或镜像问题。
排障Jenkins 构建卡住排查方法
Jenkins 构建卡在队列不动或执行中挂起时，用 queue/api/json 查看队列 why 阻塞原因，computer/api/json 检查 executor 是否 offline，卡死用 jstack 抓 Jenkins 主线程转储，多数是节点掉线、标签不匹配或 Quiet Period 延迟。
排障Redis 内存占用过高与淘汰策略排查
Redis 内存持续上涨、报 OOM command not allowed when used memory > 'maxmemory' 或 evicted_keys 飙升时，先用 INFO memory 看 used_memory/maxmemory，CONFIG GET maxmemory-policy 确认策略是否 noeviction，再用 --bigkeys 找大 key 并检查 TTL 是否缺失。
命令CI/CD 常用排障命令
CI/CD 排障常用命令合集，Jenkins 用 jenkins-cli 与 queue/computer API 查队列和 executor，GitLab 用 gitlab-runner verify/list 检查 Runner，GitHub Actions 用 gh run list、gh run view --log-failed、gh cache 定位失败步骤和缓存。