GitLab SSH Key 添加与管理 – wiki基地

作者： /

GitLab SSH Key 的添加与管理：安全、便捷的代码协作之路

在现代软件开发的协作环境中，代码版本控制系统扮演着核心角色。GitLab 作为一款广受欢迎的 Git 代码仓库管理平台，为开发者提供了强大的协作工具。与 GitLab 进行交互的方式主要有两种：通过 HTTPS 和通过 SSH。虽然 HTTPS 简单易用，但每次操作（如 git pull 或 git push）都需要输入用户名和密码（或 Personal Access Token），这在频繁操作时显得繁琐。相比之下，使用 SSH Keys 提供了一种更安全、更便捷的认证方式，一旦设置完成，后续操作将无需重复输入凭据，极大地提高了工作效率。

本文将深入探讨 GitLab SSH Key 的概念、原理、生成过程、添加到 GitLab 的步骤、管理方法以及相关的最佳实践和常见问题，旨在帮助您充分利用 SSH Keys 的优势，畅通无阻地进行代码协作。

第一部分：理解 SSH Key 及其在 GitLab 中的作用

1. 什么是 SSH Key？

SSH Key（Secure Shell Key）是一种用于通过 SSH 协议进行身份验证的加密密钥对。它由一对相关联的密钥组成：
* 公钥 (Public Key)： 可以安全地公开分享。它就像一个数字锁，可以加密信息，但不能解密。在认证过程中，它被用于验证持有匹配私钥的用户的身份。
* 私钥 (Private Key)： 必须严格保密。 它就像这把数字锁的唯一钥匙，可以解密用对应的公钥加密的信息，并用于数字签名，证明持有者就是公钥的拥有者。

这对密钥是数学上关联的，但仅凭公钥无法推导出私钥。

2. 为什么要在 GitLab 中使用 SSH Key？

使用 SSH Key 连接 GitLab 带来了诸多优势：

  • 安全性：
    • 与基于密码的认证相比，SSH Key 认证通常更安全，因为它不容易受到暴力破解攻击（密钥长度通常远超密码复杂度）。
    • 私钥存储在本地计算机上，且可以设置密码保护，降低了泄露风险。
    • 无需在每次 Git 操作时在网络上传输密码。
  • 便捷性：
    • 一次设置，长期有效。无需记住或频繁输入密码。
    • 结合 SSH Agent 可以实现无密码输入（只需要在启动会话或添加密钥时输入一次私钥密码）。
  • 自动化友好： SSH Key 认证非常适合用于自动化脚本、持续集成/持续部署（CI/CD）流程等，无需人工介入输入密码。
  • 权限控制： 可以通过为不同的用户或机器生成不同的密钥对，并在 GitLab 中管理这些公钥来精细控制访问权限。

3. SSH Key 认证原理（简化版）

当您使用 SSH 协议连接到 GitLab 服务器时（例如执行 git clone、git pull、git push 等操作），其认证过程大致如下：

  1. 您的本地 SSH 客户端（通常是您的终端）向 GitLab 服务器发起连接请求，并声明希望使用公钥认证。
  2. 服务器收到请求后，会从其存储中查找与您的用户名（对于 Git 仓库操作，通常是用户 git）关联的所有公钥列表。
  3. 服务器随机生成一个数据片段，并使用列表中的每个公钥对其进行加密，然后发送给您的客户端。
  4. 您的 SSH 客户端尝试使用您的本地私钥来解密服务器发送的数据片段。
  5. 如果成功解密，客户端会用私钥对一个包含会话标识符的新数据片段进行数字签名，并将签名后的数据发送回服务器。
  6. 服务器收到签名数据后，会使用 匹配 您用于解密的那个公钥来验证签名的有效性。
  7. 如果签名验证通过，服务器就确认您的身份是持有该公钥对应私钥的合法用户，从而允许连接并执行 Git 操作。

整个过程您的私钥从未离开您的本地计算机，保障了安全性。

第二部分：生成 SSH Key Pair

要开始使用 SSH Key，您首先需要在本地计算机上生成一对密钥。大多数现代操作系统（Linux, macOS, Windows 10/11 及更高版本或通过 Git Bash/WSL）都内置了 OpenSSH 客户端工具集，包括 ssh-keygen 命令用于生成密钥。

