GitLab SSH Key 配置完全指南：从入门到精通 (详细步骤)

前言

在现代软件开发工作流中，GitLab 作为领先的一体化 DevOps 平台，为代码托管、版本控制、CI/CD 等提供了强大的支持。与 GitLab 服务器交互时，我们通常有两种主要的认证方式：HTTPS 和 SSH。

• HTTPS：通常使用用户名/密码或个人访问令牌 (Personal Access Token, PAT)。对于频繁的操作，每次都需要输入凭证（或依赖凭证管理器），相对繁琐。
• SSH (Secure Shell)：基于密钥对的认证方式。在本地生成一对密钥（公钥和私钥），将公钥上传到 GitLab，之后本地 Git 操作通过私钥进行身份验证，无需重复输入密码，更加安全、高效和便捷。

对于开发者而言，配置 SSH Key 是与 GitLab 进行顺畅交互的基础技能。它不仅简化了 git push, git pull, git clone 等操作，还显著提升了安全性，因为私钥存储在本地，不易在网络传输中泄露。

本文将提供一份极其详尽的步骤指南，涵盖从检查现有密钥、生成新密钥、添加到 GitLab 账户，到测试连接、配置仓库以及常见问题排查和安全最佳实践的方方面面，旨在帮助初学者和有经验的用户都能准确、安全地完成 GitLab SSH Key 的配置。预计阅读和操作时间约为 15-30 分钟。

本文主要内容包括：

1. SSH Key 基础知识简介：理解公钥和私钥的作用。
2. 前提条件：确保你的系统环境满足要求。
3. 步骤一：检查本地是否已存在 SSH Key：避免重复生成和管理混乱。
4. 步骤二：生成新的 SSH Key 对：详细讲解生成命令和选项，推荐现代加密算法。
5. 步骤三：将 SSH 公钥添加到 GitLab 账户：图文并茂地指导你在 GitLab 界面完成操作。
6. 步骤四：测试 SSH 连接：验证配置是否成功。
7. 步骤五：配置本地 Git 仓库使用 SSH：切换现有仓库或克隆新仓库。
8. 常见问题排查 (Troubleshooting)：解决配置过程中可能遇到的问题。
9. 安全最佳实践：保护你的 SSH Key 和账户安全。
10. 进阶话题 (可选)：多密钥管理与 SSH Agent。
11. 总结

让我们开始这段详细的 GitLab SSH Key 配置之旅吧！

1. SSH Key 基础知识简介

SSH 密钥对认证基于非对称加密技术。当你生成密钥时，会同时产生两个文件：

• 私钥 (Private Key)：通常命名为 id_rsa, id_ed25519 或 id_ecdsa（取决于加密算法）。这个文件必须严格保密，绝不能泄露给任何人或上传到任何地方。 它存储在你的本地计算机上，相当于你的数字“身份证”，用于证明你的身份。
• 公钥 (Public Key)：通常命名为 id_rsa.pub, id_ed25519.pub 或 id_ecdsa.pub。这个文件可以安全地分享给其他人或服务（如 GitLab）。GitLab 会存储你的公钥。

工作原理：

1. 当你尝试通过 SSH 连接 GitLab 时（例如执行 git push），你的 Git 客户端会使用你的私钥对一个特定的数据进行签名。
2. 这个签名连同你的请求一起发送到 GitLab 服务器。
3. GitLab 服务器查找与你用户名关联的公钥列表。
4. GitLab 使用你账户中存储的公钥来验证这个签名。
5. 如果签名验证成功，证明你确实拥有对应的私钥，GitLab 就确认了你的身份，允许你执行操作。

这种方式避免了在网络上传输密码，大大降低了密码被截获的风险。

2. 前提条件

在开始配置之前，请确保你的系统满足以下基本条件：

• 安装了 Git：Git 是进行版本控制的基础。大多数现代操作系统都预装或可以轻松安装 Git。你可以通过在终端或命令提示符中运行 git --version 来检查。
• 安装了 SSH 客户端：SSH 客户端用于生成密钥和建立 SSH 连接。
  • Linux/macOS：通常系统自带 OpenSSH 客户端。
  • Windows：
    • Git for Windows (推荐)：安装 Git 时会自带一个 Git Bash 环境，其中包含了 OpenSSH 客户端。这是在 Windows 上最常用的方式。
    • Windows 10/11 内建 OpenSSH Client：较新版本的 Windows 可以在“设置” -> “应用” -> “可选功能”中添加 OpenSSH 客户端。
    • WSL (Windows Subsystem for Linux)：如果你使用 WSL，其 Linux 环境通常也自带 OpenSSH。
      你可以在终端/命令提示符/Git Bash 中运行 ssh -V 来检查 SSH 客户端版本。
