在 Jenkins 中使用 SSH 部署密钥

本文档介绍了如何在 Jenkins 中配置 SSH 部署密钥，以便更稳定地拉取 Git 仓库代码，避免常见的 RPC 错误。

1. 背景

在使用 Jenkins 进行持续集成时，常常需要从 Git 仓库拉取代码。如果使用 HTTP/HTTPS 协议，有时会遇到 RPC 错误，这可能是由于网络不稳定或大文件传输导致的。使用 SSH 协议可以提供更稳定的连接，并且在处理大文件时表现更好。

2. 常见的 RPC 错误

常见的错误信息如下：

remote:Enumerating objects:12443,done.
remote:Counting objects:100%(946/946),done.
remote:Compressing objects:100%(762/762),done.
error: RPC failed; curl 92 HTTP/2 stream 7 was not closed cleanly: INTERNAL_ERROR (err 2)
error:40022 bytes of body are still expected
fetch-pack: unexpected disconnect while reading sideband packet
fatal: early EOF
fatal: fetch-pack: invalid index-pack output

错误

remote:Enumerating objects:12443,done.
remote:Counting objects:100%(946/946),done.
remote:Compressing objects:100%(762/762),done.
error: RPC failed; curl 56GnuTLS recv error (-9):Error decoding the received TLS packet.
error:9443 bytes of body are still expected
fetch-pack: unexpected disconnect while reading sideband packet
fatal: early EOF
fatal: fetch-pack: invalid index-pack output

错误

这个错误信息表明在 Jenkins 中使用 Git 插件进行代码拉取时，出现了一个与 RPC（远程过程调用）相关的错误。具体来说，HTTP/2 流在关闭时没有正常关闭，并且在读取 sideband 包时发生了意外断开连接。

而使用 SSH 通常更稳定，并且在处理大文件或大量数据时表现更好。

3. 配置 SSH 部署密钥

3.1 本地生成 SSH 密钥对

在本地终端或构建代理上运行：

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

说明：

•-t rsa：密钥类型为 RSA；•-b 4096：密钥长度 4096 位，增强安全性；•-C：注释，可填邮箱或用途；•-f deploy_key：密钥输出文件名。

执行后生成两个文件：

•deploy_key：私钥，用于身份验证；•deploy_key.pub：公钥，需添加到远程仓库的部署密钥列表中。

秘钥生成

3.2 将公钥添加到 Git 仓库

具体操作方式视平台而定：

•GitHub：仓库 → Settings → Deploy keys → Add deploy key；•GitLab：仓库 → Settings → Repository → Deploy Keys；•Bitbucket：仓库 → Repository Settings → Access keys。

一般建议使用 只读权限 的 Deploy Key，以提升安全性。

4. 在 Jenkins 中配置 SSH 凭据

4.1 添加 SSH 凭据

1.登录 Jenkins，进入 系统管理 → 凭据。2.选择对应的作用域（如 全局）。3.点击 Add Credentials，选择SSH Username with private key填写以下信息：

内容说明

1.保存凭据。

添加凭据

4.2 在 Jenkins Job 中配置 Git 仓库

在你的构建 Job 中：

1.在 Source Code Management 中选择 Git；2.将 Git 仓库地址改为 SSH 格式，如：

git@github.com:username/repo.git

3.在 Credentials 中选择你刚刚添加的 SSH 凭据；4.保存配置并尝试构建。

不出意外，你应该能看到类似下图的输出：

信任设置

这是因为 Jenkins 第一次连接时需要验证 SSH 主机密钥。我们接下来将配置主机密钥验证策略。

4.3 配置 SSH 主机密钥验证

Jenkins 的 Git 插件支持自定义 SSH 主机密钥验证策略，以防止中间人攻击。可选策略说明（参考 Git Client Plugin 文档[1]）：

说明

在 Jenkins 中配置方式：

1.进入 系统管理 → 全局安全设置；2.找到 Git plugin 部分；3.设置 Git Host Key Verification Configuration。

信任设置

1.这里我们选择 Manually provided keys，并将 GitHub 的SSH 公钥添加到文本框中。可以使用本地的 known_hosts 文件，或者直接从 GitHub 获取：

ssh-keyscan -t rsa github.com

SSH 公钥

5. 验证与测试

完成上述配置后：

•手动运行一次 Job，确认能成功克隆代码；•查看控制台输出是否有如下类似信息：

Cloning the remote Git repository...
Using credentials github-ssh
> git init ...
> git fetch --tags --progress git@github.com:xxx/xxx.git ...

若成功，则表示 SSH 配置无误。

6. 常见问题与排查建议

7. 总结

通过配置 SSH 部署密钥，你可以：

•避免 Jenkins 使用 HTTP 协议拉取代码时的 RPC 错误；•提升 CI 流程中的稳定性；•加强身份验证安全性。

建议将 deploy_key 设置为项目独立密钥，避免多个项目共享同一密钥，提高安全性与可维护性。

References

[1] Git Client Plugin 文档: https://plugins.jenkins.io/git-client/#plugin-content-ssh-host-key-verification