Git配置SSH密钥认证从入门到精通详细讲解密钥生成配置平台绑定以及故障排查等全流程内容助你成为Git高手

1. SSH密钥认证基础

1.1 什么是SSH密钥认证？

SSH（Secure Shell）是一种网络协议，用于加密方式远程登录和管理服务器。在Git中，SSH密钥认证是一种安全的方式，允许你在不输入密码的情况下与远程Git仓库进行交互。

SSH密钥认证使用一对密钥：私钥和公钥。私钥保存在你的本地计算机上，必须保密；公钥则可以安全地分享给任何人，通常添加到你使用的Git托管服务（如GitHub、GitLab等）上。

1.2 为什么使用SSH密钥认证？

使用SSH密钥认证有以下几个主要优势：

安全性：相比HTTPS认证，SSH密钥认证更加安全。私钥永远不会离开你的计算机，而公钥即使被截获也无法用来破解认证。
便利性：一旦配置完成，你无需每次推送或拉取代码时输入用户名和密码。
自动化友好：对于自动化脚本和CI/CD流程，SSH密钥认证是理想的选择，因为它不需要交互式输入凭证。

1.3 SSH密钥认证的工作原理

SSH密钥认证的工作原理如下：

你生成一对SSH密钥（私钥和公钥）。
你将公钥添加到Git托管服务上。
当你尝试通过SSH连接到Git托管服务时，服务会使用你存储的公钥加密一个随机字符串，并发送给你的客户端。
你的客户端使用私钥解密这个字符串，并将其发送回服务。
服务验证收到的字符串是否与原始字符串匹配。如果匹配，认证成功。

2. 生成SSH密钥

2.1 检查现有SSH密钥

在生成新的SSH密钥之前，最好先检查你是否已经拥有SSH密钥。打开终端（在Windows上可以使用Git Bash或PowerShell），运行以下命令：

ls -al ~/.ssh

这个命令会列出你.ssh目录下的所有文件。如果你看到类似id_rsa.pub或id_ed25519.pub的文件，说明你已经有了SSH密钥。

2.2 生成新的SSH密钥

如果你没有SSH密钥，或者想要为特定用途生成新的密钥，可以按照以下步骤操作：

2.2.1 使用ED25519算法生成密钥（推荐）

ED25519是一种现代、安全且高效的加密算法，是生成SSH密钥的推荐选择。

ssh-keygen -t ed25519 -C "your_email@example.com"

将your_email@example.com替换为你的电子邮件地址。这个地址将作为密钥的标识，帮助你识别密钥的用途。

2.2.2 使用RSA算法生成密钥

如果你的系统不支持ED25519，可以使用RSA算法：

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

这里-b 4096指定了密钥的位数为4096，这是RSA密钥的推荐长度。

2.3 密钥生成过程详解

运行上述命令后，你会看到以下提示：

保存位置：
```
Enter file in which to save the key (/home/your_username/.ssh/id_ed25519): 
```
按Enter键接受默认位置，或者输入自定义路径。
密码短语（Passphrase）：
```
Enter passphrase (empty for no passphrase): Enter same passphrase again: 
```
输入一个强密码短语。这个密码短语用于加密你的私钥，即使有人获取了你的私钥文件，没有密码短语也无法使用它。虽然这是可选的，但强烈建议设置密码短语以提高安全性。

2.4 查看生成的SSH密钥

生成密钥后，你可以查看公钥内容：

cat ~/.ssh/id_ed25519.pub

或者，如果你使用的是RSA密钥：

cat ~/.ssh/id_rsa.pub

这将显示你的公钥，以ssh-ed25519或ssh-rsa开头，后面跟着一长串字符，最后是你的电子邮件地址。

3. 配置SSH密钥

3.1 启动SSH代理

SSH代理是一个程序，它在后台运行，保存你的解密私钥，这样你就不必每次使用SSH时都输入密码短语。

在macOS和Linux上，启动SSH代理：

eval "$(ssh-agent -s)"

在Windows上（使用Git Bash）：

eval $(ssh-agent -s)

3.2 将SSH私钥添加到SSH代理

将你的SSH私钥添加到SSH代理：

ssh-add ~/.ssh/id_ed25519

或者，如果你使用的是RSA密钥：

ssh-add ~/.ssh/id_rsa

如果你为密钥设置了密码短语，系统会提示你输入它。

3.3 配置SSH文件

为了确保SSH连接使用正确的密钥，你可以创建或编辑~/.ssh/config文件：

