GitLab如何在Linux上进行故障排查 - 问答

Linux 上 GitLab 故障排查实战手册

一快速定位流程

检查运行状态与组件健康：执行 sudo gitlab-ctl status，确认关键组件（如 nginx、puma/unicorn、sidekiq、gitaly、postgresql、redis）均为 run。若异常，优先查看对应日志。
查看实时日志：使用 sudo gitlab-ctl tail 观察全局日志，或指定组件如 sudo gitlab-ctl tail gitlab-rails、sudo gitlab-ctl tail nginx/gitlab_error.log；定位错误关键词如 ERROR、FATAL、PG::Error、permission denied。
系统资源与连通性自检：
- 资源：free -m、df -h、top/htop 检查内存、磁盘、CPU 是否瓶颈。
- 端口：ss -plnt | grep -E ‘(:80|:443|:22)’ 或 lsof -i :80 排查端口占用与冲突。
- 网络与 DNS：ping、dig +short、nslookup、traceroute 验证域名解析与链路可达。
配置与生效：修改 /etc/gitlab/gitlab.rb 后执行 sudo gitlab-ctl reconfigure，必要时 sudo gitlab-ctl restart 使配置生效。
防火墙与安全策略：开放 80/443/22（或自定义端口），在 CentOS 上确认 firewalld 规则；若启用 SELinux，使用 sestatus 检查状态并按需调整策略。
版本与升级兼容性：通过 /help 页面或 API 获取版本，排查升级后的兼容性问题。

二常见症状与处理对照表

症状	快速检查	处理要点
访问返回 502/504	gitlab-ctl status；ss -plnt 检查 80/443；tail gitlab-rails/production.log 与 nginx/gitlab_error.log	常见为上游未就绪（如 puma/unicorn、gitaly、sidekiq 异常）或端口冲突；重启异常组件，必要时 reconfigure；排查 Nginx 与上游超时配置
页面 500 错误	tail -f /var/log/gitlab/gitlab-rails/production.log	依据日志定位异常（如 DB 连接、权限、迁移失败）；修复根因后重启服务
SSH 克隆失败（Permission denied/Authentication failed）	检查本机 ~/.ssh/id_rsa.pub 是否已添加至用户 SSH Keys；测试 ssh -T git@your_domain	确认使用正确的 SSH 端口（默认 22 或自定义）；确保服务器 authorized_keys 与权限正确
安装/依赖错误	观察安装日志；检查 curl、policycoreutils、openssh-server 等依赖	补齐依赖；离线安装核对版本与仓库；修正仓库源后重试
配置文件错误导致无法启动	gitlab-ctl reconfigure 报错；检查 /etc/gitlab/gitlab.rb 语法与参数	修正语法/参数；reconfigure 后再启动
资源不足（卡顿/OOM）	free -m、df -h、top/htop	增加内存或启用 swap；优化并发与缓存；清理无用仓库/构建产物
端口冲突（80/443 被占用）	lsof -i :80 或 ss -plnt	停止占用进程或调整 GitLab 端口；reconfigure 并重启
邮件发送失败	检查 gitlab.rb 中 smtp_enable 等参数；查看邮件日志	修正 SMTP 配置与发信域名；确保邮件服务可达与认证正确

三日志与系统诊断命令清单

组件与日志：
- 全局与组件日志：sudo gitlab-ctl tail，sudo gitlab-ctl tail gitlab-rails，sudo gitlab-ctl tail nginx/gitlab_error.log
- 直接查看文件：/var/log/gitlab/ 下的 gitlab-rails/production.log、gitlab-rails/production_json.log、sidekiq/current、gitaly/current、nginx/gitlab_access.log、nginx/gitlab_error.log
系统与服务日志：
- systemd：sudo journalctl -u gitlab、sudo journalctl -u gitlab-rails、sudo journalctl --since “2025-12-01” --until “2025-12-10”
资源与进程：
- 资源：free -m、df -h、du -hd 1
- 进程：top/htop、ps aux | grep puma
网络与端口：
- 监听与占用：ss -plnt、lsof -i :80
- 连通与解析：ping、dig +short、nslookup、traceroute、ip address
深入诊断（慎用）：
- 系统调用跟踪：strace -tt -T -f -y -yy -s 1024 -p （生产环境谨慎，可能影响性能）

四系统与安全配置检查

防火墙放行：确保 firewalld/iptables 已放行 80/443/22（或自定义端口），避免外部访问被拒。
SELinux（CentOS 常见）：
- 检查状态：sestatus
- 目录上下文与恢复：sudo semanage fcontext -a -t httpd_sys_rw_content_t “/var/log/gitlab(/.*)?”，sudo restorecon -Rv /var/log/gitlab
资源与内核参数：
- 内存压力可临时启用 swap；必要时优化 vm.swappiness 等内核参数，缓解 OOM 与抖动。
权限与目录：
- 确认 /var/opt/gitlab、/var/log/gitlab 等目录属主为 git:git，权限合理（如 755/644），避免因权限导致写入失败。

五数据一致性与恢复建议

配置变更流程：修改 /etc/gitlab/gitlab.rb → sudo gitlab-ctl reconfigure → sudo gitlab-ctl restart，变更前建议备份配置与数据。
备份与恢复：定期执行 gitlab-backup create 进行备份；恢复时先确保实例版本一致、数据目录与数据库状态一致，再执行恢复流程。
数据库与后台任务：
- 检查数据库状态：gitlab-ctl status postgresql；必要时在维护窗口重启。
- 观察后台任务：sudo gitlab-ctl tail sidekiq，异常任务重试或清理卡死任务。
升级与兼容性：跨版本升级遵循官方路径，先小版本过渡并充分备份，验证插件/Runner/存储兼容性。

0 赞

0 踩