企业官网建设流程全解析

gitlab two-factor authentication 完整避坑指南：开启之后，开发工作流怎么调才不炸

两个星期前我们组一个开发小哥的 GitLab 账号被撞库了，攻击者拿到密码之后直接把私有仓库克隆了个遍，还在仓库里插了挖矿脚本的 commit。万幸的是他还没开双因素认证，账号一旦绑定 two-factor authentication，就算密码泄露几天，攻击者大概率也进不来。从那天起我把项目组所有成员账号都强推了 2FA，折腾完 Web 端登录之后，又引出 SSH、HTTPS 拉代码、CI/CD Runner、IDE 提交等一系列连锁问题。

这篇文章就是基于我这次“全量开通 GitLab two-factor authentication”的实操过程写出来的。内容覆盖 2FA 原理、启用流程、认证工具选型、开启后开发工作流的适配，以及我在 Docker 自建 GitLab 里踩过的恢复坑。文中的步骤和代码都是我在真实环境里跑过的，适合刚把 2FA 提上日程的团队，也适合被 2FA 锁在门外正在找恢复方法的同学。

1. 为什么 GitLab 必须开双因素认证

1.1 代码仓库失守的代价

聊 2FA 之前，先说结论：GitLab 账号本质上是你整个软件供应链的钥匙。里面不只有源码，还有 CI/CD 流水线配置、部署密钥、容器镜像仓库的推送权限、环境变量里的数据库密码和云服务密钥。一个账号被拿，轻则私有代码泄露，重则攻击者通过修改.gitlab-ci.yml实现供应链投毒，把恶意代码直接送进生产环境。

GitLab 官方也很清楚这个风险，所以在账号安全设置里把 two-factor authentication 直接放在显眼位置。安全事故统计里，“凭证泄露 + 弱密码复用”始终占第一梯队。密码可以靠撞库拿到，但第二因素（手机里的动态验证码、恢复码、硬件 key）是攻击者没法远程偷走的东西。

1.2 双因素认证到底验证了什么

双因素认证的核心是“三样东西”：你知道的（密码）、你拥有的（手机/硬件 key）、你本身的（指纹/人脸）。GitLab 的 2FA 走的是 TOTP（Time-based One-Time Password）协议，也就是基于时间的动态口令——认证器和服务器各自持有一个共享密钥，以当前 Unix 时间戳为输入，每 30 秒生成一组 6 位数验证码。两端算法一致、时间一致，验证码就一致，所以常见的验证失败原因基本都是手机时间与服务器时间偏差过大。

GitLab 启用 2FA 后并非只保护网页登录，它实际防守的入口很广：

• Web 界面登录、登出、密码重置
• 使用账号密码通过 HTTPS 方式执行 Git 操作（git fetch、git push）
• 通过 GraphQL API 或 REST API 以账号密码换取 token
• 管理员后台的关键操作二次确认

这条必须提前理解：GitLab 的 2FA 不直接拦截 SSH 协议，因为 SSH 走的是公钥认证，包里根本没有密码。很多人开完 2FA 后发现 SSH 照样能拉代码，就误以为 2FA 没生效，其实是机制不同。

1.3 一个被忽略的“账户锁定”场景

开了 2FA 之后，密码泄露的生存窗口会大大缩短，但前提是你没有把恢复码落在攻击者手里。GitLab 在绑定 2FA 时会一次性生成一串恢复码（recovery codes），每个恢复码只能使用一次，用于手机丢失、认证器数据被清空时重新登录。我见过太多人把恢复码截图丢在聊天软件里，或者干脆顺手复制到桌面 txt 就忘了删。

还有个细节：GitLab 允许同时启用 TOTP 应用和 WebAuthn 硬件安全密钥，两者可以并存。恢复码是最后的逃生通道，这些手段不冲突，建议有条件都开。硬件 key 的好处是防钓鱼能力比普通 TOTP 强得多，但很多团队嫌成本高，至少把 TOTP + 恢复码做扎实。

2. 在 GitLab 上启用双因素认证的完整流程