1. 打开终端或命令行工具

  • Linux/macOS: 打开终端应用程序。
  • Windows:
    • 使用 Git Bash（推荐，如果您通过 Git 官网安装 Git）。
    • 使用 PowerShell (Windows 10 build 1803 或更高版本默认包含 OpenSSH 客户端)。
    • 使用 Windows Terminal 中的 WSL (Windows Subsystem for Linux)。

2. 运行 ssh-keygen 命令

在终端中输入以下命令：

bash
ssh-keygen -t ed25519 -C "[email protected]"

  • ssh-keygen: 生成 SSH 密钥对的命令。
  • -t ed25519: 指定密钥类型。ed25519 是一种较新的、更安全的、性能更好的非对称加密算法，推荐优先使用。如果您使用的是较旧的系统或需要广泛兼容性，也可以使用 -t rsa -b 4096 来生成一个 4096 位的 RSA 密钥，它也是安全的选择。RSA 密钥长度 (-b) 推荐至少 2048 位，4096 位更佳。
  • -C "[email protected]": 为公钥添加一个注释。这个注释通常是您的电子邮件地址，用于标识这个密钥的用途或所有者。在 GitLab 中，添加公钥时这个注释会显示出来，有助于您区分不同的密钥。请将 "[email protected]" 替换为您在 GitLab 中使用的电子邮件地址或其他有意义的标识。

按下回车键执行命令。

3. 按照提示操作

执行命令后，ssh-keygen 会提示您：

  • Enter file in which to save the key (…): 这是指定密钥文件保存的位置和名称。默认位置通常是用户主目录下的 .ssh 目录（例如 /home/youruser/.ssh/ 或 C:\Users\youruser\.ssh\）。默认文件名为 id_ed25519（如果使用 -t ed25519）或 id_rsa（如果使用 -t rsa）。
    • 对于大多数用户，直接按回车接受默认位置和文件名即可。这将把公钥保存为 ~/.ssh/id_ed25519.pub，私钥保存为 ~/.ssh/id_ed25519。
    • 如果您希望为不同的服务或目的生成多个密钥，可以在这里指定一个不同的文件名，例如 ~/.ssh/gitlab_ed25519。
  • Enter passphrase (empty for no passphrase): 这是设置私钥的密码（passphrase）。
    • 强烈建议设置一个密码。 即使您的私钥文件被泄露，没有密码对方也无法使用它。这个密码只在您首次使用私钥或将其添加到 SSH Agent 时输入。
    • 密码可以包含空格和特殊字符，与普通密码类似，越复杂越好。
    • 如果您选择不设置密码（直接按回车），私钥将没有额外保护，使用时也无需输入密码。这在某些自动化场景下可能需要，但会降低安全性。
  • Enter same passphrase again: 再次输入密码以确认。

输入密码（或留空）并确认后，ssh-keygen 会生成密钥对，并显示类似如下的信息：

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

至此，您的 SSH Key Pair 已成功生成并保存在指定的 .ssh 目录下。

4. 查看生成的密钥文件

您可以使用文件浏览器或命令行来查看生成的文件：

bash
ls -l ~/.ssh/

您会看到类似以下的文件：

-rw------- 1 youruser youruser 411 Feb 20 10:30 id_ed25519 # 这是您的私钥 (Private Key)
-rw-r--r-- 1 youruser youruser 96 Feb 20 10:30 id_ed25519.pub # 这是您的公钥 (Public Key)

注意文件的权限：
* 私钥文件 (id_ed25519 或 id_rsa) 的权限应该是 600 (-rw-------)，这意味着只有您（文件所有者）有读写权限，其他用户没有任何权限。这是为了保护您的私钥不被窥探。
* 公钥文件 (id_ed25519.pub 或 id_rsa.pub) 的权限通常是 644 (-rw-r--r--)，允许其他用户读取，这是可以接受的，因为公钥本身就是公开的。
* .ssh 目录的权限应该是 700 (drwx------)，确保只有您能够访问其中的文件。

如果权限不正确，可以使用 chmod 命令修正：

bash
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519 # 将此处的 filename 替换为您的私钥文件名
chmod 644 ~/.ssh/id_ed25519.pub # 将此处的 filename 替换为您的公钥文件名

