Debian 下 GitLab 常见问题与排查清单
一 环境要求与快速自检
- 系统建议：使用 Debian 10（Buster）及以上稳定版本。硬件建议至少 2GB 内存（推荐 4GB+）、20GB+ 磁盘空间，以避免 OOM 和磁盘告警。
- 基础依赖：确保安装 curl、openssh-server、ca-certificates、tzdata、postfix（邮件通知）。
- 首次安装要点：编辑 /etc/gitlab/gitlab.rb 设置 external_url（包含协议与域名/IP），执行 sudo gitlab-ctl reconfigure 应用配置，随后 sudo gitlab-ctl start 启动服务。
- 访问与端口：确认防火墙放行 80/443（以及自定义端口），浏览器访问 external_url 验证。
- 服务状态：使用 sudo gitlab-ctl status 检查组件是否全部为 run 状态。
二 高频故障与处理步骤
- 502 Bad Gateway
- 检查组件状态：sudo gitlab-ctl status，异常则 sudo gitlab-ctl restart。
- 检查端口占用：sudo netstat -tulnp | grep ‘:80|:443’，释放冲突进程或修改 /etc/gitlab/gitlab.rb 中的 nginx[‘listen_port’] 后 reconfigure。
- 内存不足：创建 2GB 交换分区（示例）：
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo ‘/swapfile none swap sw 0 0’ | sudo tee -a /etc/fstab
- 配置文件错误
- 语法校验：sudo gitlab-ctl configtest；修正 /etc/gitlab/gitlab.rb 后执行 sudo gitlab-ctl reconfigure。
- 重点核对 external_url 协议与地址格式（如 http:// 或 https://）。
- 内存不足导致崩溃或卡顿
- 启用 swap（见上），并降低并发：
unicorn[‘worker_processes’] = 2
sidekiq[‘concurrency’] = 10
- 邮件发送失败
- 检查 SMTP 配置（示例为 163 邮箱）：
gitlab_rails[‘smtp_enable’] = true
gitlab_rails[‘smtp_address’] = “smtp.163.com”
gitlab_rails[‘smtp_port’] = 25
gitlab_rails[‘smtp_user_name’] = “your-email@163.com”
gitlab_rails[‘smtp_password’] = “your-email-password”
gitlab_rails[‘smtp_domain’] = “163.com”
gitlab_rails[‘smtp_authentication’] = “login”
gitlab_rails[‘smtp_enable_starttls_auto’] = true
gitlab_rails[‘smtp_tls’] = false
gitlab_rails[‘gitlab_email_from’] = “your-email@163.com”
- 重启服务并测试：sudo systemctl restart postfix；sudo gitlab-ctl restart；在控制台执行
sudo gitlab-rails console
Notify.test_email(‘recipient@example.com’, ‘Test Subject’, ‘Test Body’).deliver_now
- 升级失败或数据损坏
- 升级前备份：sudo gitlab-backup create（默认保存至 /var/opt/gitlab/backups）。
- 按官方路径逐级升级，避免跨大版本；恢复示例：
sudo gitlab-backup restore BACKUP=
sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart
- SSH 推送/拉取错误
- rejected non-fast-forward：先同步远端再推送
git fetch origin
git merge origin/main
git push origin main
- failed to push some refs：核对远端地址与权限，确认 SSH 公钥已添加至 GitLab。
三 日志定位与常用命令
- 组件与服务日志：
- 实时查看全部组件：sudo gitlab-ctl tail
- 指定组件日志：如 sudo tail -f /var/log/gitlab/unicorn/stdout.log
- 应用错误细节：/var/log/gitlab/gitlab-rails/production.log
- 系统与内核日志：tail -f /var/log/syslog、journalctl、dmesg
- 资源与进程：top/htop、ps aux
- 网络与端口：ping、netstat -tulnp | grep ‘:80|:443’
- GitLab 管理：sudo gitlab-ctl status/restart/reconfigure
四 预防性维护与优化
- 备份策略：定期执行 sudo gitlab-backup create，妥善保存 /var/opt/gitlab/backups 的备份文件，升级或迁移前务必验证可恢复性。
- 升级路径：遵循官方升级指南，按序升级中间版本，严禁跨多版本跳跃。
- 性能与资源：为小内存实例启用 swap，并适当降低 unicorn/sidekiq 并发；监控 CPU/内存/磁盘 IO。
- 安全与合规：使用 HTTPS/Let’s Encrypt 证书，限制对外暴露端口，定期更新系统与 GitLab 包。
