Debian系统中GitLab的故障排查方法

Debian 上 GitLab 故障排查方法

一 快速定位流程

• 查看整体健康与组件状态：执行 gitlab-ctl status，对异常组件记录名称与状态。
• 实时查看日志：优先使用 gitlab-ctl tail（或 tail -f /var/log/gitlab/gitlab-ctl/production.log）观察启动与运行期报错；必要时用 journalctl -u gitlab-rails、journalctl -u gitlab-shell 定位服务层问题。
• 配置与依赖校验：核对 /etc/gitlab/gitlab.rb 中关键项（如 external_url、端口、域名、数据库/Redis 连接）；执行 gitlab-rake gitlab:check SANITIZE=true 做连通性与一致性自检；变更后执行 gitlab-ctl reconfigure 并 gitlab-ctl restart 使配置生效。
• 资源与连通性：用 top、free -m、df -h 检查 CPU/内存/磁盘；用 ping、curl 测试内外网与端口可达性；检查 UFW/iptables 是否放行 80/443（示例：ufw allow 80,443）。
• 变更记录：每次修改与重启都建议记录操作与结果，便于回溯。

二 常见故障与处理

• 访问出现 502 Bad Gateway：常见于端口被占用或内存不足。处理：检查占用（如 netstat/ss），必要时调整 /etc/gitlab/gitlab.rb 中的端口；内存紧张时临时启用 swap 或优化工作进程数。
• 服务无法启动：多由配置语法错误、依赖缺失或版本不兼容导致。处理：回滚最近变更，校验 gitlab.rb 语法，补齐依赖，必要时执行修复安装或版本升级。
• Runner 卡顿或任务超时：排查 docker.sock 响应、系统 CPU/IO 异常与资源争用；必要时隔离运行环境或优化宿主机负载。
• 克隆/推送失败：优先检查 SSH 密钥或 HTTPS 令牌是否正确、用户权限是否足够；遇到 “rejected non-fast-forward” 先合并或拉取再推送。
• 升级后数据库迁移失败：可临时设置 gitlab_skip_unmigrated_data_check true 重启以恢复访问，随后按官方流程补齐迁移。

三 日志与定位技巧

• 日志入口与检索：
  • 系统与服务日志：/var/log/syslog、journalctl -u gitlab-rails、journalctl -u gitlab-shell。
  • GitLab 组件日志：/var/log/gitlab/ 下的 production.log、gitlab-shell.log、sidekiq.log、nginx/gitlab_error.log 等；使用 gitlab-ctl tail 快速跟踪。
• 高效检索：结合 grep/less 过滤关键字（如 “error”, “timeout”, “PG::”, “connection refused”）；按时间窗口查看（如 journalctl --since/–until）。
• 运行期诊断：必要时用 strace 跟踪可疑进程系统调用，定位卡顿根因（如 docker.sock 请求阻塞）。

四 性能与资源优化

• 资源基线：GitLab 建议至少 4GB 内存；内存紧张可临时启用 swap 或降低并发工作进程数。
• 工作进程与并发：在 /etc/gitlab/gitlab.rb 中按 CPU 核数与负载调优 unicorn[‘worker_processes’] 或 puma 相关参数，避免 OOM 与高延迟。
• 数据库与缓存：结合负载调优 PostgreSQL shared_buffers、max_worker_processes，并合理设置 Redis 内存与持久化策略。
• 监控与维护：启用 Prometheus + Grafana 做资源与错误监控；配置 logrotate 管理日志体积，定期备份与升级。

五 变更与回滚建议

• 变更前：备份关键数据与配置（含 /etc/gitlab/gitlab.rb 与数据库），在维护窗口操作。
• 变更中：小步迭代，每次只改一处；变更后执行 gitlab-ctl reconfigure 与 gitlab-ctl restart，并第一时间复核日志。
• 变更后：若异常，优先回滚最近变更或版本；无法快速恢复时，利用备份恢复至稳定点。