第三部分：将公钥添加到 GitLab

生成密钥对后，您需要将 公钥 的内容添加到您的 GitLab 账户设置中。

1. 复制公钥内容

公钥文件 (.pub 结尾的文件，例如 id_ed25519.pub) 包含了一串文本，这就是您需要添加到 GitLab 的内容。

  • Linux/macOS: 使用 cat 命令读取并复制：
    bash
    cat ~/.ssh/id_ed25519.pub
    （请将 id_ed25519.pub 替换为您实际的公钥文件名）。然后将终端中显示的完整内容复制到剪贴板。确保复制的内容从 ssh-ed25519 或 ssh-rsa 开始，到注释结束。

  • Windows (Git Bash): 同样可以使用 cat 命令。
    bash
    cat ~/.ssh/id_ed25519.pub
    右键标记文本，然后右键复制。

  • Windows (PowerShell):
    powershell
    Get-Content $HOME\.ssh\id_ed25519.pub
    （请将 id_ed25519.pub 替换为您实际的公钥文件名）。复制显示的内容。

  • 文件浏览器： 您也可以直接使用文本编辑器打开 .ssh 目录下的 .pub 文件，然后复制其中的全部内容。

重要： 确保您复制的是 .pub 文件（公钥）的内容，而不是没有扩展名的私钥文件的内容！

2. 登录 GitLab 并添加公钥

  1. 打开您的网页浏览器，访问您的 GitLab 实例（例如 gitlab.com 或您公司内部的 GitLab 地址）。
  2. 使用您的用户名和密码登录。
  3. 点击页面右上角您的用户头像，然后选择 Settings (设置)。
  4. 在左侧导航菜单中，找到并点击 SSH Keys。

  5. 您会看到一个标题为 “Add an SSH key” 或类似的区域。

    • Key (密钥): 将您刚才复制的公钥内容粘贴到这个文本区域。确保粘贴的内容是完整且没有任何额外空格或换行符的。
    • Title (标题): 为您的 SSH Key 设置一个描述性标题。这个标题会帮助您识别这个密钥是用于哪台机器或什么用途的。例如：”My Laptop (Home)”, “Work Desktop”, “CI Runner Key” 等。默认情况下，GitLab 可能会自动从公钥的注释中提取信息作为标题，您也可以自己修改。
    • Expires At (过期时间): (可选，但推荐) 您可以为密钥设置一个过期日期。设置过期日期是一个很好的安全实践，它鼓励您定期更换密钥，降低了长期有效密钥被滥用的风险。如果设置为过去的时间，该密钥将立即失效。如果您不设置，密钥将永不过期（直到您手动删除）。
    • Usage type (使用类型): (GitLab 14.6 及更高版本) 您可以选择密钥的用途：
      • Authentication: 用于通过 SSH 协议认证到 GitLab，执行 Git 操作（clone, pull, push）。这是最常见的用途。
      • Signing: 用于验证提交（Commit）和标签（Tag）的 GPG 签名。如果您使用 SSH Key 进行 GPG 签名，则需要选择此项。一个密钥可以同时用于认证和签名，您需要添加两次，一次选择 Authentication，一次选择 Signing。对于本文讨论的 Git 操作，通常只需要 Authentication。

  6. 填写完信息后，点击 Add key (添加密钥) 按钮。

如果公钥格式正确，它将出现在您的 SSH Keys 列表中，显示标题、指纹 (Fingerprint) 和过期时间等信息。公钥指纹是一个短的标识符，可以用来快速验证您添加到 GitLab 的公钥是否是您期望添加的那个，可以通过在本地终端运行 ssh-keygen -lf ~/.ssh/id_ed25519.pub 来查看本地公钥的指纹并与 GitLab 页面上显示的进行对比。

第四部分：测试 SSH 连接

成功将公钥添加到 GitLab 后，您应该测试连接以确保一切正常。

1. 运行测试命令

在本地终端中，运行以下命令：

bash
ssh -T [email protected]

如果您的 GitLab 实例是自建的，请将 gitlab.com 替换为您的 GitLab 服务器域名或 IP 地址：