2.1 启用前的必要准备

先别急着点“开启”，准备工作做足能省掉后面一大半的麻烦。第一步是确认账号邮箱可访问，因为开启 2FA 以及后续找回流程都会往邮箱发通知。第二步是准备一个支持 TOTP 的认证工具，手机上装 Google Authenticator、Microsoft Authenticator、Authy、1Password 都行，或者浏览器装 Bitwarden、KeePassXC 这类扩展。

我个人建议优先用支持云同步的认证器（1Password、Bitwarden），因为换手机时不会把所有种子全丢。Google Authenticator 的换机迁移要手动扫码，很容易翻车，后面我会单独说这个问题。

注意：提前在 GitLab 里看一眼自己有哪些访问凭证。SSH key 不受影响，但如果你平时是用 HTTPS + 账号密码拉代码的，开完 2FA 之后密码方式会立刻失效，需要改用 Personal Access Token，这条很多人没注意，结果当场卡死。

2.2 一步步操作：绑定 TOTP 验证器

以 GitLab 15.x/16.x 社区版界面为例（SaaS 版一样），路径是：右上角头像 →Preferences（偏好设置）→ 左侧Account（账号）→ 找到Two-Factor Authentication区块，点击Enable Two-Factor Authentication。

这时候页面会展示一个大大的二维码，旁边是一串可以手动输入的 base32 密钥（通常以otpauth://totp/gitlab:yourname@domain?secret=XXX格式展示）。在认证器里扫码或者手动输入密钥，认证器就会开始滚动生成 6 位动态码。

GitLab 出于安全考虑，要求你连续输入两次动态码来确认你确实持有这个验证器。第一次验证码通过后，页面会立刻显示恢复码清单，同时要求输入第二次验证码完成绑定。这里要特别提醒：别急着把恢复码关了，先做三件事：

1. 把恢复码抄在纸质笔记本上，至少留一份不联网的备份
2. 用 Bitwarden 或者加密笔记里存一份电子版
3. 「不要」把恢复码截图发到聊天软件，GitLab 的恢复码清单只在绑定那一刻完整展示一次，之后不会给你看全文

恢复码一般给 10 个，每个只能用一次，格式是 16 位乱码字符。用掉一个之后剩余数量可以在 2FA 设置页看到，但不能反查明文。

2.3 开启后马上要做的验证

第一次开启 2FA 成功后先不要无脑高兴，退出账号，重新走一遍登录流程，用 TOTP 动态码登录一次，确认整个链路通了。登录时页面会先要求输入用户名密码，下一步再要求输入 6 位验证码。中间有个可选勾选“Trust this device”（信任此设备），信任之后这台设备 30 天内再登录就不用重复输验证码。

接着要比较坑的是：GitLab 不会自动把你“已登录”状态剔除，所以原会话仍然是有效的。如果你是在一台已经登录的机器上开的 2FA，账户安全状态实际上还是旧会话，要彻底安全必须主动点 Log out，清掉所有旧会话。

做完登录验证，再验证恢复码。方法简单：手机飞行模式模拟丢失设备场景，用恢复码登录一次。这一步不用真的把数据清掉，只要确认恢复码能登录即可。我用过 2FA 这么久，最大的感受是恢复码这东西 99% 的时间用不上，但一旦手机摔了、换机了，它就是唯一救命的钥匙。

3. 认证应用与浏览器扩展的选型对比

3.1 主流认证工具实测体验

GitLab 的提示语里有一句常见描述：enter the code from your two-factor authentication app or browser extension。很多人纠结到底用 App 还是浏览器扩展，我两种都长期用过，直接给结论：

