跳到主要内容

SSH 公钥管理

在 GitCode 中，您可以通过 SSH（安全外壳协议）公钥实现安全的代码托管和提交操作。SSH 公钥提供了以下优势：

  • 便捷访问：使用 SSH 公钥后，您无需每次操作都输入密码，访问 GitCode 存储库更加高效。
  • 访问控制：您可以将 SSH 公钥与特定存储库关联，灵活管理项目访问权限。
注意事项
  1. SSH 公钥与私钥成对使用，请妥善保管私钥，避免泄露。
  2. 如果您在多个设备上使用 GitCode，建议为每个设备生成独立的 SSH 密钥对。

SSH 密钥类型​

GitCode 支持以下两类 SSH 密钥：

ED25519 SSH 密钥​

  • 安全性更高：根据 Practical Cryptography With Go 的描述，ED25519 密钥比 RSA 密钥更安全。
  • 广泛支持：自 2014 年 OpenSSH 6.5 引入 ED25519 后，所有主流操作系统均已支持该密钥类型。

RSA SSH 密钥​

  • 密钥长度建议：如果使用 RSA 密钥，建议密钥长度为 4096 位（至少 2048 位），以确保安全性。
  • 兼容性：默认情况下，ssh-keygen 命令生成的 RSA 密钥为 1024 位，建议升级至更高强度。
  • 安全性提示：在 OpenSSH 7.8 之前，RSA 密钥的默认指纹基于 MD5，存在安全风险。如果您仍在使用旧版 RSA 密钥，建议升级至更安全的加密格式。

生成 SSH 密钥​

生成 ED25519 SSH 密钥​

  1. 打开终端

    • 在 Linux/macOS 上，打开系统自带的终端
    • 在 Windows 上，可以使用 Cmd、Power Shell 或 Git Bash

  2. 输入生成密钥的命令

    运行以下命令，将 your_email@example.com 替换为您的邮箱：

    ssh-keygen -t ed25519 -C "your_email@example.com"
    • -t ed25519：指定密钥类型为 ED25519。
    • -C "your_email@example.com"：添加注释，通常使用您的邮箱地址，便于识别密钥。

  3. 选择密钥保存位置

    命令执行后，您将看到以下提示：

    Generating public/private ed25519 key pair.
    Enter file in which to save the key (/Users/user/.ssh/id_ed25519):
    • 按 Enter 键接受默认位置（~/.ssh/id_ed25519）。
    • 如果需要自定义保存路径，可以输入新的路径，例如：~/.ssh/my_custom_key。

  4. 设置密钥密码（可选但推荐）

    接下来，系统会提示您设置密码：

    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    • 输入一个安全的密码以保护您的私钥（建议使用强密码）。
    • 如果不需要密码，直接按 Enter 键跳过。
    提示

    设置密码后，每次使用 SSH 密钥时都需要输入该密码。这可以防止私钥被未经授权的人使用。

  5. 确认密钥生成成功

    如果操作成功，您将看到类似以下的输出：

    Your identification has been saved in /Users/user/.ssh/id_ed25519
    Your public key has been saved in /Users/user/.ssh/id_ed25519.pub
    The key fingerprint is:
    SHA256:x8gFyNRIg5UsIhqYOnsDYhyxXJNhwBU2WcLs11b421g your_email@example.com
    The key's randomart image is:
    +--[ED25519 256]--+
    |o+*@*O==o        |
    |*o*=* *o.o       |
    |+=o. .. o .      |
    |*o . . + = E     |
    |o+  . . S B      |
    |. o      + .     |
    | . .             |
    |                 |
    |                 |
    +----[SHA256]-----+

  6. 查看生成的密钥

    您可以通过以下命令查看生成的公钥内容：

    cat ~/.ssh/id_ed25519.pub

    您将得到类似下方的输出：

    ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJx8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z your_email@example.com

    将此公钥内容复制，以便后续添加到 GitCode。

img_1735033556079_78805a.png

生成 RSA SSH 密钥​

