1.1 适用场景#

以下三种场景适用本指南的方法：

忘记 root 管理员密码

部署 GitLab 后长期未登录，root 密码已遗忘，无法通过 Web UI 进入管理后台。这是最常见的触发场景。

首次部署后初始密码未生效

GitLab 容器启动时，系统会生成一个随机初始密码并存储在 /etc/gitlab/initial_root_password 文件中。该文件在首次登录成功 24 小时后自动删除。如果未及时查看该文件，或文件已被清理，则无法获取初始密码。

未配置 SMTP 邮件服务

GitLab 的”忘记密码”功能依赖 SMTP 邮件服务发送重置链接。如果部署时未配置 SMTP，用户无法通过邮件自助找回密码。此时 Rails 控制台是唯一可行的恢复路径。

1.2 风险警告#

Rails 控制台执行密码重置是在数据库层面进行直接写入操作。这一过程绕过 ActiveRecord 模型层的所有验证回调和安全策略，可能带来的风险包括：

• 数据完整性风险：user.save! 会正常触发 ActiveRecord 回调（包括 before_save、after_save 等），意味着 GitLab 在用户保存时配置的审计或同步逻辑都会被执行。
• 误操作风险：在控制台中若操作了错误的用户对象（如误修改其他管理员账号），可能导致其密码被覆盖而无法登录。
• 审计不可追溯：控制台操作不会记录到 GitLab 的审计日志中，生产环境下可能需要额外的操作记录。

操作前务必对容器数据卷做一次快照或备份。 这是回滚的唯一途径。

2.1 确认容器名称或 ID#

首先定位 GitLab 容器：

1
docker ps | grep gitlab

输出示例：

1
abc123def456   gitlab/gitlab-ce:16.0.0   "/assets/wrapper"   2 weeks ago   Up 7 days   22/tcp, 80/tcp, 443/tcp   0.0.0.0:8080->80/tcp   gitlab

记下容器名称（此处为 gitlab）或容器 ID（abc123def456）。后续命令将使用容器名称。

如果 docker ps 未显示任何 GitLab 容器，执行 docker ps -a 检查容器是否处于停止状态。若容器已停止，先执行 docker start <容器名> 启动它。

2.2 可选：创建数据卷快照#

在生产环境中，强烈建议在操作前备份数据卷。以下命令创建当前数据卷的压缩快照：

1
docker run --rm \
2
  -v gitlab_data:/data:ro \
3
  -v $(pwd):/backup \
4
  alpine \
5
  tar czf /backup/gitlab-data-backup-$(date +%Y%m%d-%H%M%S).tar.gz -C /data .

说明：

• gitlab_data：替换为实际的 GitLab 数据卷名称，通过 docker volume ls | grep gitlab 确认。
• -v gitlab_data:/data:ro：以只读模式挂载数据卷，防止备份过程意外写入。
• $(pwd):/backup：将当前目录挂载为备份输出路径。
• $(date +%Y%m%d-%H%M%S)：为备份文件添加时间戳，便于区分多个快照。

数据卷名称不确定时，使用以下命令列出所有数据卷并定位 GitLab 相关的卷：

1
docker volume ls | grep gitlab

3.1 进入容器 Shell#

以交互模式进入 GitLab 容器的 bash：

1
docker exec -it gitlab bash

注意：如果容器名不是 gitlab，替换为第 2.1 步确认的实际名称或 ID。

3.2 启动 Rails 控制台#

在容器内执行：

1
gitlab-rails console -e production

-e production 显式指定生产环境。此命令加载整个 Rails 应用栈，可能需要 10 到 30 秒，取决于服务器性能。成功进入后，提示符变为：

1
irb(main):001:0>

3.3 查找 root 用户#

推荐方式：按用户名查找

1
user = User.find_by(username: 'root')

此方法直接定位 root 用户，一行完成，绝大多数场景下足够。

备选方式：查找所有管理员后手动确认

如果 find_by(username: 'root') 返回 nil（例如 root 用户名被修改），则列出所有管理员账号：

1
admins = User.admins
2
admins.each { |u| puts "#{u.id}: #{u.username} (#{u.email})" }

从输出中确认目标用户后，按 ID 加载：

1
user = User.find(<目标ID>)

3.4 确认用户身份#

在继续操作前，务必确认当前操作的确实是目标用户：