• Google Authenticator：老牌、简单、离线可用，但它不支持多设备同步。换机迁移必须旧手机一个个扫码导出，账号多了非常痛苦。
• Microsoft Authenticator：支持云备份，界面对多账号管理比 Google 的舒服一点，GitLab 也能正常扫。
• Authy：支持多设备同步，但最近口碑有点下滑，备份机制也有过争议。不推荐新用户上车。
• 1Password / Bitwarden：本质是密码管理器附带 TOTP 功能，浏览器插件能自动检测 6 位码输入框并自动填充。团队里如果本来就在用密码管理器，用它的 2FA 功能最顺滑，我目前的主力方案就是这个。
• 浏览器扩展（如 Bitwarden 扩展、KeePassXC 浏览器集成）：优势是自动填充极度丝滑，不用掏手机。缺点是依赖浏览器环境和扩展数据同步，如果浏览器多账号隔离、或者开无痕模式，要注意扩展是否自动解锁。

3.2 多账号多 GitLab 实例怎么管理

开发同学手里一般不止一个 GitLab 账号：公司自建 GitLab、SaaS 版、客户方的 GitLab、可能还有 GitLab.com 上个人的私有仓库。每个账号的 2FA seed 都不同，如果都绑在同一个认证器里，账号一多会分不清哪个码对应哪个 GitLab。

我的做法是给每个 GitLab 实例的账号在认证器里单独命名，命名规则用GitLab-Prod-公司、GitLab-Personal、GitLab-CustomerA这种格式。扫码之后一定要立刻在认证器里顺便编辑条目名称，否则默认名称可能只是邮箱前缀，多个账号撞在一块完全分不清。

如果用的是 Bitwarden 或者 1Password，TOTP 种子直接存在对应登录条目里，自动填充时会自动填充正确账号的验证码，不需要记条目名，体验最好。

3.3 换手机与数据迁移的避坑建议

这条非常实用，务必看完。用 Google Authenticator 的老用户换手机时最常见的崩溃现场是：新手机扫码绑定发现账号列表是一片空白，旧手机早已被重置。Google Authenticator 的官方“转移账号”功能是用二维码把旧手机里的账号逐个导出，就算有导出二维码，也需要旧手机还能用。

所以我的建议是：

1. 能选支持云同步的认证器就尽量选支持云同步的
2. 在 GitLab 的恢复码还没用完的情况下，把恢复码留好，等新手机重新扫码绑定 GitLab 2FA 后，旧恢复码自动作废，新恢复码会重新生成
3. 如果所有认证器的 seed 都丢了、恢复码也没了，那就只剩管理员后台强解一条路（第 5 章有命令）

换完手机重新绑定后，记得在 GitLab 的 2FA 设置页里重新下载并保存新的恢复码，旧的恢复码在换绑成功后就没用了。

4. 开启 2FA 后，开发工作流的连锁适配

4.1 SSH 方式：基本不受影响，但要给 key 上锁

GitLab 的 2FA 属于“Web 登录会话侧的验证”，SSH 协议走的是公钥认证，不涉及密码和 TOTP。所以平时用 SSH 方式git fetch/push的人，开 2FA 之后基本无感。这一点既是便利也是风险：SSH key 一旦被拷走，就等于拿到了仓库的“长期免密通行证”。

我的建议是给本地 SSH key 加上 passphrase，用ssh-keygen -t ed25519 -C "your_email"生成时输入口令。配合ssh-agent后只需要每次输入一次口令，后续无需重复输入。这样哪怕 SSH private key 被偷，没有 passphrase 也用不了。

4.2 HTTPS 方式：账号密码当场失效，必须改用 Personal Access Token

开 2FA 最明显的转折点就在这里。之前用 HTTPS + 账号密码拉代码的人，开完 2FA 之后再用密码会直接报HTTP Basic: Access denied。GitLab 要求所有 HTTPS 方式的 Git 操作改用 Personal Access Token（PAT）作为密码。

创建路径：右上角头像 →Preferences→Access Tokens→ 填名称、选有效期、勾选read_repository和write_repository权限，生成后复制 token。这个 token 只显示一次，类似恢复码的性质，关掉页面就再也看不到明文。拿到 token 后在命令行里这样用：

git clone https://oauth2:YOUR_PERSONAL_ACCESS_TOKEN@gitlab.example.com/group/project.git

或者更稳妥的做法是配置 Git 凭据管理器，把 token 存进本机凭据存储，不用每次写 URL：