RSA 是一种广泛支持的 SSH 密钥类型，适用于大多数场景。为了确保安全性，建议使用 4096 位 的密钥长度（至少 2048 位）。

  1. 输入生成密钥的命令

    运行以下命令，将 your_email@example.com 替换为您的邮箱地址：

    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

    • -t rsa：指定密钥类型为 RSA。

    • -b 4096：指定密钥长度为 4096 位（推荐）。

    • -C "your_email@example.com"：添加注释，通常使用您的邮箱地址，便于识别密钥。

  2. 选择密钥保存位置

    命令执行后，您将看到以下提示：

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

    • 按 Enter 键接受默认位置（~/.ssh/id_rsa）

    • 如果需要自定义保存路径，可以输入新的路径，例如：~/.ssh/my_custom_key

  3. 设置密钥密码（可选但推荐）

    接下来，系统会提示您设置密码：

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

    • 输入一个安全的密码以保护您的私钥（建议使用强密码）

    • 如果不需要密码，直接按 Enter 键跳过

      密码的作用

      设置密码后，每次使用 SSH 密钥时都需要输入该密码。这可以防止私钥被未经授权的人使用。

  4. 确认密钥生成成功

    如果操作成功，您将看到类似以下的输出：

    Your identification has been saved in /Users/.ssh/id_rsa
    Your public key has been saved in /Users/.ssh/id_rsa.pub
    The key fingerprint is:
    SHA256:Ub+LOdZzqYTdq5t+mDAErdkTtzUbnB8VPXJs/cTBDPA your_email@example.com
    The key's randomart image is:
    +---[RSA 4096]----+
    |         ....o==B|
    |        ..o.o.*O=|
    |        .= o.E+*+|
    |        o.+ ... o|
    |        S. ..    |
    |          o* o . |
    |          *o*o+  |
    |         . oo=.. |
    |           .*+.  |
    +----[SHA256]-----+

    • 私钥：~/.ssh/id_rsa（切勿泄露）。

    • 公钥：~/.ssh/id_rsa.pub（可上传到 GitCode）。

  5. 查看生成的密钥

    您可以通过以下命令查看生成的公钥内容：

    cat ~/.ssh/id_rsa.pub

    输出示例：

    ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArV1... your_email@example.com

    将此公钥内容复制，以便后续添加到 GitCode。

OpenSSH 6.5 ~ 7.8 的 RSA 密钥​

在 OpenSSH 7.8 之前，RSA 密钥的默认指纹基于 MD5，存在安全风险。如果您使用的是 OpenSSH 6.5 至 7.8 版本，建议采取以下措施：

  1. 升级现有 RSA 密钥

    如果您已有 RSA 密钥，可以通过以下命令将其升级为更安全的 OpenSSH 格式：

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

  2. 生成新的 RSA 密钥

    如果您需要生成新的 RSA 密钥，可以使用以下命令：

    ssh-keygen -o -t rsa -b 4096 -C "your_email@example.com"
    • -o：以更安全的 OpenSSH 格式保存私钥。

添加 SSH 公钥到 GitCode​

现在，你可以将创建好的 SSH 密钥复制到你的 GitCode 帐户。以ED25519 SSH 密钥为例，你可以参考以下步骤：

  1. 复制 SSH 公钥内容

    从保存 SSH 密钥的文件中复制你的 SSH 密钥的公钥，以下命令可以将 ED25519 的信息保存到指定操作系统的剪贴板中：

    macOS

    pbcopy < ~/.ssh/id_ed25519.pub

    Linux（需要 xclip 软件包）

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

    Windows 上的 Git Bash

    cat ~/.ssh/id_ed25519.pub | clip

    如果你使用的是 RSA 密钥，相应地替换即可

  2. 登录 GitCode，进入「个人设置」->「安全设置」->「SSH 公钥」

  3. 点击「+ SSH 公钥」

  4. 在“公钥名称”一栏中，为公钥添加一个描述性名称

  5. 将复制的公钥内容粘贴到“公钥”文本框中

  6. 点击「新建」完成操作

    img_1735033556079_3f4460.png

提示

如果你手动复制了公共 SSH 密钥，请确保复制了整个密钥，以ssh-ed25519 （或ssh-rsa ）开头，并以你的电子邮件地址结尾。

测试 SSH 连接​

要测试是否正确添加了 SSH 密钥，可以在终端中运行以下命令：

ssh -T git@gitcode.com