touch ~/.ssh/config

然后，在文件中添加以下内容：

# GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes # GitLab Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes # Bitbucket Host bitbucket.org HostName bitbucket.org User git IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes

这个配置告诉SSH客户端在连接到特定主机时使用哪个密钥。

3.4 测试SSH连接

在将公钥添加到Git托管服务之前，你可以测试SSH连接是否正常工作：

ssh -T git@github.com

如果一切正常，你会看到类似以下的消息：

Hi your_username! You've successfully authenticated, but GitHub does not provide shell access.

类似地，你可以测试与其他Git托管服务的连接：

ssh -T git@gitlab.com ssh -T git@bitbucket.org

4. 在不同平台上绑定SSH密钥

4.1 在GitHub上添加SSH密钥

登录到你的GitHub账户。
点击右上角的头像，然后选择”Settings”。
在左侧菜单中，点击”SSH and GPG keys”。
点击”New SSH key”按钮。
在”Title”字段中，输入一个描述性的标题，例如”My Laptop SSH Key”。
在”Key”字段中，粘贴你的SSH公钥（从cat ~/.ssh/id_ed25519.pub命令获取）。
点击”Add SSH key”按钮。
如果需要，输入你的GitHub密码进行确认。

4.2 在GitLab上添加SSH密钥

登录到你的GitLab账户。
点击右上角的头像，然后选择”Settings”。
在左侧菜单中，点击”SSH Keys”。
在”Key”字段中，粘贴你的SSH公钥。
在”Title”字段中，输入一个描述性的标题。
可选地，在”Expires at”字段中设置密钥的过期日期。
点击”Add key”按钮。

4.3 在Bitbucket上添加SSH密钥

登录到你的Bitbucket账户。
点击左下角的头像，然后选择”Bitbucket settings”。
在左侧菜单中，点击”SSH keys”。
点击”Add key”按钮。
在”Label”字段中，输入一个描述性的标题。
在”Key”字段中，粘贴你的SSH公钥。
点击”Add key”按钮。

4.4 在其他Git托管服务上添加SSH密钥

大多数Git托管服务添加SSH密钥的流程类似：

登录到你的账户。
进入账户设置或个人资料设置。
找到”SSH Keys”或类似的选项。
点击”Add key”或”New key”按钮。
粘贴你的SSH公钥并添加一个描述性的标题。
保存更改。

5. 使用SSH密钥进行Git操作

5.1 克隆仓库使用SSH

使用SSH克隆仓库时，URL格式通常如下：

git clone git@github.com:username/repository.git

相比之下，HTTPS URL格式为：

git clone https://github.com/username/repository.git

5.2 更改现有仓库的远程URL

如果你已经使用HTTPS克隆了一个仓库，可以将其更改为使用SSH：

cd /path/to/repository git remote set-url origin git@github.com:username/repository.git

5.3 验证远程URL

要验证你的远程URL是否已更改为SSH，可以运行：

git remote -v

你应该看到类似以下的输出：

origin git@github.com:username/repository.git (fetch) origin git@github.com:username/repository.git (push)

6. 多SSH密钥管理

6.1 为什么需要多个SSH密钥？

在某些情况下，你可能需要使用多个SSH密钥：

工作与个人账户分离：你可能有一个用于工作的Git账户和一个用于个人项目的Git账户。
不同平台使用不同密钥：你可能希望为GitHub、GitLab和Bitbucket使用不同的密钥。
安全考虑：为不同的项目或环境使用不同的密钥可以提高安全性，如果一个密钥被泄露，只需撤销该密钥而不影响其他项目。

6.2 生成多个SSH密钥

为不同用途生成不同的SSH密钥：

# 为GitHub生成密钥 ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519_github # 为GitLab生成密钥 ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519_gitlab # 为Bitbucket生成密钥 ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519_bitbucket

6.3 配置多个SSH密钥

编辑~/.ssh/config文件，为每个服务指定不同的密钥：

# GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes # GitLab Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/id_ed25519_gitlab IdentitiesOnly yes # Bitbucket Host bitbucket.org HostName bitbucket.org User git IdentityFile ~/.ssh/id_ed25519_bitbucket IdentitiesOnly yes

6.4 添加多个密钥到SSH代理

将所有密钥添加到SSH代理：

ssh-add ~/.ssh/id_ed25519_github ssh-add ~/.ssh/id_ed25519_gitlab ssh-add ~/.ssh/id_ed25519_bitbucket

6.5 在不同平台上添加不同的SSH密钥