git config --global credential.helper store

但store是明文存 token，不推荐用在共享机器上。Linux 下推荐libsecret，macOS 下用系统钥匙串，Windows 下用 Git Credential Manager。

注意：创建 PAT 时权限别贪多，只需要read_repository就坚决不给write_repository。生产环境的 CI/CD 里用的 token 权限要更保守，最好用项目级的 deploy token，而不是个人 PAT。

4.3 IDE 提交：PyCharm、VS Code 与 IntelliJ 的配置调整

热词里有人搜“pycharm提交到gitlab”，正好说一下。PyCharm 里的 Git 集成有两种方式连 GitLab：SSH 或 HTTPS。开启 2FA 后，如果你之前用的是 HTTPS + 密码，需要换成 Personal Access Token：

PyCharm 操作路径：File → Settings → Version Control → Git → 选中 remote 地址。如果你是 HTTPS URL，在 Credentials 下拉里选择“Use credential helper”，并在首次 push 时输入 GitLab 用户名和 PAT（不是账号密码）。如果你是 SSH URL，则在 SSH executable 里选Native，用本机 ssh-agent 管理私钥即可。

VS Code 和 IntelliJ 思路一样：要么用 SSH key，要么在 credential helper 里填username+PAT。代码里不要写 token，IDE 的凭据管理器会自动保存。

4.4 CI/CD 流水线与 Runner 注册的调整

开启 2FA 后 CI/CD 这边有几个容易踩坑的点。第一，如果项目中已经注册过 GitLab Runner，runner 用的是项目里的registration_token和 runner 自己的authentication_token注册的，这些 token 和注册过程并不过 2FA，所以现有 runner 不会受影响。

第二，如果你想在 Web 页面“新建 Runner”或者通过界面查看 runner 的 registration token，这些操作属于“管理范围的高危操作”，GitLab 在安全策略上要求管理员账号执行，有些场景会要求二次验证。如果你的 runner token 需要轮换，提前在项目设置 →CI/CD→Runners里处理，把旧 token 撤销再重新注册。

第三，流水线里如果要调用 GitLab API，用CI_JOB_TOKEN比在 CI 变量里硬编码 PAT 安全得多。系统预置的CI_JOB_TOKEN在gitlab-ci.yml里直接可用：

deploy_job: stage: deploy script: - curl --header "PRIVATE-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects"

这样既不需要在 CI 变量里维护 PAT，也避免了 2FA 环境下 token 过期无人维护的问题。

4.5 Docker 部署自建 GitLab 的管理员恢复操作

搜热词时发现“docker安装gitlab”相关的问题不少，如果是 Docker 自建的 GitLab，管理员碰到的 2FA 恢复问题比 SaaS 更棘手，因为在 Web 上丢了恢复码，你是没法“找官方客服”的，只能进容器里操作。这里给一个我实测可用的命令：

docker exec -it gitlab gitlab-rails runner " user = User.find_by_username('your_username') user.otp_required_for_login = false user.save! puts '2FA disabled' "

执行前先确认容器名是gitlab，如果容器名不一样，换成你自己的。这条命令的作用是把目标用户的otp_required_for_login字段设为 false，等用户下次登录时就能直接绕过 2FA。同时建议把该用户的otp_secret清除，彻底移除绑定的验证器：

docker exec -it gitlab gitlab-rails runner " user = User.find_by_username('your_username') user.otp_required_for_login = false user.otp_secret = nil user.save! "

跑完字段更新后，用户重新登录再绑定一个新的 2FA 即可。这个操作只适合管理员处理“忘了一切凭证”的极限场景，平时尽量不要用脚本去动 2FA 字段，否则等于给绕过开了一扇门。

5. 常见问题与排查技巧实录

5.1 恢复码丢了，手机也换了，还能不能救

