SSH 公钥管理
在 GitCode 中,您可以通过 SSH(安全外壳协议)公钥实现安全的代码托管和提交操作。SSH 公钥提供了以下优势:
- 便捷访问:使用 SSH 公钥后,您无需每次操作都输入密码,访问 GitCode 存储库更加高效。
- 访问控制:您可以将 SSH 公钥与特定存储库关联,灵活管理项目访问权限。
- SSH 公钥与私钥成对使用,请妥善保管私钥,避免泄露。
- 如果您在多个设备上使用 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 密钥
-
打开终端
- 在 Linux/macOS 上,打开系统自带的终端
- 在 Windows 上,可以使用 Cmd、Power Shell 或 Git Bash
-
输入生成密钥的命令
运行以下命令,将
your_email@example.com
替换为您的邮箱:ssh-keygen -t ed25519 -C "your_email@example.com"
-t ed25519
:指定密钥类型为 ED25519。-C "your_email@example.com"
:添加注释,通常使用您的邮箱地址,便于识别密钥。
-
选择密钥保存位置
命令执行后,您将看到以下提示:
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
。
- 按 Enter 键接受默认位置(
-
设置密钥密码(可选但推荐)
接下来,系统会提示您设置密码:
Enter passphrase (empty for no passphrase):
Enter same passphrase again:- 输入一个安全的密码以保护您的私钥(建议使用强密码)。
- 如果不需要密码,直接按 Enter 键跳过。
提示设置密码后,每次使用 SSH 密钥时都需要输入该密码。这可以防止私钥被未经授权的人使用。
-
确认密钥生成成功
如果操作成功,您将看到类似以下的输出:
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]-----+ -
查看生成的密钥
您可以通过以下命令查看生成的公钥内容:
cat ~/.ssh/id_ed25519.pub
您将得到类似下方的输出:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJx8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z8z your_email@example.com
将此公钥内容复制,以便后续添加到 GitCode。
生成 RSA SSH 密钥
RSA 是一种广泛支持的 SSH 密钥类型,适用于大多数场景。为了确保安全性,建议使用 4096 位 的密钥长度(至少 2048 位)。
-
输入生成密钥的命令
运行以下命令,将
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"
:添加注释,通常使用您的邮箱地址,便于识别密钥。
-
-
选择密钥保存位置
命令执行后,您将看到以下提示:
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
-
-
设置密钥密码(可选但推荐)
接下来,系统会提示您设置密码:
Enter passphrase (empty for no passphrase):
Enter same passphrase again:-
输入一个安全的密码以保护您的私钥(建议使用强密码)
-
如果不需要密码,直接按 Enter 键跳过
密码的作用设置密码后,每次使用 SSH 密钥时都需要输入该密码。这可以防止私钥被未经授权的人使用。
-
-
确认密钥生成成功
如果操作成功, 您将看到类似以下的输出:
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)。
-
-
查看生成的密钥
您可以通过以下命令查看生成的公钥内容:
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 版本,建议采取以下措施:
-
升级现有 RSA 密钥
如果您已有 RSA 密钥,可以通过以下命令将其升级为更安全的 OpenSSH 格式:
ssh-keygen -o -f ~/.ssh/id_rsa
-
生成新的 RSA 密钥
如果您需要生成新的 RSA 密钥,可以使用以下命令:
ssh-keygen -o -t rsa -b 4096 -C "your_email@example.com"
-o
:以更安全的 OpenSSH 格式保存私钥。
添加 SSH 公钥到 GitCode
现在,你可以将创建好的 SSH 密钥复制到你的 GitCode 帐户。以ED25519 SSH 密钥为例,你可以参考以下步骤:
-
复制 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 密钥,相应地替换即可
-
登录 GitCode,进入「个人设置」->「安全设置」->「SSH 公钥」
-
点击「+ SSH 公钥」
-
在“公钥名称”一栏中,为公钥添加一个描述性名称
-
将复制的公钥内容粘贴到“公钥”文本框中
-
点击「新建」完成操作
如果你手动复制了公共 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
:指定对应账号的私钥文件路径。
-
IdentityFile
配置必须放在Host
块内部,而不能放在Host
块之外。如果IdentityFile
配置在Host
块之外,SSH 和 Git 将无法正确识别密钥,导致登录失败。 -
注意:私钥和公钥文件的权限应设置为仅用户可读,运行以下命令:
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
调试连接