GitLab SSH Key 教程：从生成到使用 – wiki大全

作者： /

GitLab SSH Key 教程：从生成到使用

GitLab 是一个流行的基于 Git 的代码托管平台。为了安全、高效地与 GitLab 仓库进行交互，通常推荐使用 SSH (Secure Shell) 密钥对进行身份验证。本教程将详细指导您如何生成 SSH 密钥、将其添加到 ssh-agent、上传到 GitLab，并最终通过 SSH 使用 GitLab。

1. 什么是 SSH 密钥以及为什么要使用它？

SSH 密钥对由一个私钥和一个公钥组成。它们共同工作，无需每次都输入用户名和密码即可安全地验证您的身份。

  • 私钥 (Private Key)：保存在您的本地计算机上，必须严格保密。
  • 公钥 (Public Key)：您可以将其分享给 GitLab 等服务。

当您尝试连接 GitLab 时，GitLab 会使用您的公钥验证您是否拥有匹配的私钥。这种方式比 HTTPS 和用户名/密码更安全，也更便捷，尤其是在自动化脚本或频繁操作时。

2. 生成新的 SSH 密钥对

在生成新密钥之前，最好检查一下是否已经存在 SSH 密钥。

2.1 检查现有 SSH 密钥

打开您的终端 (macOS/Linux) 或 Git Bash (Windows)，然后运行以下命令：

bash
ls -al ~/.ssh

如果输出中包含 id_rsa.pub、id_ecdsa.pub 或 id_ed25519.pub 等文件，则表示您可能已经有了一个 SSH 密钥。如果您想使用现有的密钥，可以跳过密钥生成步骤。如果您想生成一个新的密钥，或者没有现有密钥，请继续。

2.2 生成新的 SSH 密钥

如果您没有现有密钥或希望创建一个新密钥，可以使用 ssh-keygen 命令。推荐使用 Ed25519 算法，因为它比 RSA 更安全且速度更快。

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

  • -t ed25519：指定密钥类型为 Ed25519。您也可以使用 rsa -b 4096 生成一个 4096 位的 RSA 密钥，如果您的系统不支持 Ed25519。
  • -C "[email protected]"：为您的密钥添加一个有用的注释，通常是您的电子邮件地址，这有助于识别密钥的用途。

当系统提示您保存密钥文件时，可以直接按回车键接受默认路径 (~/.ssh/id_ed25519)：

Enter file in which to save the key (~/.ssh/id_ed25519): [Press Enter]

接下来，系统会提示您输入一个密码 (passphrase)。这是一个可选但强烈推荐的步骤。为您的私钥设置一个强大的密码可以增加安全性。每次使用密钥时，您可能需要输入此密码。如果您不想设置密码，可以直接按回车键两次。

Enter passphrase (empty for no passphrase): [Your Passphrase]
Enter same passphrase again: [Your Passphrase]

生成成功后，您会看到类似以下输出：

Your identification has been saved in /home/user/.ssh/id_ed25519
Your public key has been saved in /home/user/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx [email protected]
The key's randomart image is:
+--[ED25519 256]--+
| .+=. |
| ...o + |
| . .o = o |
| . . B+ * |
| . o S X= . |
| . = O |
| . . |
| . |
| E |
+----[SHA256]-----+

现在，您的 SSH 密钥对已生成并存储在 ~/.ssh/ 目录下。私钥是 id_ed25519 (或 id_rsa)，公钥是 id_ed25519.pub (或 id_rsa.pub)。

3. 将 SSH 密钥添加到 ssh-agent

ssh-agent 是一个程序，它在后台运行，保存您的私钥，这样您就不必每次使用 SSH 密钥时都输入密码。

3.1 启动 ssh-agent

首先，确保 ssh-agent 正在运行：

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

您应该看到类似 Agent pid 1234 的输出。

3.2 将您的私钥添加到 ssh-agent

现在，将您的私钥添加到 ssh-agent。如果您使用了默认文件名，则命令如下：

bash
ssh-add ~/.ssh/id_ed25519

如果您设置了密码，系统会提示您输入密码。

注意 (Windows 用户)：如果您使用的是 Git Bash，ssh-add 命令应该会正常工作。如果您在 Windows Subsystem for Linux (WSL) 中操作，请确保您在 WSL 环境中启动 ssh-agent 并添加密钥。

4. 将公钥添加到 GitLab

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