bash
ssh -T [email protected]

  • -T: 表示不分配伪终端。
  • git: 这是连接 GitLab 时使用的固定用户名。即使您的 GitLab 账号用户名不是 git，通过 SSH 连接时也总是使用 git@。GitLab 服务器通过您的 SSH 公钥来识别您是谁。
  • gitlab.com 或 your-gitlab-instance.com: 这是 GitLab 服务器的域名或 IP 地址。

2. 处理可能的提示

  • 首次连接提示: 如果是第一次通过 SSH 连接到该 GitLab 服务器，您可能会看到一个提示，询问您是否信任该主机的指纹：
    The authenticity of host 'gitlab.com (xxx.xxx.xxx.xxx)' can't be established.
    ED25519 key fingerprint is SHA256:...........................................
    Are you sure you want to continue connecting (yes/no)?
    这是 SSH 的安全机制，防止“中间人攻击”。您应该验证显示的指纹是否与 GitLab 文档或其他可信来源提供的指纹一致。如果一致，输入 yes 并按回车。该主机的指纹将被添加到您的 ~/.ssh/known_hosts 文件中，以后再次连接时就不会再提示了。

  • 输入私钥密码提示: 如果您在生成 SSH Key 时设置了密码，系统会提示您输入私钥的密码：
    Enter passphrase for key '/home/youruser/.ssh/id_ed25519':
    输入您设置的私钥密码并按回车。

3. 验证连接结果

  • 成功: 如果一切设置正确，您应该看到一个欢迎消息，表明您已成功通过 SSH 身份验证。这个消息通常类似这样：
    Welcome to GitLab, @your_gitlab_username!
    这里的 @your_gitlab_username 是您在 GitLab 中的用户名。收到这个消息意味着您的 SSH Key 认证已经成功，您现在可以使用 SSH URL 来克隆、拉取和推送代码了。

  • 失败: 如果连接失败，您可能会看到错误消息，例如 Permission denied (publickey)。请参考本文末尾的“常见问题与故障排除”部分进行排查。

4. 使用 SSH URL 克隆仓库

现在，您可以访问 GitLab 仓库页面，复制 SSH URL（通常以 git@ 开头），然后在本地使用 git clone 命令克隆仓库：

bash
git clone [email protected]:your-group/your-project.git

或者对于您的自建实例：

bash
git clone [email protected]:your-group/your-project.git

克隆过程应该无需输入密码即可完成（如果您已经通过 SSH Agent 添加了密钥或在测试连接时输入了私钥密码）。后续的 git pull 和 git push 命令也将通过 SSH 协议认证，无需密码。

第五部分：SSH Agent 的使用与管理

每次使用私钥时都输入密码可能会很麻烦，特别是对于频繁的 Git 操作。SSH Agent 就是为了解决这个问题而设计的。SSH Agent 是一个在后台运行的程序，它会缓存您的解密后的私钥。一旦您将私钥添加到 Agent 中（通常在首次使用或会话开始时输入一次密码），只要 Agent 仍在运行，后续需要使用该私钥的连接请求都会由 Agent 处理，无需再次输入密码。

1. 启动 SSH Agent

在大多数 Linux 和 macOS 系统中，当您打开一个新的终端会话时，SSH Agent 可能已经自动启动了。您可以通过检查环境变量来确认：

bash
echo "$SSH_AUTH_SOCK"

如果输出了一个套接字路径（例如 /tmp/ssh-xxxxxxxxx/agent.xxxx），说明 Agent 正在运行。如果输出为空，则 Agent 未启动。

如果 Agent 未启动，您可以手动启动它：

bash
eval "$(ssh-agent -s)"

这条命令会启动 Agent，并设置必要的环境变量。在 Windows 的 Git Bash 中，ssh-agent 也通常会自动启动或可以通过类似命令启动。PowerShell 中则有 Start-SshAgent 命令。

2. 将私钥添加到 Agent

Agent 启动后，您需要将您的私钥“添加”进去：

bash
ssh-add ~/.ssh/id_ed25519

（请将 id_ed25519 替换为您实际的私钥文件名）。

如果您的私钥有密码，ssh-add 会提示您输入密码。输入一次后，您的私钥就被加载到 Agent 中并缓存起来。

