GitLab Linux配置中常见的错误及解决方法

GitLab Linux配置常见错误与排查清单

一 安装与配置阶段

• 依赖安装失败：网络不稳定或包名错误会导致安装中断。建议使用稳定网络、核对包名，必要时切换到国内镜像源后重试安装。
• 配置文件语法或参数错误：编辑 /etc/gitlab/gitlab.rb 后未校验语法或写入了错误项，服务可能起不来。修改后先本地语法检查，再执行 gitlab-ctl reconfigure 使配置生效。
• external_url 未设置或设置不当：未正确配置 external_url 会导致实例无法通过域名或外网访问。请在 gitlab.rb 中明确设置如 external_url ‘http://gitlab.example.com’ 或 https://…，随后执行 gitlab-ctl reconfigure。
• 端口冲突：默认 80/8080 等端口被占用会引发访问异常。修改 gitlab.rb 中的端口（如改为 8081/8443），并确保防火墙放行对应端口。
• 邮件服务未就绪：未安装或未启动 Postfix 等 MTA 会导致通知邮件发送失败。安装并启用 Postfix，确保系统可对外发信。

二 访问与网络连通性

• 防火墙阻断：未放行 HTTP/HTTPS/SSH 会被防火墙拦截。按需放行：
  • firewalld（CentOS/RHEL）：firewall-cmd --permanent --add-service=http --add-service=https && firewall-cmd --reload
  • ufw（Debian/Ubuntu）：ufw allow 80,443,22 && ufw reload
• 端口未监听或被占用：访问返回连接被拒绝或超时。检查端口占用（ss -tulpen | grep -E ‘80|443|8080’），释放或更换端口后重启服务。
• 外部 URL 与实际访问方式不一致：例如仅配置了 HTTP 却用 HTTPS 访问，或反向代理未正确设置 X-Forwarded-Proto。统一 external_url 与访问协议，并在反向代理正确设置头部。
• DNS 解析失败：域名无法解析导致访问异常。使用 nslookup/dig 检查解析是否正确，必要时更换 DNS 或修正本地解析配置。
• 502/504 网关错误：常见于上游服务未就绪或反向代理配置错误。检查 Nginx/Puma/Unicorn/Gitaly 等组件状态与日志，修正代理配置后重启相关服务。

三 权限与认证问题

• 文件系统权限错误：数据或日志目录属主/权限不当会出现 Permission denied。将 /var/opt/gitlab 等目录属主设为 git:git，权限 755；变更后执行 gitlab-ctl reconfigure。
• SSH 密钥与权限：客户端私钥权限应为 600；公钥需正确添加到用户账户的 SSH Keys。克隆/推送报认证失败先核对密钥与远程 URL（git@ 或 https://）。
• SELinux/AppArmor 限制：安全模块策略不当会阻止 GitLab 访问文件或端口。按需为相关目录设置正确的 SELinux 上下文，或将 AppArmor 调整为投诉模式进行排障。
• Runner 不可用：注册 Runner 的 Token 错误或 Runner 服务未启动会导致作业卡住。检查 Runner 状态、重新注册并更新配置后重启 Runner。

四 数据库与性能问题

• 数据库未就绪或连接失败：PostgreSQL 等服务未启动或连接参数错误会导致实例异常。使用 gitlab-ctl status 检查服务状态，确认数据库运行且连接配置正确。
• 资源不足导致卡顿或 502：内存/CPU/IO 资源紧张会引发访问慢或网关错误。使用 top/htop 定位高占用进程，必要时增加内存、启用 swap、使用 SSD、优化并发与缓存参数。
• 大文件操作内存不足：推送/拉取大文件易触发 OOM。启用 Git LFS 管理大文件，或提升服务器内存配置。
• 配置不当引发性能劣化：如并发进程数、数据库缓存设置不合理。结合硬件与负载调整相关参数，定期清理构建产物与缓存。

五 快速排查命令与日志定位

• 服务状态与重启：
  • 查看整体状态：gitlab-ctl status
  • 重新配置并重启：gitlab-ctl reconfigure && gitlab-ctl restart
• 日志定位：
  • 控制台实时日志：tail -f /var/log/gitlab/gitlab-ctl/production.log
  • Rails 应用日志：tail -f /var/log/gitlab/gitlab-rails/production.log
• 配置一致性检查：gitlab-rake gitlab:check SANITIZE=true --trace
• 组件状态细化：gitlab-ctl status nginx gitaly puma unicorn postgresql