• 拥有一个 GitLab 账户：你需要登录你的 GitLab 账户来添加公钥。无论是 GitLab.com 还是自托管的 GitLab 实例。
• 访问终端或命令提示符：你需要一个命令行界面来执行生成密钥和测试连接的命令。
  • Linux: Terminal
  • macOS: Terminal.app
  • Windows: Git Bash (推荐), Command Prompt (需确认 OpenSSH 可用), PowerShell (需确认 OpenSSH 可用), 或 WSL 终端。

3. 步骤一：检查本地是否已存在 SSH Key

在生成新密钥之前，最好先检查一下你的计算机上是否已经存在 SSH 密钥对。这可以避免覆盖现有密钥（可能用于其他服务）或不必要地创建多个密钥。

SSH 密钥通常存储在用户主目录下的 .ssh 隐藏文件夹中。

操作方法：

打开你的终端或 Git Bash，执行以下命令：

```bash

Linux / macOS / Windows (Git Bash)

ls -al ~/.ssh
```

• ls：列出文件和目录。
• -a：显示所有文件，包括隐藏文件（以 . 开头的文件和目录）。
• -l：使用长列表格式显示。
• ~/.ssh：~ 代表用户主目录，.ssh 是存储 SSH 相关文件的默认目录。

检查输出结果：

你需要寻找以下模式的文件名：

• id_rsa 和 id_rsa.pub
• id_ed25519 和 id_ed25519.pub
• id_ecdsa 和 id_ecdsa.pub

可能的情况：

• 找到现有的密钥对（例如 id_ed25519 和 id_ed25519.pub）：
  • 如果你确定这个密钥对是你想要用于 GitLab 的，并且你记得它的密码（如果设置了的话），你可以跳过步骤二（生成新密钥），直接进入步骤三（添加公钥到 GitLab）。强烈建议使用现有的、安全的密钥，尤其是 ED25519 类型的。
  • 如果你不确定这个密钥的用途，或者想为 GitLab 创建一个专用的密钥，那么继续执行步骤二来生成一个新的密钥对。
• .ssh 目录不存在，或目录存在但没有上述密钥文件：你需要生成一个新的 SSH 密钥对。继续执行步骤二。
• 只找到公钥文件 (.pub) 而没有对应的私钥文件：这意味着密钥对不完整，你需要生成一个新的密钥对。
• 找到多个密钥对：你可以选择其中一个使用，或者生成一个新的。如果选择现有密钥，请确保你知道哪个私钥对应哪个公钥。

注意：.ssh 目录的权限非常重要。通常应该是 700 (drwx------), 私钥文件的权限应该是 600 (-rw-------)。权限不正确可能导致 SSH 连接失败。如果权限不正确，可以使用 chmod 命令修复：
bash
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519 # 根据你的私钥文件名调整

4. 步骤二：生成新的 SSH Key 对

如果你需要生成新的密钥对，请按照以下步骤操作。我们将使用 ssh-keygen 命令。

推荐使用 ED25519 算法：ED25519 是目前推荐的现代 SSH 密钥算法，它比传统的 RSA 更安全、性能更好，生成的密钥也更短。如果你的系统或 GitLab 版本不支持 ED25519（非常少见的情况），可以退而求其次使用 RSA (建议 4096 位)。

操作方法：

1. 打开终端或 Git Bash。

2. 执行 ssh-keygen 命令。

   • 推荐使用 ED25519:
     bash
ssh-keygen -t ed25519 -C "[email protected]"
   • 如果需要使用 RSA (4096位):
     bash
