全面解析 GitLab SSH Key 配置 – wiki大全

作者： /

Here’s a detailed article on configuring GitLab SSH keys:

全面解析 GitLab SSH Key 配置

在使用 GitLab 进行代码协作和版本控制时，SSH Key 提供了一种安全、高效的认证方式，免除了每次操作都需要输入用户名和密码的繁琐。本文将详细解析 GitLab SSH Key 的配置过程，从生成密钥对到添加到 GitLab 账户，再到验证连接，助您轻松上手。

1. 为什么使用 SSH Key？

在深入配置之前，我们首先了解一下为什么 SSH Key 是 GitLab（以及其他 Git 托管服务）推荐的认证方式：

  • 安全性更高： SSH Key 采用非对称加密技术，由一对密钥组成：公钥（Public Key）和私钥（Private Key）。公钥存储在 GitLab 服务器上，私钥保存在本地计算机上。认证时，双方通过加密握手验证身份，私钥永不离开本地，大大降低了密码泄露的风险。
  • 便捷性更强： 一旦配置完成，您在执行 git push、git pull 等操作时，无需重复输入用户名和密码，提升了开发效率。
  • 自动化友好： 对于自动化脚本和 CI/CD 流程，SSH Key 认证是标准的做法，因为它无需人工干预。

2. SSH Key 的工作原理

简单来说，当您尝试通过 SSH 协议连接 GitLab 时：

  1. 您的本地客户端会向 GitLab 服务器发送连接请求，并出示您的公钥。
  2. GitLab 服务器会检查其存储的所有公钥，查找与您提供的公钥匹配的记录。
  3. 如果找到匹配项，GitLab 服务器会使用该公钥对一个随机字符串进行加密，并将其发送回您的客户端。
  4. 您的客户端会使用本地保存的私钥对这个加密字符串进行解密。
  5. 如果解密成功，客户端将解密后的字符串发送回服务器。
  6. 服务器验证解密后的字符串是否与原始字符串一致。如果一致，则认证成功，连接建立。

整个过程私钥始终保存在本地，保证了安全性。

3. 生成 SSH Key

如果您之前没有生成过 SSH Key，或者想为 GitLab 创建一个新的专用密钥对，请按照以下步骤操作：

步骤 3.1：检查现有的 SSH Key

在生成新的 SSH Key 之前，最好检查一下您的本地计算机是否已经存在 SSH Key。打开您的终端（Linux/macOS）或 Git Bash（Windows），输入以下命令：

bash
ls -al ~/.ssh

此命令会列出 ~/.ssh 目录下的所有文件。如果您看到名为 id_rsa.pub、id_ecdsa.pub 或 id_ed25519.pub 的文件（通常 *.pub 结尾的是公钥文件），则表示您可能已经有了一个 SSH Key。

  • 如果已存在： 您可以选择使用现有的密钥对，跳过生成步骤，直接进入步骤 3.3 查看公钥内容。或者，如果您希望为 GitLab 创建一个独立的密钥，可以继续下一步生成新的密钥对，并在生成时指定不同的文件名。
  • 如果不存在： 请继续下一步生成新的 SSH Key。

步骤 3.2：生成新的 SSH Key

在终端或 Git Bash 中，执行以下命令来生成一个新的 SSH Key。GitLab 推荐使用 Ed25519 算法，因为它提供强大的安全性和较小的密钥文件大小。如果您需要更广泛的兼容性，也可以使用 RSA 算法。

推荐使用 Ed25519 算法：

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

或者使用 RSA 算法（传统且兼容性好）：

bash
ssh-keygen -t rsa -b 4096 -C "[email protected]"

命令参数说明：

  • -t ed25519 或 -t rsa: 指定加密算法为 Ed25519 或 RSA。
  • -b 4096: 仅对 RSA 算法有效，指定密钥长度为 4096 位，增强安全性。
  • -C "[email protected]": 为您的密钥添加一个注释，通常是您的邮箱地址。这有助于您识别不同的密钥，特别是当您有多个密钥时。

