{{< details >}}

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

Git 是一个分布式版本控制系统，这意味着您可以在本地工作，然后将您的更改共享或 推送 到服务器。在这种情况下，您推送到的服务器是极狐GitLab。

极狐GitLab 使用 SSH 协议与 Git 进行安全通信。当您使用 SSH 密钥对极狐GitLab 远程服务器进行身份验证时，您无需每次都提供用户名和密码。

什么是 SSH 密钥

SSH 使用两个密钥，一个公钥和一个私钥。

  • 公钥可以分发。
  • 私钥应该受到保护。

上传公钥不会泄露机密数据。当您需要复制或上传 SSH 公钥时，请确保不要意外地复制或上传私钥。

您可以使用您的私钥来签署提交，这使您的极狐GitLab 使用和数据更加安全。然后，任何使用您的公钥的人都可以验证此签名。

先决条件

要使用 SSH 与极狐GitLab 通信，您需要：

  • OpenSSH 客户端，预安装在 GNU/Linux、macOS 和 Windows 10 上。
  • SSH 版本 6.5 或更高版本。较早版本使用 MD5 签名，这不安全。

要查看系统上安装的 SSH 版本，请运行 ssh -V。

支持的 SSH 密钥类型

要与极狐GitLab 通信，您可以使用以下 SSH 密钥类型：

管理员可以限制允许的密钥及其最小长度。

ED25519 SSH 密钥

使用 Go 实际加密密钥比 RSA 密钥更安全和高效。

OpenSSH 6.5 于 2014 年引入了 ED25519 SSH 密钥，应该可以在大多数操作系统上使用。

{{< alert type=”note” >}}

ED25519 密钥可能无法完全支持所有 FIPS 系统。

{{< /alert >}}

ED25519_SK SSH 密钥

要在极狐GitLab 上使用 ED25519_SK SSH 密钥，您的本地客户端和极狐GitLab 服务器必须安装 OpenSSH 8.2 或更高版本。

ECDSA_SK SSH 密钥

要在极狐GitLab 上使用 ECDSA_SK SSH 密钥，您的本地客户端和极狐GitLab 服务器必须安装 OpenSSH 8.2 或更高版本。

RSA SSH 密钥

{{< history >}}

  • 在极狐GitLab 16.3 中更改了最大 RSA 密钥长度。

{{< /history >}}

现有文档建议 ED25519 比 RSA 更安全。

默认密钥大小取决于您的 ssh-keygen 版本。有关详细信息，请查看已安装的 ssh-keygen 命令的 man 页面。

查看是否已有 SSH 密钥对

在创建密钥对之前，请查看是否已经存在密钥对。

  1. 进入您的主目录。
  2. 进入 .ssh/ 子目录。如果 .ssh/ 子目录不存在，您可能不在主目录中，或者您之前没有使用过 ssh。在后一种情况下，您需要生成 SSH 密钥对。

  3. 查看是否存在以下格式的文件：

    算法 公钥 私钥
    ED25519（首选） id_ed25519.pub id_ed25519
    ED25519_SK id_ed25519_sk.pub id_ed25519_sk
    ECDSA_SK id_ecdsa_sk.pub id_ecdsa_sk
    RSA（至少 2048 位密钥大小） id_rsa.pub id_rsa
    DSA（已弃用） id_dsa.pub id_dsa
    ECDSA id_ecdsa.pub id_ecdsa

生成 SSH 密钥对

如果您没有现有的 SSH 密钥对，请生成一个新的密钥对：

  1. 打开终端。

  2. 运行 ssh-keygen -t 后跟密钥类型和可选评论。此评论包含在创建的 .pub 文件中。您可能希望使用电子邮件地址作为评论。

    例如，对于 ED25519：

    ssh-keygen -t ed25519 -C "<comment>"

    对于 2048 位 RSA：

    ssh-keygen -t rsa -b 2048 -C "<comment>"

  3. 按 Enter。显示类似于以下的输出：

    Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):

  4. 接受建议的文件名和目录，除非您正在生成部署密钥或希望保存到存储其他密钥的特定目录。

    您还可以将 SSH 密钥对专用于特定主机。

  5. 指定密码短语：

    Enter passphrase (empty for no passphrase):
Enter same passphrase again:

    显示确认，包括关于文件存储位置的信息。

生成了公钥和私钥。将公钥添加到您的极狐GitLab 账户并确保私钥安全。

配置 SSH 指向不同的目录

如果您没有将 SSH 密钥对保存到默认目录，请将您的 SSH 客户端配置为指向存储私钥的目录。

  1. 打开终端并运行此命令：

    eval $(ssh-agent -s)