这种场景我处理过好几回。分两种情况：如果你是普通用户，那就是没有自救路径，必须找 GitLab 管理员，管理员用第 4.5 节的 rails console 命令给你解绑 2FA。如果你是 SaaS 版 GitLab（GitLab.com），没有管理员权限，唯一的自救是：如果你曾经下载过恢复码，就从加密备份里恢复；如果恢复码也没了，联系官方支持并证明账号归属，过程非常漫长，所以恢复码一定要留备份。

如果是团队内部自建 GitLab，我建议管理员在运维文档里留存一张“2FA 紧急解绑流程”的页面，上面记录着 rails console 命令。这个页面权限严格控制，只能管理员看，否则这个“后门”本身就是漏洞。

5.2 手机时间不准导致验证码一直报错

GitLab 的 TOTP 验证失败最常出现的一种情况是“验证码输入没错但提示 invalid”。用手头手机打开其他任何 TOTP 认证码做对比，如果所有验证码都差一分钟左右，基本能判定是手机时间漂移。

Google Authenticator 的对策是：App 内设置→时间校正→ 立即同步。iOS 和 Android 都在设置项里能找。校正完再过 30 秒输入新验证码，基本就通了。服务器时间不用自己改，GitLab 容器默认走 NTP，除非你自己在 Docker 部署时把系统时间调乱了。

5.3 浏览器扩展自动填充不灵怎么办

如果你选的是 Bitwarden 或者其他浏览器扩展方案，常见的“不灵”场景有两种。第一种是扩展没有解锁：浏览器重启后主密码没输，LiFi 扩展处于锁定状态，页面上的 6 位码框自然不会有提示。第二种是网页的登录表单结构特殊，GitLab 的 2FA 输入框本身是普通文本输入框，常规扩展应该都能识别，如果个别站点不行，就手动从扩展里复制验证码粘贴进去。

更隐蔽的一个坑：浏览器扩展根据“当前登录的 GitLab 用户名”来匹配合适的 TOTP 条目，如果你在同一个浏览器里同时登录了多个 GitLab 账号，扩展可能匹配到默认条目，自动填充后报错。解决方式是手动点扩展，选择对应的 GitLab 账号条目，再填充。

5.4 递归困境：用 GitLab 账号登录第三方服务时卡在 2FA

很多人还会遇到这种情况：GitLab 里集成了 Jenkins、SonarQube、Harbor 等第三方系统，这些系统通过 OAuth 方式接入 GitLab 单点登录。开启 2FA 后，第三方系统跳转回 GitLab 授权时，有些老系统的 OAuth 回调并不会给你弹 2FA 验证页，而是直接报错。

这种情况基本要升级第三方系统的版本，或者把 OAuth 应用改成 Private Application + PAT 方式接入。如果第三方应用不支持 OAuth 换 token 的 2FA 校验，也可以用 Project Access Token 或 Deploy Token 代替个人账号授权。

5.5 多人共用一个 GitLab 账号的治理兜底

不提倡多人共用账号，但很多企业历史遗留就是这么干的。一旦在这个共享账号上开 2FA，等于全组人都要拿同一个手机验证码，运维活活变成传话游戏。正确的做法是彻底分账号，每个人一个账号，再通过 Group 的成员权限管理仓库权限。如果是历史遗留必须过渡，建议别对这个共享账号开 2FA，而是先用 Group Access Token 解决 CI/CD 的临时访问需求，然后排期拆账号。

最后再分享两个小技巧

第一，恢复码我习惯打印一份纸质的放在钱包里，同时 Bitwarden 里加密存一份电子版。这份备份平时基本用不上，但换手机、出差丢设备时它就是救命稻草。第二，团队里如果有人 2FA 被锁，管理员解绑后记得要求对方用“新验证器 + 新恢复码”重新绑定，顺便把旧恢复码作废——我遇到过解绑后用户忘了重新绑定，结果账号裸奔了一周才被发现。

GitLab 的双因素认证开启只是起点，真正的安全建设是在它之上把恢复码、PAT、SSH key、CI/CD token 四套凭证分开管理，各自最小化权限。代码仓库是整个公司的命脉，值得多花一点时间把这条链路上的认证做扎实。