执行命令后，系统会提示您：

  1. Enter file in which to save the key (~/.ssh/id_ed25519):
    这是密钥对的保存路径和文件名。默认情况下，它会保存在 ~/.ssh/ 目录下，并以 id_ed25519（私钥）和 id_ed25519.pub（公钥）命名。

    • 如果这是您的第一个密钥，直接按回车键使用默认路径即可。
    • 如果您已经有一个密钥，并且想创建新密钥而不想覆盖旧密钥，您需要为新密钥指定一个不同的文件名，例如 ~/.ssh/id_gitlab_ed25519。

  2. Enter passphrase (empty for no passphrase):
    这是设置密钥的密码（passphrase）。

    • 强烈建议设置密码：即使您的私钥被盗，攻击者也无法直接使用，增加了安全性。每次使用密钥时都需要输入密码（或者在会话开始时输入一次并由 SSH 代理缓存）。
    • 如果不设置密码：直接按回车键两次，不输入任何内容。这样使用密钥时将无需输入密码，但安全性较低。

生成成功后，您会看到类似“Your identification has been saved in /home/you/.ssh/id_ed25519”和“Your public key has been saved in /home/you/.ssh/id_ed25519.pub”的信息。

步骤 3.3：查看公钥内容

生成密钥后，您需要获取公钥的内容，以便将其添加到 GitLab。
在终端或 Git Bash 中，使用 cat 命令查看公钥文件的内容：

bash
cat ~/.ssh/id_ed25519.pub
（如果您在生成时指定了不同的文件名，请替换为您的文件名，例如 cat ~/.ssh/id_gitlab_ed25519.pub）

这会输出一长串以 ssh-ed25519 或 ssh-rsa 开头，并以您邮箱结尾的字符串。请完整复制这个字符串，包括开头的 ssh-ed25519 或 ssh-rsa，以及结尾的邮箱。

4. 将公钥添加到 GitLab

接下来，您需要将复制的公钥添加到您的 GitLab 账户中。

  1. 登录 GitLab： 使用您的浏览器访问 GitLab 网站并登录您的账户。
  2. 导航到 SSH Keys 设置：
    • 点击页面右上角的您的用户头像。
    • 选择 Preferences。
    • 在左侧导航栏中选择 SSH Keys。
  3. 添加 SSH Key：
    • 在 “Key” 文本框中，粘贴您之前复制的公钥内容。
    • 在 “Title” 文本框中，为您的 SSH Key 输入一个有意义的名称（例如：”My Laptop”、”Work Machine” 或 “CI/CD Server”），方便您识别。
    • 在 “Expires At” 字段中，您可以选择为密钥设置一个过期日期。这是一个良好的安全实践，可以定期更新密钥。如果您不设置，密钥将永不过期。
    • 点击 Add key 按钮。

成功添加后，您会在 SSH Keys 列表中看到您新添加的密钥。

5. 配置 SSH 代理 (ssh-agent)

如果您为私钥设置了密码（passphrase），每次使用密钥时都需要输入。为了避免这种重复操作，您可以使用 ssh-agent 来缓存您的密码。

步骤 5.1：启动 ssh-agent

通常，ssh-agent 在 Linux/macOS 上会自动启动。如果您的 ssh-agent 没有运行，或者在 Windows 上使用 Git Bash，您可以手动启动它：

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

步骤 5.2：将私钥添加到 ssh-agent

将您的私钥添加到 ssh-agent 中：

bash
ssh-add ~/.ssh/id_ed25519
（如果您使用了不同的文件名，请替换为您的私钥文件名，例如 ssh-add ~/.ssh/id_gitlab_ed25519）

此时，系统会提示您输入私钥的密码。输入一次后，您的密码就会被 ssh-agent 缓存起来，在当前的会话中，您无需再次输入密码即可使用该密钥。

提示： 为了让 ssh-agent 在系统启动时自动加载密钥，您可能需要将 eval "$(ssh-agent -s)" 和 ssh-add 命令添加到您的 shell 配置文件（如 ~/.bashrc, ~/.zshrc, ~/.profile）中。

6. 验证 SSH 连接

完成上述步骤后，是时候验证您的 SSH 连接是否配置成功了。