4.1 复制您的公钥内容

  • macOS/Linux:
    bash
    cat ~/.ssh/id_ed25519.pub
    或者，使用 pbcopy (macOS) 或 xclip (Linux) 直接复制到剪贴板：
    bash
    pbcopy < ~/.ssh/id_ed25519.pub # macOS
    xclip -selection clipboard < ~/.ssh/id_ed25519.pub # Linux (可能需要安装 xclip)
  • Windows (Git Bash):
    bash
    cat ~/.ssh/id_ed25519.pub
    然后手动复制终端输出的内容。
    或者：
    bash
    clip < ~/.ssh/id_ed25519.pub

4.2 登录 GitLab 并添加公钥

  1. 打开您的 Web 浏览器，登录到 GitLab 账户。
  2. 点击右上角的用户头像，然后选择 Preferences (偏好设置)。
  3. 在左侧导航栏中，点击 SSH Keys (SSH 密钥)。
  4. 在 Key (密钥) 文本区域中，粘贴您之前复制的公钥内容。
  5. 在 Title (标题) 字段中，为此密钥输入一个描述性名称 (例如：“My Laptop SSH Key” 或 “Work PC”)。
  6. 您可以设置一个可选的 Expiration date (过期日期)。
  7. 点击 Add key (添加密钥)。

现在，您的公钥已经成功添加到 GitLab 账户中。

5. 测试 SSH 连接

为了确认您的 SSH 连接设置正确，您可以使用以下命令测试与 GitLab 的连接：

bash
ssh -T [email protected]

当您第一次连接时，系统可能会询问您是否信任 gitlab.com 的主机。输入 yes 并按回车。

如果连接成功，您会看到类似以下消息：

Welcome to GitLab, @your_username!

如果出现错误，请检查以下几点：
* 公钥是否正确添加到 GitLab？
* 私钥是否添加到 ssh-agent？
* ~/.ssh/config 文件是否有任何冲突设置？

6. 使用 SSH 与 GitLab 仓库交互

一旦 SSH 设置完成并通过测试，您就可以开始使用 SSH 克隆和操作 GitLab 仓库了。

6.1 克隆仓库

在 GitLab 上，导航到您想要克隆的仓库页面。通常，在仓库主页的右上角会有一个蓝色的 “Clone” (克隆) 按钮。点击它，然后选择 “Clone with SSH” (使用 SSH 克隆) 选项，复制提供的 URL。

然后，在您的终端中执行以下命令：

bash
git clone [email protected]:your-username/your-project.git
将 your-username/your-project.git 替换为您实际的仓库 SSH URL。

6.2 推送和拉取代码

使用 SSH 克隆的仓库，后续的 git pull、git push 等操作都将自动通过 SSH 进行身份验证，无需再次输入用户名和密码。

bash
git add .
git commit -m "My changes"
git push origin main # 或您的主分支名称

7. 故障排除

  • Permission denied (publickey):
    • 确保您的公钥已添加到 GitLab。
    • 确保私钥已添加到 ssh-agent (ssh-add -l 可以列出已加载的密钥)。
    • 检查 ~/.ssh/ 目录和私钥文件的权限。私钥 (id_ed25519 或 id_rsa) 应该只有所有者有读写权限 (chmod 600 ~/.ssh/id_ed25519)。
    • 尝试在 ~/.ssh/config 文件中为 GitLab 添加配置：
      Host gitlab.com
      AddKeysToAgent yes
      UseKeychain yes # macOS specific, if you want to use the macOS keychain
      IdentityFile ~/.ssh/id_ed25519 # 或您的私钥路径
  • Agent admitted failure to sign using the key: 这通常意味着 ssh-agent 没有加载您的密钥，或者您输入了错误的密码。尝试重新运行 ssh-add ~/.ssh/id_ed25519。
  • 使用不同的 SSH 密钥: 如果您有多个密钥并希望为特定仓库使用其中一个，您可以在 ~/.ssh/config 文件中进行配置，或者在使用 git clone 时临时指定密钥 (GIT_SSH_COMMAND="ssh -i ~/.ssh/other_key" git clone ...)。

8. 总结

通过本教程，您应该已经成功地生成了 SSH 密钥对，将其配置到 ssh-agent，并上传到 GitLab。现在，您可以享受更安全、更便捷的 GitLab 代码管理体验。记住，始终保护好您的私钥，不要将其分享给任何人！

希望这篇教程对您有所帮助！

滚动至顶部