Debian 上 GitLab 常见错误的排查与修复
一、快速定位与通用修复
- 查看组件与服务状态：运行 gitlab-ctl status；异常时使用 gitlab-ctl restart 重启；修改配置后执行 gitlab-ctl reconfigure 使配置生效。
- 集中查看日志：实时跟踪 tail -f /var/log/gitlab/gitlab-ctl/production.log；应用层错误可查 /var/log/gitlab/gitlab-rails/production.log 与 /var/log/gitlab/gitlab-shell/gitlab-shell.log。
- 检查系统资源与系统日志：用 top 观察 CPU/内存/磁盘，用 tail -f /var/log/syslog、dmesg、journalctl 定位系统级报错。
- 网络与防火墙：确认服务器可访问外网（如 ping），并放通 80/443（如使用 ufw allow 80,443）。
- 变更前务必备份重要数据与配置。
二、高频错误与对应处理
| 症状 |
可能原因 |
快速修复 |
| APT 安装/更新报 GPG 签名错误（如：repomd.xml GPG signature verification error: Bad GPG signature） |
仓库公钥过期或未正确导入 |
若使用 signed-by：在 /etc/apt/sources.list.d/gitlab_gitlab-?e.list 中找到对应公钥文件路径，执行：curl -s “https://packages.gitlab.com/gpg.key” |
| 访问 GitLab 出现 502 |
80/443 端口被占用、服务未就绪、内存不足 |
检查端口占用（如 ss -ltnp |
| 页面无法访问或配置不生效 |
external_url 配置错误、配置未生效 |
编辑 /etc/gitlab/gitlab.rb，确保 external_url ‘http://服务器IP或域名’ 正确；执行 gitlab-ctl reconfigure 并重启 |
| 推送被拒（non-fast-forward） |
本地非快进、远端有更新 |
先 git pull --rebase 或合并后再推送；必要时使用 git push --force-with-lease（谨慎） |
三、升级与仓库密钥更新
- 升级前准备：备份数据与配置，确保磁盘空间充足，执行 sudo apt update && sudo apt upgrade 保持系统包最新。
- 更新仓库签名密钥（适用于 Debian 的两种 APT 公钥管理方式）：
- 使用 signed-by 的源：
awk ‘/deb [signed-by=/{ pubkey = $2; sub(/[signed-by=/, “”, pubkey); sub(/]$/, “”, pubkey); print pubkey }’ /etc/apt/sources.list.d/gitlab_gitlab-?e.list | \
while read line; do curl -s “https://packages.gitlab.com/gpg.key” | gpg --dearmor > “$line”; done
- 使用 apt-key 的源：
apt-key del 3F01618A51312F3F
curl -s “https://packages.gitlab.com/gpg.key” | apt-key add -
- 完成后执行 apt update 验证仓库元数据可正常获取。
四、仍未解决时的建议
- 复核关键配置与端口：确认 /etc/gitlab/gitlab.rb 中 external_url 与端口设置正确，且 80/443 未被其他进程占用。
- 复核资源与时区：检查 内存/磁盘 使用，确保时间与时区正确，避免因资源紧张或时间漂移引发异常。
- 查阅官方文档与社区支持，并在操作前做好完整备份。