在终端或 Git Bash 中，执行以下命令：

bash
ssh -T [email protected]

首次连接时，您可能会看到一个类似如下的提示：

The authenticity of host 'gitlab.com (XX.XX.XX.XX)' can't be established.
ED25519 key fingerprint is SHA256:*******************************************.
Are you sure you want to continue connecting (yes/no)?

这是因为您的计算机第一次连接到 gitlab.com，系统会询问您是否信任该主机。输入 yes 并按回车键。这个主机指纹会被添加到您的 ~/.ssh/known_hosts 文件中，下次连接时就不会再询问了。

如果一切配置正确，您会看到类似以下的信息：

Welcome to GitLab, @your_username!

这表示您已成功通过 SSH Key 认证连接到 GitLab。如果您收到错误消息，请检查以下常见问题。

7. 常见问题与排查

  • “Permission denied (publickey).”

    • 公钥未正确添加到 GitLab： 确保您复制的是公钥文件（.pub 结尾），并且内容完整无误地粘贴到了 GitLab。
    • GitLab 账户与公钥不匹配： 确保您添加公钥的 GitLab 账户是您正在尝试访问仓库的账户。
    • 私钥权限不正确： 私钥文件（例如 id_ed25519）的权限必须严格限制。在 Linux/macOS 上，确保私钥文件的权限是 600（即只有所有者有读写权限），公钥文件的权限是 644。
      bash
      chmod 600 ~/.ssh/id_ed25519
      chmod 644 ~/.ssh/id_ed25519.pub
    • ssh-agent 没有运行或没有加载私钥： 确认 ssh-agent 正在运行，并且您的私钥已通过 ssh-add 命令添加到其中。
    • 使用了错误的私钥： 如果您有多个私钥，确保 SSH 客户端正在尝试使用与 GitLab 上注册的公钥对应的私钥。您可以尝试在 ~/.ssh/config 文件中明确指定私钥路径。

  • “Agent admitted failure to sign using the key.”

    • 这通常意味着您尝试使用一个需要密码的私钥，但您没有将其添加到 ssh-agent 中，或者 ssh-agent 中的密码已过期。重新运行 ssh-add 命令并输入密码。

  • ~/.ssh/config 文件配置：
    如果您有多个 SSH Key 或需要为不同的 Git 托管服务使用不同的密钥，您可以在 ~/.ssh/config 文件中进行配置。
    创建一个名为 config 的文件（如果不存在）：

    bash
    touch ~/.ssh/config
    chmod 600 ~/.ssh/config # 设置正确权限

    编辑 ~/.ssh/config 文件，添加如下内容：

    “`

    Default GitLab

    Host gitlab.com
    Hostname gitlab.com
    IdentityFile ~/.ssh/id_ed25519 # 替换为你的私钥文件路径
    User git

    If you have a second GitLab account or another key

    Host gitlab.com-personal
    Hostname gitlab.com
    IdentityFile ~/.ssh/id_gitlab_personal_ed25519 # 替换为你的另一个私钥文件路径
    User git
    “`

    然后，在克隆或操作仓库时，您可以这样使用：

    “`bash

    使用默认 key

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

    使用 personal key

    git clone [email protected]:your-group/your-personal-repo.git
    ``
    请注意，当您使用    gitlab.com-personal` 这样的别名时，GitLab 仓库的 URL 也需要相应修改。

8. 将 Git 仓库协议更改为 SSH

如果您之前使用的是 HTTPS 协议克隆的仓库，现在想切换到 SSH 协议，可以在本地仓库目录中执行以下命令：

bash
cd /path/to/your/repo
git remote set-url origin [email protected]:your-group/your-repo.git

请确保将 your-group/your-repo.git 替换为您的实际仓库路径。

总结

配置 GitLab SSH Key 是提升开发体验和安全性的重要一步。通过本文的详细指导，您应该已经能够顺利完成 SSH Key 的生成、添加和验证。牢记密钥的安全性，并善用 ssh-agent 和 ~/.ssh/config 来管理您的密钥，将使您的 GitLab 工作流更加高效和顺畅。

滚动至顶部