ssh-keygen -t rsa -b 4096 -C "[email protected]"

   命令参数解释：
   * ssh-keygen: 生成密钥的命令。
   * -t ed25519 或 -t rsa: 指定要创建的密钥类型 (type)。-t 是 type 的缩写。
   * -b 4096: （仅用于 RSA）指定密钥的位数 (bits)。对于 RSA，建议至少 4096 位以保证安全性。ED25519 不需要指定位数。-b 是 bits 的缩写。
   * -C "[email protected]": 添加一个注释 (comment)。通常使用你的邮箱地址作为注释，方便识别这个密钥属于谁。这不是功能必需的，但强烈推荐加上。请将 "[email protected]" 替换为你自己的邮箱地址（最好是与你 GitLab 账户关联的邮箱）。-C 是 comment 的缩写。

3. 交互式提示：
   执行命令后，ssh-keygen 会向你提出几个问题：

   • Enter file in which to save the key (/Users/your_user/.ssh/id_ed25519):
     这里询问你保存密钥文件的路径和名称。

     • 直接按 Enter：接受默认路径和文件名（例如 ~/.ssh/id_ed25519）。这是最常见和推荐的做法，除非你有充分理由使用不同的名称（比如管理多个密钥）。
     • 输入自定义路径/名称：如果你想将密钥保存在其他位置或使用不同的名称（例如 ~/.ssh/gitlab_key），请输入完整的路径和文件名。如果选择自定义名称，请务必记住它，后续步骤需要用到。
     • 警告：如果默认文件已存在（比如你之前检查过但决定重新生成），它会提示 ... already exists. Overwrite (y/n)?。除非你确定要覆盖旧密钥，否则输入 n 然后重新运行 ssh-keygen 并指定一个不同的文件名。

   • Enter passphrase (empty for no passphrase):
     这里要求你为私钥设置一个密码 (passphrase)。

     • 强烈推荐设置一个强密码！ 这个密码用于保护你的私钥文件。即使你的私钥文件意外泄露，没有密码，攻击者也无法使用它。
     • 密码可以是几个单词组成的短语，比单个单词更安全。确保你能记住它。
     • 输入密码时，屏幕上不会显示任何字符（甚至星号或点），这是正常的安全措施。
     • 如果你不设置密码（直接按 Enter）：你的私钥将不受密码保护。任何人如果获得了你的私钥文件，就能冒充你与 GitLab 进行交互。这非常不安全，极不推荐。
     • 便利性 vs 安全性：设置密码后，每次使用该密钥（例如 git push/pull）时，系统可能会要求你输入密码。虽然稍微麻烦一点，但安全性大大提高。（后面会提到使用 ssh-agent 来避免频繁输入密码）。

   • Enter same passphrase again:
     再次输入你设置的密码以确认。

4. 生成完成：
   如果一切顺利，你会看到类似以下的输出：

   Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/your_user/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/your_user/.ssh/id_ed25519.
Your public key has been saved in /Users/your_user/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx [email protected]
The key's randomart image is:
+--[ED25519 256]--+
| .. |
| o= . |
| .* B |
| . =+ = . |
| . + S= * |
| o.o=.= o |
| . o+o= E . |
| o.o+ . . |
| .+ .. |
+----[SHA256]-----+

   这表示你的私钥（例如 id_ed25519）和公钥（例如 id_ed25519.pub）已经在指定的目录下成功生成。

5. （可选但推荐）将新密钥添加到 SSH Agent
   如果你为密钥设置了密码，为了避免每次 Git 操作都输入密码，可以使用 ssh-agent。ssh-agent 是一个在后台运行的程序，它可以缓存你的解密后的私钥，并在需要时自动提供给 SSH 连接。

   • 启动 ssh-agent (如果尚未运行):
     bash
# 在后台启动 agent (Bash 或 Zsh)
eval "$(ssh-agent -s)"
     你应该会看到类似 Agent pid xxxx 的输出。

   • 将你的私钥添加到 ssh-agent:
     bash
# 将默认的 ed25519 私钥添加到 agent
ssh-add ~/.ssh/id_ed25519
     如果你的私钥文件名不是默认的，请替换成你的私钥文件路径。
     执行此命令时，会要求你输入之前设置的私钥密码。输入一次后，只要 ssh-agent 进程在运行，你就不需要再次为使用该密钥的操作输入密码了。

   • 注意: ssh-agent 的生命周期通常与你的终端会话或登录会话相关。关闭终端或重启电脑后可能需要重新启动 ssh-agent 并 ssh-add 密钥（除非你配置了自动启动和加载）。在 macOS 上，通常与 Keychain 集成得更好。在 Windows Git Bash 中，它通常与 Bash 会话绑定。