Enter passphrase for /home/youruser/.ssh/id_ed25519:
Identity added: /home/youruser/.ssh/id_ed25519 (/home/youruser/.ssh/id_ed25519)

现在，在当前终端会话（以及知道 SSH_AUTH_SOCK 变量的其他终端）中，只要 Agent 还在运行，您就可以使用这个私钥进行 SSH 连接，而无需再次输入密码。

3. 查看 Agent 中缓存的密钥

可以使用 ssh-add -l 命令查看当前 Agent 中已加载的密钥列表：

bash
ssh-add -l

输出会列出 Agent 中缓存的私钥指纹和对应的文件路径。

4. 从 Agent 中删除密钥

要从 Agent 中删除某个特定的密钥：

bash
ssh-add -d ~/.ssh/id_ed25519

要删除 Agent 中所有缓存的密钥：

bash
ssh-add -D

5. SSH Agent 的持久化

SSH Agent 默认只在当前的 shell 会话中有效。当您关闭终端窗口时，Agent 通常会停止运行，并且加载的密钥会被清空。为了避免每次打开新终端都要手动启动 Agent 和添加密钥，您需要设置 Agent 的持久化。

持久化 Agent 的方法因操作系统和 shell 的不同而有所差异：

  • Linux/macOS: 许多桌面环境和终端模拟器会自动启动 Agent。如果您的没有，可以将 eval "$(ssh-agent -s)" 命令添加到您的 shell 配置文件中（如 ~/.bashrc, ~/.zshrc, ~/.profile），并在 Agent 未运行时执行它。一些工具如 keychain 可以帮助更可靠地管理 Agent 的生命周期和密钥加载。
  • macOS: 系统自带的 SSH Agent (ssh-agent -l) 可以与 Keychain 集成，实现密钥密码的长期存储。使用 ssh-add -K 命令可以将密钥添加到 Agent 并存储到 Keychain 中。
  • Windows (Git Bash): Git Bash 通常会配置为自动启动 Agent。
  • Windows (PowerShell): 使用 Start-SshAgent 和 Add-SshKey 命令，结合 Windows Credential Manager 可以实现持久化。

具体的配置方法请参考您操作系统和 shell 的文档。

第六部分：管理多个 SSH Keys

有时您可能需要为不同的目的或不同的 GitLab 账户使用不同的 SSH Key。例如：
* 为工作和个人项目使用不同的密钥。
* 连接到不同的 GitLab 实例（例如 gitlab.com 和公司内部的 GitLab）。
* 为 CI/CD Runner 或自动化脚本使用专门的密钥。

在这种情况下，您可以生成多个密钥对（在生成时指定不同的文件名），然后使用 SSH 配置文件 (~/.ssh/config) 来告诉 SSH 客户端在连接到特定主机时使用哪个私钥。

1. 创建或编辑 SSH 配置文件

SSH 配置文件位于您的用户主目录下的 .ssh 目录中，文件名为 config (没有扩展名)。如果该文件不存在，您可以手动创建一个。

bash
touch ~/.ssh/config
chmod 600 ~/.ssh/config # 确保文件权限安全

使用文本编辑器打开 ~/.ssh/config 文件。

2. 配置不同的主机和密钥

配置文件使用 Host 关键字来定义不同的连接配置。一个典型的配置项包括 Host, HostName, User, IdentityFile 等。

例如，假设您有两个密钥：
* ~/.ssh/id_ed25519 (用于连接 gitlab.com 的个人账户)
* ~/.ssh/work_rsa (用于连接公司内部 GitLab 实例 my-gitlab.com 的工作账户)

您的 ~/.ssh/config 文件可以这样配置：

“`config

Default settings for all SSH connections (optional)

ForwardAgent yes # Automatically add keys to agent for connections

Configuration for gitlab.com

Host gitlab.com
HostName gitlab.com
User git # Always use ‘git’ user for GitLab SSH
IdentityFile ~/.ssh/id_ed25519 # Specify the private key to use
# AddKeysToAgent yes # Automatically add this key to agent when used

Configuration for internal GitLab instance

Host my-gitlab.com
HostName my-gitlab.com
User git # Always use ‘git’ user for GitLab SSH
IdentityFile ~/.ssh/work_rsa # Specify the private key to use
# AddKeysToAgent yes # Automatically add this key to agent when used

Optional: Create an alias for easier access to the internal instance

Host internal-gitlab
HostName my-gitlab.com
User git
IdentityFile ~/.ssh/work_rsa
# AddKeysToAgent yes

“`