按照第4节中的步骤，将相应的公钥添加到各自的平台：

将~/.ssh/id_ed25519_github.pub添加到GitHub
将~/.ssh/id_ed25519_gitlab.pub添加到GitLab
将~/.ssh/id_ed25519_bitbucket.pub添加到Bitbucket

7. SSH密钥故障排查

7.1 常见SSH连接问题及解决方案

7.1.1 “Permission denied (publickey)“错误

问题：当你尝试连接到Git托管服务时，收到”Permission denied (publickey)“错误。

可能原因：

SSH密钥未添加到Git托管服务。
SSH密钥与Git托管服务上存储的密钥不匹配。
SSH客户端使用了错误的密钥。

解决方案：

确保你已将公钥添加到Git托管服务。
验证SSH客户端使用的密钥：
```
 ssh -vT git@github.com 
```
这将显示详细的连接信息，包括尝试使用的密钥。
检查~/.ssh/config文件，确保为正确的主机指定了正确的密钥。

7.1.2 “Invalid format”或”Invalid key”错误

问题：在添加SSH密钥到Git托管服务时，收到”Invalid format”或”Invalid key”错误。

可能原因：

你复制了私钥而不是公钥。
复制过程中包含了额外的字符或空格。

解决方案：

确保你复制的是公钥（以.pub结尾的文件）。

使用以下命令重新复制公钥，确保不包含额外的字符：

 cat ~/.ssh/id_ed25519.pub | pbcopy # macOS cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard # Linux (需要安装xclip) cat ~/.ssh/id_ed25519.pub | clip # Windows (Git Bash)

7.1.3 “Enter passphrase for key”提示频繁出现

问题：每次使用SSH时都需要输入密码短语。

可能原因：

SSH代理未运行或未添加密钥。
SSH代理已重启，需要重新添加密钥。

解决方案：

确保SSH代理正在运行：
```
 eval "$(ssh-agent -s)" 
```
将密钥添加到SSH代理：
```
 ssh-add ~/.ssh/id_ed25519 
```
考虑使用SSH配置文件中的AddKeysToAgent yes选项，这样密钥会自动添加到代理。

7.1.4 “Connection timed out”或”Connection refused”错误

问题：无法连接到Git托管服务，收到”Connection timed out”或”Connection refused”错误。

可能原因：

网络连接问题。
防火墙阻止了SSH连接（端口22）。
公司或学校网络限制了SSH连接。

解决方案：

检查网络连接。
尝试使用HTTPS连接，确认是否可以访问Git托管服务。
如果可能，联系网络管理员，确认是否允许SSH连接。
某些Git托管服务支持通过HTTPS端口进行SSH连接，可以尝试：
```
 ssh -T -p 443 git@ssh.github.com 
```
如果这有效，可以在~/.ssh/config文件中添加：
```
 Host github.com Hostname ssh.github.com Port 443 User git IdentityFile ~/.ssh/id_ed25519 
```

7.2 高级故障排查技巧

7.2.1 使用详细模式调试SSH连接

使用-v标志获取详细的SSH连接信息：

ssh -vT git@github.com

如果需要更详细的信息，可以使用-vvv：

ssh -vvvT git@github.com

7.2.2 检查SSH密钥指纹

验证你的SSH密钥是否与Git托管服务上存储的密钥匹配：

获取本地密钥的指纹：
```
 ssh-keygen -lf ~/.ssh/id_ed25519.pub 
```
在Git托管服务上，查看已添加SSH密钥的指纹（通常在SSH密钥设置页面）。

7.2.3 测试SSH连接

使用ssh-keyscan测试SSH连接：

ssh-keyscan github.com

这将显示GitHub的SSH主机密钥指纹，你可以将其与~/.ssh/known_hosts文件中的指纹进行比较。

7.2.4 检查文件权限

SSH对文件权限非常严格，确保以下文件和目录具有正确的权限：

chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub chmod 644 ~/.ssh/known_hosts chmod 644 ~/.ssh/config

8. SSH密钥安全最佳实践

8.1 保护你的私钥

私钥是你的身份证明，必须严格保护：

使用强密码短语：为你的SSH私钥设置强密码短语。
不要共享私钥：永远不要与他人共享你的私钥。
定期轮换密钥：定期生成新的SSH密钥对，并删除旧的密钥。
在安全设备上生成密钥：在受信任的设备上生成SSH密钥，避免在公共或共享计算机上生成。

8.2 管理SSH密钥