现在，你已经有了一个 SSH 密钥对，并且（如果设置了密码）可能已经将其添加到了 ssh-agent。下一步是将公钥添加到你的 GitLab 账户。

5. 步骤三：将 SSH 公钥添加到 GitLab 账户

在这一步，你需要将公钥的内容复制并粘贴到你的 GitLab 账户设置中。再次强调：是公钥 (.pub 文件)，绝不是私钥！

操作方法：

1. 复制公钥内容到剪贴板：
   你需要获取 .pub 文件的全部内容。有多种方法可以做到：

   • 方法一：使用 cat 命令打印到终端，然后手动复制 (通用)
     bash
cat ~/.ssh/id_ed25519.pub
     (如果你的公钥文件名不同，请替换 id_ed25519.pub)
     命令执行后，终端会显示公钥的全部内容，它通常以 ssh-ed25519 或 ssh-rsa 开头，以你的邮箱地址（注释）结尾。确保完整复制所有内容，从 ssh- 开头到邮箱结尾，不要遗漏任何字符，也不要添加额外的换行符。

   • 方法二：使用特定工具直接复制到剪贴板 (更方便)

     • macOS:
       bash
pbcopy < ~/.ssh/id_ed25519.pub
     • Windows (Git Bash):
       bash
clip < ~/.ssh/id_ed25519.pub
     • Linux (需要安装 xclip):
       bash
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard
       或者 (需要安装 xsel):
       bash
cat ~/.ssh/id_ed25519.pub | xsel --clipboard --input
       这些命令会直接将公钥文件的内容复制到系统剪贴板，减少手动复制时出错的可能。

