Ubuntu 上 GitLab 使用常见问题与排查
一 安装与初始化
- 建议使用 Ubuntu 18.04/20.04/22.04，至少 4GB 内存（低于 4GB 也能运行但会明显变慢）。安装依赖：sudo apt-get install -y curl openssh-server ca-certificates tzdata perl；如需要邮件功能，安装并启用 Postfix。添加仓库并安装：curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash，然后 sudo apt-get install gitlab-ce。首次访问 http://服务器IP或域名 设置管理员密码；也可在 /etc/gitlab/initial_root_password 查看自动生成的初始 root 密码（首次安装后 24 小时内有效）。修改 /etc/gitlab/gitlab.rb 后需执行 sudo gitlab-ctl reconfigure 使配置生效。
二 访问与端口冲突
- 访问出现 502/504：常见于资源不足或端口冲突。GitLab 组件（如 Unicorn/Puma、Nginx、Sidekiq）未完全启动或反向代理/本机服务占用了 80/443/8080 等端口。处理步骤：执行 sudo gitlab-ctl status 查看组件状态；sudo gitlab-ctl tail 查看错误日志；必要时调整 /etc/gitlab/gitlab.rb 中的 external_url 与内部服务端口并重跑 reconfigure。若本机已有 Tomcat/Jenkins 占用 8080，可在 gitlab.rb 中修改 Unicorn/Puma 端口（如改为 9090）后 reconfigure。外部访问需放行 80/443/22（UFW：sudo ufw allow 80,443,22/tcp；firewalld：sudo firewall-cmd --permanent --add-service=http --add-service=https --add-service=ssh && sudo firewall-cmd --reload）。
三 备份与恢复
- 备份：编辑 /etc/gitlab/gitlab.rb 设置 gitlab_rails[‘backup_path’]（可选），执行 sudo gitlab-ctl reconfigure 后，创建备份：sudo gitlab-rake gitlab:backup:create。恢复：先停写（sudo gitlab-ctl stop unicorn/puma 或整个实例），执行 sudo gitlab-rake gitlab:backup:restore BACKUP=时间戳（文件名即时间戳），恢复完成后再启动。注意：备份仅包含仓库与数据库等核心数据，通常不包含 /etc/gitlab/gitlab.rb 与 /var/opt/gitlab/ssl 等配置与证书，需手动备份；跨版本恢复需谨慎，尽量使用同版本或按官方升级路径执行。
四 用户与权限 邮件与 SSH
- 管理员密码：首次登录强制修改；如忘记，可在控制台重置：sudo gitlab-rails console production，执行 user = User.where(id: 1).first; user.password = ‘新密码’; user.password_confirmation = ‘新密码’; user.save!。邮件通知：在 /etc/gitlab/gitlab.rb 启用并配置 SMTP（如 gitlab_rails[‘smtp_enable’] = true、smtp_address/smtp_port/smtp_user_name/smtp_password/smtp_domain 等），保存后 reconfigure。SSH 克隆：本地生成密钥（ssh-keygen -t rsa -C “邮箱”），将 ~/.ssh/id_rsa.pub 内容添加到 GitLab 用户 SSH Keys；若使用非默认端口或自签证书，客户端需相应配置。权限问题：项目 Access Level（Guest/Reporter/Developer/Maintainer/Owner）与 Protected Branch 策略决定推送/合并权限，按团队流程在 UI 或 API 中配置。
五 升级与迁移 性能优化
- 升级：建议先在测试环境验证，按 小版本→大版本 逐步升级；执行 sudo apt-get update && sudo apt-get install gitlab-ce，随后 sudo gitlab-ctl reconfigure。跨大版本升级前务必完整备份并阅读官方变更说明。迁移：在源站执行备份（gitlab-rake gitlab:backup:create），将备份文件与 gitlab.rb/gitlab-secrets.json 复制到目标服务器，在目标站先安装同版本 GitLab，恢复备份后 reconfigure 并启动。性能优化：为 4–8GB 内存实例可适当调整 unicorn[‘worker_processes’]、sidekiq[‘concurrency’]；启用 gzip 压缩、使用 Nginx/Let’s Encrypt 提供 HTTPS、将仓库存储与数据库分离到更快的磁盘；定期清理无用仓库与制品、监控磁盘与 I/O。