解释：

  • Host gitlab.com: 定义一个配置块，应用于连接 gitlab.com 时。当您执行 ssh [email protected] 或使用 git clone [email protected]:... 时，SSH 客户端会查找名为 gitlab.com 的 Host 配置。
  • HostName gitlab.com: 指定实际要连接的服务器地址。通常与 Host 名称相同，但您可以使用不同的 Host 名称作为别名。
  • User git: 指定连接时使用的用户名。对于 GitLab，总是 git。
  • IdentityFile ~/.ssh/id_ed25519: 这是关键，指定连接此主机时应尝试使用的私钥文件路径。您可以列出多个 IdentityFile，SSH 客户端会按顺序尝试。
  • AddKeysToAgent yes: (可选) 如果设置为 yes，当使用此密钥进行身份验证成功后，SSH 客户端会自动将该私钥添加到正在运行的 SSH Agent 中。这省去了手动 ssh-add 的步骤。

配置完成后，当您使用 git clone [email protected]:... 时，SSH 客户端会自动使用 ~/.ssh/id_ed25519 私钥进行认证。当您使用 git clone [email protected]:... 时，会使用 ~/.ssh/work_rsa 私钥。如果您设置了别名 internal-gitlab，您也可以使用 git clone internal-gitlab:... 来连接到 my-gitlab.com 并使用指定的私钥。

重要： 当您在 GitLab 中添加公钥时，即使您在本地使用不同的密钥文件名（例如 work_rsa），您复制粘贴到 GitLab 的仍然是对应私钥的 公钥 (work_rsa.pub) 的内容。GitLab 只关心您上传的公钥，以及它是否与您连接时使用的私钥配对。

第七部分：最佳实践与安全性

  • 使用强密码保护私钥： 总是为您的私钥设置一个复杂且独特的密码。
  • 永不共享您的私钥： 您的私钥就像您的数字身份证明，泄露私钥等同于您的账户被完全控制。
  • 定期审查和轮换密钥： 建议定期（例如每年或每两年）生成新的密钥对并更新 GitLab 中的公钥，同时删除旧的密钥。这可以通过设置 GitLab 中密钥的过期时间来强制执行。
  • 设置 GitLab 中密钥的过期时间： 这是一个非常有用的安全功能，可以防止长期不用的密钥成为安全隐患。
  • 使用推荐的密钥类型和长度： 优先使用 Ed25519。如果使用 RSA，确保密钥长度至少为 4096 位。
  • 保护 .ssh 目录和密钥文件权限： 确保 .ssh 目录权限为 700，私钥文件权限为 600，公钥文件权限为 644 或更严格的 600。
  • 谨慎处理 known_hosts 文件： 当首次连接一个主机时，SSH 会记录其指纹到 ~/.ssh/known_hosts。如果未来连接时主机指纹发生变化（通常是因为服务器升级或重装），SSH 会发出警告。请务必调查原因，确认不是中间人攻击后再更新 known_hosts 文件（SSH 会提示您如何操作）。
  • 限制 SSH Agent 的生命周期： 如果您在不安全的网络环境中使用 Agent，考虑限制其生命周期或在不需要时将其关闭。
  • 不要将私钥硬编码到脚本中： 使用 SSH Agent 或其他安全的凭据管理方式。

第八部分：常见问题与故障排除

1. Permission denied (publickey).