在你第一次通过 SSH 方式连接到 GitCode 的时候，将会询问你是否信任将要连接的 GitCode host 地址。当确认 yes 后，会将 GitCode 作为已知主机添加到受信任的 hosts 地址中：

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

一旦添加到已知主机列表中，将不再要求你再次验证 GitCode 主机的真实性。 再次运行以上命令时，你将只收到 Welcome to GitCode, [username] 信息。

如果未出现欢迎消息，则可以通过使用以下命令在详细模式下运行 ssh 来解决问题：

ssh -Tv git@gitcode.com

使用非默认路径的 SSH 密钥​

如果你为 SSH 密钥对使用了非默认文件路径，请配置 SSH 客户端以指向 GitCode 私有 SSH 密钥。

可以运行以下命令进行配置：

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

以上设置将会保存到~/.ssh/config文件中。以下是两个专用于 GitCode 的 SSH 密钥示例：

# GitCode
  Host gitcode.com
  Preferredauthentications publickey
  IdentityFile ~/.ssh/gitcode_rsa

# Github instance
  Host github.com
  Preferredauthentications publickey
  IdentityFile ~/.ssh/example_github_rsa

公共 SSH 密钥对于 GitCode 必须是唯一的，因为它们将绑定到你的账号中。 SSH 密钥是通过 SSH 推送代码时唯一的标识符，这是它需要唯一地映射到单个用户的原因。

为项目设置 SSH 密钥​

如果要根据正在使用的项目代码仓库使用不同的密钥，则可以在代码仓库中执行以下命令：

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 密钥的方法还适用于在 GitCode 中使用多个账号的情况，此外，还可以通过在 ~/.ssh/config 配置 SSH 密钥来区分不同账号。以下是具体方法：

在 ~/.ssh/config 文件中为每个账号设置别名，并指定对应的 SSH 密钥文件。示例配置如下：

# User1 账号配置
Host user_1.gitcode.com
  Hostname gitcode.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/example_ssh_key1

# User2 账号配置
Host user_2.gitcode.com
  Hostname gitcode.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/example_ssh_key2
  • Host：自定义别名（如 user_1.gitcode.com），用于区分不同账号。
  • IdentityFile：指定对应账号的私钥文件路径。
提示

  1. IdentityFile 配置必须放在 Host 块内部，而不能放在 Host 块之外。如果 IdentityFile 配置在 Host 块之外，SSH 和 Git 将无法正确识别密钥，导致登录失败。

  2. 注意：私钥和公钥文件的权限应设置为仅用户可读，运行以下命令：

    chmod 0400 ~/.ssh/example_ssh_key1
    chmod 0400 ~/.ssh/example_ssh_key1.pub

接下来您可以使用配置的别名克隆仓库。例如，为 user_1 克隆仓库时，将 gitcode.com 替换为别名 user_1.gitcode.com：

git clone git@user_1.gitcode.com:repo-org/repo.git

如果已克隆仓库但需要切换账号，可以使用 git remote set-url 命令修改远程 URL。例如：

git remote set-url origin git@user_1.gitcode.com:repo-org/repo.git

在 Eclipse 中配置 SSH 密钥​

如果使用 Eclipse 和 EGit 插件，可以通过 EGit 用户指南 将 SSH 密钥添加到 Eclipse。

Windows 系统配置​

在 Windows 上，可以通过以下方式支持 Git 和 SSH：

  • WSL（Windows Subsystem for Linux）：安装 Linux 发行版（如 Ubuntu），使用其中的 Git 和 SSH 客户端。
  • Git for Windows：安装 Git for Windows，自带 SSH 客户端。
  • 其他工具：
    • Cygwin：在 Windows 上运行 Linux 工具的环境。
    • PuttyGen：用于生成和管理 SSH 密钥的工具。

故障排除​

如果在执行 git clone 时，系统提示你输入密码（例如 git@gitcode.com's password:），这表明 SSH 配置可能存在问题。以下是排查步骤：

  • 确保你正确地生成了 SSH 密钥，并将公共 SSH 密钥添加到了你 GitCode 账号的 SSH 密钥中
  • 尝试使用 ssh-agent 手动注册你的私有 SSH 密钥，参考 使用非默认路径的 SSH 密钥
  • 尝试通过运行 ssh -Tv git@gitcode.com 调试连接