ssh-add <directory to private SSH key>

  2. 在 ~/.ssh/config 文件中保存这些设置。例如：

    # JihuLab.com
Host gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/gitlab_com_rsa

# 私有化极狐GitLab 实例
Host gitlab.company.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/example_com_rsa

公有 SSH 密钥必须是极狐GitLab 独有的，因为它们绑定到您的账户。您的 SSH 密钥是您使用 SSH 推送代码时唯一的标识符。它必须唯一映射到单个用户。

更新您的 SSH 密钥密码短语

您可以更新 SSH 密钥的密码短语：

  1. 打开终端并运行此命令：

    ssh-keygen -p -f /path/to/ssh_key

  2. 在提示处输入密码短语，然后按 Enter。

将您的 RSA 密钥对升级为更安全的格式

如果您的 OpenSSH 版本介于 6.5 和 7.8 之间，您可以通过打开终端并运行以下命令，将您的私有 RSA SSH 密钥保存为更安全的 OpenSSH 格式：

ssh-keygen -o -f ~/.ssh/id_rsa

或者，您可以使用以下命令生成具有更安全加密格式的新 RSA 密钥：

ssh-keygen -o -t rsa -b 4096 -C "<comment>"

为 FIDO2 硬件安全密钥生成 SSH 密钥对

要生成 ED25519_SK 或 ECDSA_SK SSH 密钥，您必须使用 OpenSSH 8.2 或更高版本：

  1. 将硬件安全密钥插入您的计算机。
  2. 打开终端。

  3. 运行 ssh-keygen -t 后跟密钥类型和可选评论。此评论包含在创建的 .pub 文件中。您可能希望使用电子邮件地址作为评论。

    例如，对于 ED25519_SK：

    ssh-keygen -t ed25519-sk -C "<comment>"

    对于 ECDSA_SK：

    ssh-keygen -t ecdsa-sk -C "<comment>"

    如果您的安全密钥支持 FIDO2 常驻密钥，您可以在创建 SSH 密钥时启用此功能：

    ssh-keygen -t ed25519-sk -O resident -C "<comment>"

    -O resident 表示密钥应存储在 FIDO 认证器本身上。常驻密钥更容易导入到新计算机，因为它可以直接从安全密钥加载通过 ssh-add -K 或 ssh-keygen -K。

  4. 按 Enter。显示类似于以下的输出：

    Generating public/private ed25519-sk key pair.
You may need to touch your authenticator to authorize key generation.

  5. 触摸硬件安全密钥上的按钮。

  6. 接受建议的文件名和目录：

    Enter file in which to save the key (/home/user/.ssh/id_ed25519_sk):

  7. 指定密码短语：

    Enter passphrase (empty for no passphrase):
Enter same passphrase again:

    显示确认，包括关于文件存储位置的信息。

生成了公钥和私钥。将公钥添加到您的极狐GitLab 账户。

使用密码管理器生成 SSH 密钥对

使用 1Password 生成 SSH 密钥对

您可以使用 1Password 和 1Password 浏览器扩展来：

  • 自动生成新的 SSH 密钥。
  • 使用您 1Password 保险库中现有的 SSH 密钥进行极狐GitLab 身份验证。
  1. 登录极狐GitLab。
  2. 在左侧边栏中，选择您的头像。
  3. 选择 编辑个人资料。
  4. 在左侧边栏中，选择 SSH 密钥。
  5. 选择 添加新密钥。
  6. 选择 密钥，您应该看到 1Password 助手出现。
  7. 选择 1Password 图标并解锁 1Password。
  8. 然后您可以选择 创建 SSH 密钥 或选择现有 SSH 密钥来填写公钥。
  9. 在 标题 框中输入描述，例如 工作笔记本 或 家庭工作站。
  10. 可选。选择密钥的 使用类型。它可以用于 身份验证 或 签名 或两者。身份验证和签名 是默认值。
  11. 可选。更新 到期日期以修改默认到期日期。
  12. 选择 添加密钥。

将 SSH 密钥添加到您的极狐GitLab 账户

{{< history >}}

  • 在极狐GitLab 15.4 中引入了建议的默认密钥到期日期。
  • 在极狐GitLab 15.7 中添加了 SSH 密钥的使用类型。

{{< /history >}}