1
puts "当前操作用户: #{user.username}, ID: #{user.id}, Email: #{user.email}"

如果输出显示的用户名和 ID 与预期不符，回到上一步重新定位。

4.1 密码强度要求#

GitLab 默认密码策略要求：

• 最小长度：8 位
• 不能与用户名相同
• 某些版本（15.x+）默认要求密码不能是常见弱密码

如果密码不符合要求，user.save! 将抛出验证错误。

4.2 设置新密码#

1
user.password = 'YourNewSecurePass123!@#'
2
user.password_confirmation = 'YourNewSecurePass123!@#'

password_confirmation 必须与 password 完全一致，否则保存失败。

4.3 保存并验证#

1
user.save!

save!（带感叹号）在验证失败时直接抛出异常，便于立即发现问题。静默的 save 方法可能返回 false 而不提示原因。

然后验证密码是否生效：

1
puts "密码重置成功" if user.valid_password?('YourNewSecurePass123!@#')

输出 密码重置成功 确认密码已正确写入数据库且可被 GitLab 认证系统识别。

4.4 退出控制台#

1
exit

退出 Rails 控制台后，再输入 exit 退出容器 Shell，回到宿主机终端。

5.1 Web UI 登录验证#

在浏览器中打开 GitLab 登录页面，使用以下凭据登录：

• 用户名：root
• 密码：第 4.2 步设置的新密码

如果登录失败，检查：

• 密码是否包含特殊字符导致的输入错误（建议复制粘贴测试一次）
• 用户是否被锁定（多次失败登录可能触发临时锁定）
• 确认操作的是正确的 GitLab 实例（多实例部署时）

5.2 检查管理员权限#

登录成功后，确认管理员权限是否完整：

1. 查看顶部导航栏是否有扳手图标（Admin Area 入口）。
2. 进入 Admin Area，检查是否能访问用户管理、项目管理、系统设置等模块。
3. 尝试进入 /admin/users，确认能查看所有用户列表。

如果没有 Admin Area 入口，说明当前用户不是管理员——回到第 3.3 步，使用 User.admins 重新确认目标用户。

5.3 清理 bash 历史（可选安全措施）#

密码可能在 shell 历史中留下痕迹。建议清理：

1
history -c && rm -f ~/.bash_history

注意：此命令在容器内执行。此外，第 4.2 步中 Ruby 变量 user.password 不会出现在 bash 历史中，但如果在 bash 中执行过 echo 或使用过包含密码的命令，则需要清理。

找不到 GitLab 容器#

1
docker ps -a | grep gitlab

如果容器存在但处于 Exited 状态，启动它：

1
docker start gitlab

等待 1-2 分钟让 GitLab 服务完全启动后，再执行进入操作。

gitlab-rails 命令不存在#

1
bash: gitlab-rails: command not found

可能原因：

• 进入了错误的容器：确认当前 shell 提示符对应的容器名称。在宿主机上重新执行 docker exec -it <容器名> bash。
• GitLab 容器镜像类型不匹配：gitlab/gitlab-ce 和 gitlab/gitlab-ee 的目录结构相同，命令应存在。如果是基于 Omnibus 包自定义构建的镜像，命令路径可能在 /opt/gitlab/bin/gitlab-rails。

user.save! 报错#

1
ActiveRecord::RecordInvalid: Validation failed: Password is too short (minimum is 8 characters)

密码长度不足 8 位，使用更长密码后重试。

1
ActiveRecord::RecordInvalid: Validation failed: Password must not be a commonly used password

GitLab 15.x+ 内置弱密码黑名单，换用更复杂的密码组合。

如果密码确实无法通过验证且急需登录，可以临时绕过验证（不推荐）：

1
user.password = 'tempPass123!@#'
2
user.password_confirmation = 'tempPass123!@#'
3
user.save!(validate: false)

注意：validate: false 跳过所有 ActiveRecord 验证，仅在确认密码强度足够但因版本策略无法通过时使用。登录后立即在 Web UI 中修改为合规密码。

登录后无 Admin Area#

说明当前用户不是管理员。回到 Rails 控制台：

1
User.admins.each { |u| puts "#{u.id}: #{u.username} (#{u.email})" }

如果 root 用户不在管理员列表中，手动提升权限：

1
user = User.find_by(username: 'root')
2
user.admin = true
3
user.save!

然后重新登录，Admin Area 应该出现。