定期审计：定期检查你在Git托管服务上添加的SSH密钥，删除不再使用的密钥。
为不同用途使用不同密钥：为工作、个人项目等使用不同的SSH密钥。
使用密钥过期：如果Git托管服务支持，为SSH密钥设置过期日期。

8.3 使用硬件安全密钥

对于更高的安全性，考虑使用硬件安全密钥（如YubiKey）：

硬件安全密钥将私钥存储在硬件设备中，无法提取。
即使你的计算机被感染，攻击者也无法窃取你的私钥。
使用硬件安全密钥需要特定的配置和支持。

8.4 监控SSH密钥使用情况

启用通知：在Git托管服务上启用SSH密钥使用通知。
审查日志：定期审查Git托管服务的访问日志，查找可疑活动。
使用IP限制：如果可能，限制只有特定IP地址可以使用你的SSH密钥。

9. 高级SSH配置

9.1 SSH配置文件高级选项

~/.ssh/config文件提供了许多高级选项，可以增强SSH连接的安全性和便利性：

# 全局设置 Host * ServerAliveInterval 60 ServerAliveCountMax 3 TCPKeepAlive yes Compression yes ControlMaster auto ControlPath ~/.ssh/master-%r@%h:%p ControlPersist 600 # GitHub特定设置 Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes AddKeysToAgent yes UseKeychain yes # macOS特定选项

9.2 使用SSH代理转发

SSH代理转发允许你在通过SSH连接到远程服务器时，使用本地计算机上的SSH密钥：

在~/.ssh/config文件中添加：

 Host remote-server HostName remote-server.com User your_username ForwardAgent yes

连接到远程服务器：
```
 ssh remote-server 
```
在远程服务器上，你现在可以使用本地计算机上的SSH密钥：
```
 git clone git@github.com:username/repository.git 
```

9.3 使用SSH跳转主机

如果你需要通过跳转主机访问Git仓库，可以在~/.ssh/config文件中配置：

# 跳转主机 Host jump-server HostName jump-server.com User your_username # 目标主机 Host target-server HostName target-server.com User git ProxyJump jump-server IdentityFile ~/.ssh/id_ed25519

9.4 使用SSH配置别名

你可以为常用的SSH连接创建别名：

# GitHub别名 Host gh HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes # GitLab别名 Host gl HostName gitlab.com User git IdentityFile ~/.ssh/id_ed25519_gitlab IdentitiesOnly yes

然后，你可以使用简短的别名克隆仓库：

git clone gh:username/repository.git git clone gl:username/repository.git

10. SSH密钥与CI/CD集成

10.1 在CI/CD流水线中使用SSH密钥

在持续集成/持续部署（CI/CD）流水线中，你可能需要使用SSH密钥访问私有Git仓库：

生成部署密钥：为CI/CD系统生成专用的SSH密钥对：

 ssh-keygen -t ed25519 -C "ci-cd@example.com" -f ~/.ssh/id_ed25519_ci_cd

添加公钥到Git托管服务：将~/.ssh/id_ed25519_ci_cd.pub添加为部署密钥。
在CI/CD配置中添加私钥：将私钥作为安全变量添加到CI/CD系统。

在CI/CD脚本中设置SSH：在CI/CD脚本中，设置SSH并添加私钥：

 mkdir -p ~/.ssh echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_ed25519 chmod 600 ~/.ssh/id_ed25519 ssh-keyscan github.com >> ~/.ssh/known_hosts git clone git@github.com:username/private-repository.git

10.2 使用GitHub Actions的SSH密钥

在GitHub Actions中，你可以使用内置的actions/checkout动作通过SSH访问仓库：

name: Deploy to Production on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v2 with: ssh-key: ${{ secrets.SSH_PRIVATE_KEY }} ssh-known-hosts: ${{ secrets.SSH_KNOWN_HOSTS }} - name: Deploy run: | # 部署脚本

10.3 使用GitLab CI/CD的SSH密钥

在GitLab CI/CD中，你可以使用SSH密钥访问私有仓库：

deploy_production: stage: deploy script: - 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )' - eval $(ssh-agent -s) - echo "$SSH_PRIVATE_KEY" | tr -d 'r' | ssh-add - - mkdir -p ~/.ssh - chmod 700 ~/.ssh - ssh-keyscan gitlab.com >> ~/.ssh/known_hosts - chmod 644 ~/.ssh/known_hosts - git clone git@gitlab.com:username/private-repository.git only: - main