要使用 SSH 与极狐GitLab 通信，请将您的公钥复制到您的极狐GitLab 账户：

  1. 复制您的公钥文件的内容。您可以手动执行此操作或使用脚本。 例如，将 ED25519 密钥复制到剪贴板：

    macOS

    tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

    Linux（需要 xclip 包）

    xclip -sel clip < ~/.ssh/id_ed25519.pub

    Git Bash on Windows

    cat ~/.ssh/id_ed25519.pub | clip

    将 id_ed25519.pub 替换为您的文件名。例如，对于 RSA，请使用 id_rsa.pub。

  2. 登录极狐GitLab。
  3. 在左侧边栏中，选择您的头像。
  4. 选择 编辑个人资料。
  5. 在左侧边栏中，选择 SSH 密钥。
  6. 选择 添加新密钥。
  7. 在 密钥 框中，粘贴您的公钥内容。如果您手动复制了密钥，请确保复制整个密钥，它以 ssh-rsa、ssh-dss、ecdsa-sha2-nistp256、ecdsa-sha2-nistp384、ecdsa-sha2-nistp521、ssh-ed25519、sk-ecdsa-sha2-nistp256@openssh.com 或 sk-ssh-ed25519@openssh.com 开头，并可能以评论结尾。
  8. 在 标题 框中输入描述，例如 工作笔记本 或 家庭工作站。
  9. 可选。选择密钥的 使用类型。它可以用于 身份验证 或 签名 或两者。身份验证和签名 是默认值。
  10. 可选。更新 到期日期以修改默认到期日期。
    • 管理员可以查看到期日期并在删除密钥时使用它们作为指导。
    • 极狐GitLab 每天凌晨 01:00 UTC 检查所有 SSH 密钥。它会发送到期日期为七天后的所有 SSH 密钥的到期通知。
    • 极狐GitLab 每天凌晨 02:00 UTC 检查所有 SSH 密钥。它会发送当天到期的所有 SSH 密钥的到期通知。
  11. 选择 添加密钥。

验证您是否可以连接

验证您的 SSH 密钥是否已正确添加。

以下命令使用示例主机名 gitlab.example.com。将此示例主机名替换为您的极狐GitLab 实例的主机名，例如 git@gitlab.com。 默认情况下，极狐GitLab 使用 git 用户名进行身份验证。如果管理员已更改，则可能不同。

  1. 为了确保您连接到正确的服务器，请检查服务器的 SSH 主机密钥指纹。对于：
    • JihuLab.com，请参阅 SSH 主机密钥指纹 文档。
    • JihuLab.com 或其他极狐GitLab 实例，请参阅 gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints，其中 gitlab.example.com 是 gitlab.com（对于 JihuLab.com）或极狐GitLab 实例的地址。

  2. 打开终端并运行此命令，将 gitlab.example.com 替换为您的极狐GitLab 实例 URL：

    ssh -T git@gitlab.example.com

  3. 如果这是您首次连接，您应该验证极狐GitLab 主机的真实性。如果您看到类似的消息：

    The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hosts.

    输入 yes 并按 Enter。

  4. 再次运行 ssh -T git@gitlab.example.com 命令。您应该收到 欢迎来到极狐GitLab, @用户名! 消息。

如果欢迎消息没有出现，您可以通过以详细模式运行 ssh 来进行故障排除：

ssh -Tvvv git@gitlab.example.com

对不同的仓库使用不同的密钥

您可以为每个仓库使用不同的密钥。

打开终端并运行此命令：

git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"

此命令不使用 SSH 代理，需要 Git 2.10 或更高版本。有关 ssh 命令选项的更多信息，请参阅 ssh 和 ssh_config 的 man 页面。

查看您的 SSH 密钥

要查看您账户的 SSH 密钥：

  1. 在左侧边栏中，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏中，选择 SSH 密钥。

您现有的 SSH 密钥列在页面底部。信息包括：

  • 密钥的标题
  • 公钥指纹
  • 允许的使用类型
  • 创建日期
  • 最后使用日期
  • 到期日期

移除 SSH 密钥

您可以撤销或删除您的 SSH 密钥以永久从您的账户中移除它。

如果您使用密钥签署您的提交，移除您的 SSH 密钥会有额外的影响。有关更多信息，请参阅使用已移除 SSH 密钥签署的提交。

撤销 SSH 密钥

{{< history >}}

  • 在极狐GitLab 15.9 中引入。

{{< /history >}}

如果您的 SSH 密钥受到损害，请撤销密钥。

先决条件：

  • SSH 密钥必须具有 签名 或 身份验证和签名 使用类型。

要撤销 SSH 密钥：

  1. 在左侧边栏中，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏中，选择 SSH 密钥。
  4. 在您要撤销的 SSH 密钥旁边，选择 撤销。
  5. 选择 撤销。

