Linux环境下 GitLab 常见问题与解决
一 安装与依赖问题
- 依赖缺失或版本不匹配：在 CentOS/RHEL 上，常见报错如需要 policycoreutils-python（EL7）或 policycoreutils-python-utils（EL8）。安装对应依赖后重试安装或重配置：sudo yum install -y policycoreutils-python 或 policycoreutils-python-utils。若使用 RPM 离线安装，注意选择与系统版本匹配的 el7/el8 包。
- 配置生效与卡住：修改 /etc/gitlab/gitlab.rb 后必须执行 sudo gitlab-ctl reconfigure 使配置落地；若长时间卡在 ruby_block[supervise_redis_sleep]，可先 sudo systemctl restart gitlab-runsvdir 再执行 reconfigure。
- 资源建议：至少分配 4GB 内存，低于该值易出现启动缓慢或失败。
二 配置与端口冲突
- external_url 未设置或错误：导致页面无法访问或重定向异常。请在 /etc/gitlab/gitlab.rb 中正确设置 external_url（如 http://服务器IP 或域名），然后执行 sudo gitlab-ctl reconfigure。
- 端口被占用：默认 80/443/8080 可能被占用。用 ss -tulpen | grep -E ‘(:80|:443|:8080)’ 或 lsof -i:端口 查找占用进程并停用或调整 GitLab 端口；修改 gitlab.rb 后再次 reconfigure。
- 防火墙/SELinux：开放必要端口（如 firewall-cmd --permanent --add-service=http --add-service=https && firewall-cmd --reload）；若启用 SELinux，可用 sestatus 检查状态，必要时执行 sudo semanage fcontext -a -t httpd_sys_rw_content_t “/var/log/gitlab(/.*)?” && sudo restorecon -Rv /var/log/gitlab。
三 服务异常与 502/500 错误
- 服务未就绪或组件异常：执行 sudo gitlab-ctl status 查看各组件（如 nginx、puma/unicorn、gitaly、postgresql 等）状态；若异常，先 sudo gitlab-ctl restart，仍未恢复则查看日志定位。
- 502 Bad Gateway：常见于上游服务未启动或端口冲突。检查 nginx 与 puma/unicorn 是否运行、端口是否一致；必要时重新 reconfigure 并重启服务。
- 500 内部服务器错误：查看 /var/log/gitlab/gitlab-rails/production.log 获取堆栈与具体报错，按日志提示修复（如权限、配置、数据库等）。
四 网络连通与 SSH 认证
- 无法访问实例：先 ping 测试连通性，使用 nslookup/dig 检查 DNS 解析；确认云厂商安全组/本机防火墙已放行 80/443（或自定义端口）。
- git clone 报错：
- “Connection refused”：多为 URL 端口或协议错误（http/https/ssh），或端口未放行；修正 external_url 与客户端命令。
- SSH 认证失败：确认本地 SSH 密钥已生成并添加到 GitLab 用户 SSH Keys；如使用非默认端口，客户端需 -p 指定端口。
五 性能与资源优化
- 资源不足导致卡顿或 OOM：用 top/htop 观察 CPU/内存/IO，关闭不必要进程；内存紧张时启用 swap 分区，并适当调整内核参数（如 vm.swappiness）。
- 访问慢或偶发 502：增加可用内存、优化 GitLab 并发与缓存配置，定期清理构建产物与缓存；必要时横向扩容或分离高负载组件。
- 大文件场景：启用 Git LFS 管理大文件，避免仓库膨胀与内存压力。
如需，我可以按你的系统版本与 GitLab 版本提供对应的命令清单与配置片段。