2. 登录 GitLab:
   打开你的 Web 浏览器，访问你的 GitLab 实例 (例如 https://gitlab.com 或你的自托管 GitLab 地址) 并登录你的账户。

3. 导航到 SSH Keys 设置页面:

   • 点击页面右上角的你的头像 (Avatar)。
   • 在下拉菜单中选择 "Preferences" (偏好设置) 或 "Edit profile" (编辑个人资料)，然后在新页面的左侧导航栏找到并点击 "SSH Keys"。
   • 或者，路径通常是 /-/profile/keys 或 User Settings -> SSH Keys。

4. 粘贴并添加公钥:
   在 "SSH Keys" 页面，你会看到一个用于添加新密钥的区域：

   • "Key" 文本框: 将你刚才复制的完整公钥内容粘贴到这个大的文本框中。确保没有多余的空格或换行符。
   • "Title" 文本框: 为这个密钥设置一个描述性的标题。这有助于你区分来自不同计算机或用途的密钥。例如："Work Laptop - [email protected]", "Home Desktop", "MacBook Pro (ED25519)"。一个好的标题能让你在以后管理密钥时更容易识别。
   • "Usage type" (可选，较新 GitLab 版本): 你可能会看到选择密钥用途的选项，如 "Authentication & Signing" 或 "Authentication"。通常选择默认的 "Authentication & Signing" 即可，除非你有特定需求只用于认证。
   • "Expires at" (可选): 你可以为这个 SSH Key 设置一个过期日期。这是一个很好的安全实践（密钥轮换），但不是必需的。如果设置了，到期后该密钥将无法使用，需要添加新的密钥。

5. 点击 "Add key" 按钮。

   
   
   示例：GitLab 添加 SSH Key 的界面 (图片来源: GitLab Documentation)

添加成功后，你应该能在下方的 "Your SSH keys" 列表中看到你刚刚添加的密钥及其标题和指纹。

6. 步骤四：测试 SSH 连接

添加公钥到 GitLab 后，你需要测试一下本地计算机和 GitLab 服务器之间的 SSH 连接是否已经成功建立。

操作方法:

1. 打开终端或 Git Bash。

2. 执行测试命令:
   bash
ssh -T [email protected]

   • 将 gitlab.com 替换为你的 GitLab 实例的主机名（如果你使用的是自托管的 GitLab，例如 [email protected]）。
   • -T 选项表示禁止分配伪终端，我们只是测试连接，不需要一个交互式 shell。
   • git 是用于 Git 操作的 SSH 用户名，对于所有 GitLab 实例（包括 gitlab.com 和自托管的）通常都是 git。

3. 处理首次连接的提示 (The authenticity of host ...):
   如果是你第一次从这台计算机连接到该 GitLab 服务器，你可能会看到类似以下的警告信息：
   The authenticity of host 'gitlab.com (172.65.251.78)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

   • 这是正常的安全机制。SSH 客户端告诉你它不认识这个服务器，需要你确认是否信任该服务器的公钥指纹。
   • 验证指纹 (推荐做法，但非必需): 为了最高安全性，你可以对照 GitLab 官方文档或其他可信来源提供的服务器 SSH 主机密钥指纹，确认这里显示的指纹是正确的。GitLab.com 的指纹可以在其文档中找到。
   • 确认连接: 如果你确认主机名正确（或者选择信任），输入 yes 并按 Enter。
   • SSH 客户端会将该服务器的公钥添加到你的 ~/.ssh/known_hosts 文件中，下次连接时就不会再询问了（除非服务器的密钥发生变化）。

4. 检查连接结果:

   • 成功连接: 如果你的 SSH Key 配置正确，并且 GitLab 服务器验证通过，你会收到一条欢迎信息，通常包含你的 GitLab 用户名：
     Welcome to GitLab, @your_username!
     看到这个消息就表示你的 SSH Key 已经成功配置并可以用于 GitLab 认证了！

   • 失败连接 (例如 Permission denied (publickey)): 如果连接失败，通常会看到类似以下的错误信息：
     [email protected]: Permission denied (publickey).
     或者
     fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
     这表示 SSH 认证失败了。请参考下面的常见问题排查部分来解决问题。

7. 步骤五：配置本地 Git 仓库使用 SSH

现在你的 SSH 连接已经测试成功，你可以开始使用 SSH URL 来克隆新的 GitLab 仓库，或者修改现有仓库的远程 URL 从 HTTPS 切换到 SSH。

使用 SSH URL 的好处： 之后你对这个仓库执行 git pull, git push 等操作时，Git 会自动使用你的 SSH Key 进行认证，无需再输入用户名/密码或 Token。

操作方法：

1. 找到仓库的 SSH URL:

   • 在 GitLab 上打开你想要操作的仓库页面。
   • 点击仓库主页上蓝色的 "Clone" (克隆) 按钮。
   • 在弹出的下拉菜单中，确保选中 "Clone with SSH" (使用 SSH 克隆)。
   • 复制提供的 SSH URL。它看起来应该像这样：[email protected]:your-group/your-project.git (对于 gitlab.com) 或 [email protected]:your-group/your-project.git (对于自托管实例)。

2. 克隆新仓库:
   如果你要将仓库首次克隆到本地，使用 git clone 命令并粘贴刚才复制的 SSH URL：
   ```bash
   # 打开你想要存放项目的本地目录
   cd /path/to/your/projects

   使用 SSH URL 克隆仓库

   git clone [email protected]:your-group/your-project.git
   ```
   Git 会使用你的 SSH Key 进行认证并下载仓库内容。

3. 修改现有仓库的远程 URL (从 HTTPS 切换到 SSH):
   如果你本地已经有一个通过 HTTPS 克隆的仓库，你想将其切换为使用 SSH，可以按以下步骤操作：

   • 进入仓库目录:
     bash
cd /path/to/your/existing-project

   • 查看当前的远程 URL:
     bash
git remote -v
     你会看到类似以下的输出 (通常远程名为 origin)，显示了 fetch 和 push 的 URL，它们现在应该是 HTTPS 格式：
     origin https://gitlab.com/your-group/your-project.git (fetch)
origin https://gitlab.com/your-group/your-project.git (push)

   • 修改远程 URL 为 SSH 格式:
     使用 git remote set-url 命令，并将 origin (或你的远程名称) 和新的 SSH URL 作为参数：
     bash
git remote set-url origin [email protected]:your-group/your-project.git
     (请确保将 URL 替换为你仓库的实际 SSH URL)

   • 再次验证远程 URL 是否已更新:
     bash
git remote -v
     现在输出应该显示 SSH 格式的 URL 了：
     origin [email protected]:your-group/your-project.git (fetch)
origin [email protected]:your-group/your-project.git (push)

完成这些操作后，你对这个本地仓库执行的所有需要与远程 GitLab 服务器交互的 Git 命令（如 pull, push, fetch）都将通过 SSH 进行认证。

8. 常见问题排查 (Troubleshooting)

在配置或使用 SSH Key 的过程中，可能会遇到一些问题。以下是一些常见问题及其解决方法：

• 错误：Permission denied (publickey) 或 fatal: Could not read from remote repository.
  这是最常见的错误，表示 SSH 认证失败。原因可能有多种：

  • 公钥未正确添加到 GitLab: 再次检查步骤三，确保你复制粘贴的是完整的公钥内容，并且已成功添加到 GitLab 账户的 SSH Keys 设置中。注意不要有多余的空格或换行符。
  • 未使用正确的私钥: 如果你生成了多个 SSH Key，或者指定了非默认的文件名，SSH 可能没有找到或使用正确的私钥进行认证。
    • 检查 ssh-add -l: 运行 ssh-add -l 查看当前 ssh-agent 管理的密钥。如果你的密钥不在列表中，使用 ssh-add ~/.ssh/your_private_key 添加它（需要输入密码，如果设置了的话）。
    • 使用 ~/.ssh/config 文件 (进阶): 你可以创建一个 ~/.ssh/config 文件来明确指定哪个密钥用于连接哪个主机。例如：
      Host gitlab.com
HostName gitlab.com
User git
IdentityFile ~/.ssh/id_ed25519_gitlab # 指定用于 gitlab.com 的私钥文件
IdentitiesOnly yes
      确保 IdentityFile 指向你为 GitLab 生成的私钥文件。
  • 本地 SSH Key 文件权限不正确: .ssh 目录权限应为 700 (drwx------)，私钥文件 (如 id_ed25519) 权限应为 600 (-rw-------)，公钥文件 (.pub) 权限通常为 644 (-rw-r--r--)。使用 chmod 命令修复。
    bash
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
  • 仍然在使用 HTTPS URL: 确保你的 Git 仓库远程 URL 确实是 SSH 格式 (git@...) 而不是 HTTPS 格式 (https://...)。使用 git remote -v 检查，并用 git remote set-url 修改（如步骤七所述）。
  • GitLab 服务器问题: 极少数情况下，可能是 GitLab 服务器端的配置问题。如果是自托管实例，联系你的 GitLab 管理员。

• 每次操作都需要输入密码:

  • 原因: 你为 SSH Key 设置了密码，但没有使用 ssh-agent 来缓存解密后的密钥。
  • 解决方法: 按照步骤二末尾或步骤四开头的方法，启动 ssh-agent 并使用 ssh-add 将你的私钥添加进去。这样在 agent 运行期间就不需要重复输入密码了。

• 忘记了 SSH Key 的密码:

  • 无法恢复: SSH Key 的密码是无法找回或重置的。
  • 解决方法: 你需要重新生成一个新的 SSH Key 对（重复步骤二），然后将新的公钥添加到 GitLab（替换或添加新的记录，步骤三），并更新本地仓库可能需要的配置。记得删除或备份旧的无法使用的密钥文件。

• 错误：Host key verification failed.

  • 原因: 你连接的 GitLab 服务器的 SSH 主机密钥发生了变化（可能是服务器升级、重装，或者潜在的安全风险：中间人攻击），或者你之前连接过同名但 IP 不同的主机，导致 ~/.ssh/known_hosts 文件中的记录与当前服务器提供的不匹配。
  • 解决方法:
    1. 谨慎处理! 首先确认你连接的服务器地址 (gitlab.com 或你的自托管地址) 是正确的。
    2. 确认密钥变更是否预期: 如果是公司内部的 GitLab 实例，询问管理员服务器密钥是否确实变更过。如果是 GitLab.com，检查官方公告或状态页。
    3. 如果是预期内的变更或确认安全: 你需要移除 known_hosts 文件中关于该主机的旧记录。
       • 自动移除: 错误信息通常会提示你运行类似 ssh-keygen -R gitlab.com 的命令来移除旧密钥。
       • 手动编辑: 打开 ~/.ssh/known_hosts 文件，找到对应于 gitlab.com (或你的主机名) 的那一行（或多行），将其删除并保存文件。
    4. 再次尝试连接: 运行 ssh -T [email protected]，系统会再次提示你确认新主机的指纹（像第一次连接一样），输入 yes 即可。
    5. 如果怀疑是中间人攻击: 停止连接！ 并立即联系你的网络安全团队或 GitLab 管理员。

• 使用了错误的 GitLab 主机名:

  • 确保你在 ssh -T 测试命令或 Git 仓库 URL 中使用的 GitLab 主机名是正确的。例如，是 gitlab.com 还是 gitlab.yourcompany.com？

• 防火墙或网络问题:

  • 确保你的网络环境允许通过 SSH 协议（默认端口 22）连接到目标 GitLab 服务器。公司防火墙或代理可能需要特殊配置。

9. 安全最佳实践

保护好你的 SSH Key 至关重要，它关系到你代码仓库的安全。

• 始终为私钥设置强密码: 这是防止私钥文件意外泄露后被滥用的最重要防线。
• 保护好你的私钥文件:
  • 绝不分享、上传或提交 id_...（没有 .pub 后缀）的私钥文件到任何地方。
  • 确保私钥文件的权限是 600 (-rw-------)，只有你自己可读写。
  • 考虑使用硬件安全模块 (HSM) 或 YubiKey 等物理设备存储密钥以获得更高安全性（进阶）。
• 使用 ED25519 或 RSA 4096 位密钥: 避免使用旧的、不安全的算法如 DSA 或 RSA (低于 2048 位)。
• 定期审查添加到 GitLab 的公钥: 在 GitLab 的 /-/profile/keys 页面，定期检查列表中的密钥，移除不再使用或来源不明的密钥。
• 为不同的设备/环境使用不同的密钥: 例如，为工作电脑和个人电脑分别生成密钥。这样如果一台设备丢失或被盗，你只需撤销该设备对应的密钥即可，不影响其他设备。使用描述性的标题来区分它们。
• 考虑设置密钥过期时间: 在 GitLab 添加密钥时设置一个过期日期，强制定期轮换密钥，增加安全性。
• 谨慎使用 ssh-agent: 虽然方便，但如果你的计算机被恶意软件感染，agent 中缓存的未加密密钥可能被窃取。确保你的操作系统安全，并在离开电脑时锁定屏幕。

10. 进阶话题 (可选)

• 管理多个 SSH Key: 如果你需要使用不同的 SSH Key 连接不同的服务（例如，一个 Key 用于 GitLab，一个用于 GitHub，一个用于公司内部服务器），或者用不同的 Key 连接同一个服务的不同账户，你需要配置 SSH 客户端来自动选择正确的 Key。这通常通过编辑 ~/.ssh/config 文件来实现。
  ```
  # ~/.ssh/config

  GitLab.com 使用的 Key

  Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_ed25519_gitlab
  IdentitiesOnly yes

  GitHub.com 使用的 Key

  Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_rsa_github
  IdentitiesOnly yes

  公司内部 GitLab 实例

  Host gitlab.mycompany.com
  HostName gitlab.mycompany.com
  User git
  IdentityFile ~/.ssh/id_ed25519_company
  IdentitiesOnly yes
  ``
你需要为每个 Key 生成对应的密钥对，并将IdentityFile` 指向正确的私钥文件。

• Deploy Keys vs User Keys: 你添加到个人账户 SSH Keys 页面的密钥是 User Keys，它们授予你对你有权限的所有仓库的访问权限。GitLab 还支持 Deploy Keys，这种密钥通常只授予对单个仓库或一组仓库的只读或读写权限，常用于 CI/CD 或自动化部署脚本，而不是个人用户。

• 使用 SSH Key 签名 Git Commits: 除了认证，你还可以配置 Git 使用你的 SSH Key 来签名你的 commits，以证明这些 commit 确实是你本人做出的。这需要在 Git 中进行额外配置，并在 GitLab 中启用 GPG/SSH 签名验证。

11. 总结

配置 GitLab SSH Key 是提升开发效率和安全性的关键一步。通过遵循本指南详细的步骤——从检查现有密钥、生成安全的 ED25519 密钥对、添加公钥到 GitLab、测试连接，到配置 Git 仓库使用 SSH——你应该能够顺利完成设置，并享受无需重复输入密码即可与 GitLab 安全交互的便利。

请务必牢记安全最佳实践，特别是为私钥设置强密码并妥善保管。遇到问题时，仔细回顾排查步骤，大多数常见问题都能得到解决。

现在，你已经掌握了为 GitLab 配置 SSH Key 的完整流程。开始更高效、更安全地使用 GitLab 吧！