这是最常见的错误，意味着 SSH 服务器（GitLab）没有接受您的公钥进行身份验证。原因可能有很多：

  • 公钥未添加到 GitLab： 检查您的 GitLab 账户设置 -> SSH Keys 页面，确认您使用的公钥已成功添加。
  • 添加了错误的公钥： 确认您复制到 GitLab 的内容是您的私钥文件 (.pub 结尾) 对应的公钥内容，而不是私钥本身或其他文件的内容。可以通过在本地使用 ssh-keygen -lf your_public_key.pub 查看公钥指纹，并与 GitLab 页面上显示的指纹进行对比。
  • 使用了错误的私钥： 检查您的本地 .ssh 目录，确认您正在使用的私钥文件 (例如 id_ed25519) 与添加到 GitLab 的公钥 (id_ed25519.pub) 是配对的。如果使用了多个密钥，检查 ~/.ssh/config 文件是否配置正确，确保连接到 GitLab 时使用了正确的 IdentityFile。
  • 私钥文件权限不正确： 私钥文件 (id_ed25519 等) 的权限必须是 600。使用 chmod 600 ~/.ssh/your_private_key 修正。.ssh 目录权限应为 700 (chmod 700 ~/.ssh)。
  • SSH Agent 问题： 如果您的私钥有密码，但 Agent 没有运行或没有加载该私钥，SSH 客户端会提示输入密码。如果Agent正在运行但没有加载密钥，或者您期望Agent处理但它未能工作，也可能导致认证失败。尝试手动 ssh-add your_private_key 并输入密码，然后重试连接。
  • 连接地址错误： 确保您使用 [email protected] 或 [email protected] 进行连接，而不是您的 GitLab 用户名或其他地址。
  • 防火墙阻止： 检查本地或网络防火墙是否阻止了 SSH 端口 22 的出站连接。

诊断技巧： 使用 -v 或 -vvv 选项运行 SSH 命令以获取更详细的调试输出：

bash
ssh -vvv -T [email protected]
仔细查看输出，查找 Authentications that can continue: publickey 或类似信息，以及尝试使用的密钥文件路径。

2. Agent admitted failure to sign using the key.

这通常意味着 SSH Agent 正在运行，但它没有加载您尝试使用的那个私钥。

  • 密钥未添加到 Agent： 运行 ssh-add -l 查看 Agent 中已加载的密钥列表。如果您的密钥不在列表中，使用 ssh-add your_private_key 将其添加到 Agent。
  • Agent 未正确启动： 确保 Agent 正在运行并且环境变量 SSH_AUTH_SOCK 已正确设置。

3. Host key verification failed.

这通常发生在您首次连接一个主机时，或者当您之前连接过的主机的 SSH 密钥指纹发生了变化时。

  • 首次连接： 如果这是您第一次连接，并且您确定主机是可信的，按照提示输入 yes 并回车即可。
  • 主机密钥变化： 如果您之前连接过该主机，并且 SSH 警告指纹不匹配，这可能表示主机确实发生了变化（例如服务器重装），或者可能存在中间人攻击。在确认安全的情况下，您需要编辑 ~/.ssh/known_hosts 文件，删除与该主机相关的旧条目，然后再次连接时SSH会提示您添加新的指纹。SSH 客户端通常会告诉您具体要删除 known_hosts 文件中的哪一行。

4. GitLab 页面显示密钥指纹，但连接仍然失败

确保您在 GitLab 中添加的公钥内容是完整的，并且没有额外的空格或换行符。复制粘贴时有时容易出错。重新从您的 .pub 文件复制完整内容并尝试在 GitLab 中删除旧密钥并重新添加。

5. 每次 Git 操作都需要输入私钥密码

这意味着您没有正确使用 SSH Agent，或者 Agent 没有设置为持久运行并加载您的私钥。

  • 确认 Agent 正在运行 (echo "$SSH_AUTH_SOCK")。
  • 确认您的私钥已添加到 Agent (ssh-add -l)。
  • 如果 Agent 在终端关闭后失效，请设置 Agent 的持久化（参考上面的 SSH Agent 持久化部分）。

结论

GitLab SSH Key 提供了一种强大、安全且便捷的方式来与您的代码仓库进行交互。通过生成密钥对、将公钥添加到 GitLab、并合理利用 SSH Agent，您可以实现无密码的 Git 操作，极大地提升开发效率和工作流程的流畅性。

尽管初始设置可能需要一些步骤，但一旦配置完成，SSH Key 的优势将立刻显现。遵循本文提供的详细指南、最佳实践和故障排除技巧，您将能够自信地管理您的 GitLab SSH Keys，为您的代码协作之路奠定坚实的安全基础。熟练掌握 SSH Key 的使用，是每一位使用 Git 和 GitLab 的开发者都应具备的重要技能。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部