删除 SSH 密钥

要删除 SSH 密钥：

  1. 在左侧边栏中，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏中，选择 SSH 密钥。
  4. 在您要删除的密钥旁边，选择 移除 ({{< icon name=”remove” >}})。
  5. 选择 删除。

在单个极狐GitLab 实例上使用不同账户

您可以使用多个账户连接到极狐GitLab 的单个实例。您可以通过使用上一个主题中的命令来做到这一点。然而，即使您将 IdentitiesOnly 设置为 yes，如果 IdentityFile 存在于 Host 块之外，您也无法登录。

相反，您可以在 ~/.ssh/config 文件中为主机分配别名。

  • 对于 Host，使用别名，例如 user_1.gitlab.com 和 user_2.gitlab.com。高级配置更难维护，当您使用像 git remote 这样的工具时，这些字符串更容易理解。
  • 对于 IdentityFile，使用私钥的路径。
# 用户1账户身份
Host <user_1.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key1>

# 用户2账户身份
Host <user_2.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key2>

现在，要克隆 user_1 的仓库，请在 git clone 命令中使用 user_1.gitlab.com：

git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git

要更新之前克隆的仓库，该仓库被别名为 origin：

git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git

{{< alert type=”note” >}}

私钥和公钥包含敏感数据。确保文件的权限使它们可读，但不可被其他人访问。

{{< /alert >}}

配置双因素认证 (2FA)

您可以为 Git over SSH 设置双因素认证 (2FA)。您应该使用 ED25519_SK 或 ECDSA_SK SSH 密钥。

在 Eclipse 上使用 EGit

如果您正在使用 EGit，您可以将您的 SSH 密钥添加到 Eclipse。

在 Microsoft Windows 上使用 SSH

如果您正在运行 Windows 10，您可以使用 Windows 子系统 Linux (WSL) 和 WSL 2，其中预安装了 git 和 ssh，或者安装 Git for Windows 以通过 PowerShell 使用 SSH。

在 WSL 中生成的 SSH 密钥不能直接用于 Git for Windows，反之亦然，因为两者具有不同的主目录：

  • WSL：/home/<user>
  • Git for Windows：C:\Users\<user>

您可以复制 .ssh/ 目录以使用相同的密钥，或在每个环境中生成密钥。

如果您正在运行 Windows 11 并使用 OpenSSH for Windows，请确保正确设置 HOME 环境变量。否则，可能无法找到您的私有 SSH 密钥。

替代工具包括：

  • Cygwin
  • PuTTYgen 0.81 或更高版本

在极狐GitLab 服务器上覆盖 SSH 设置

极狐GitLab 与系统安装的 SSH 守护程序集成，并指定一个用户（通常命名为 git），通过该用户处理所有访问请求。通过 SSH 连接到极狐GitLab 服务器的用户通过其 SSH 密钥而不是用户名进行识别。

在极狐GitLab 服务器上执行的 SSH 客户端 操作以此用户身份执行。您可以修改此 SSH 配置。例如，您可以为此用户指定私有 SSH 密钥以用于身份验证请求。然而，这种做法是不支持的，并且强烈不建议，因为它带来了重大安全风险。

极狐GitLab 检查此条件，并在您的服务器配置为这种方式时将您引导到此部分。例如：

$ gitlab-rake gitlab:check

Git user has default SSH configuration? ... no
  Try fixing it:
  mkdir ~/gitlab-check-backup-1504540051
  sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
  sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
  For more information see:
  doc/user/ssh.md#overriding-ssh-settings-on-the-gitlab-server
  Please fix the error above and rerun the checks.

尽快移除自定义配置。这些自定义是不支持的，可能随时停止工作。

验证极狐GitLab SSH 所有权和权限

极狐GitLab SSH 文件夹和文件必须具有以下权限：

  • 文件夹 /var/opt/gitlab/.ssh/ 必须由 git 组和 git 用户拥有，权限设置为 700。
  • authorized_keys 文件必须设置为 600 权限。
  • authorized_keys.lock 文件必须设置为 644 权限。

要验证这些权限是否正确，请运行以下命令：

stat -c "%a %n" /var/opt/gitlab/.ssh/.

设置权限

如果权限错误，请登录到应用服务器并运行：

cd /var/opt/gitlab/
chown git:git /var/opt/gitlab/.ssh/
chmod 700  /var/opt/gitlab/.ssh/
chmod 600  /var/opt/gitlab/.ssh/authorized_keys
chmod 644  /var/opt/gitlab/.ssh/authorized_keys.lock