本文檔介紹了如何在 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 56 GnuTLS 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填寫以下信息：

字段	內容說明
Id	內部唯一ID，可以為空，會自動生成一個，本案例中也可以填 deploy_user
Username	任意標識名（如 git 或 deploy_user）
Private Key	選擇 “Enter directly”，粘貼 deploy_key 的內容
Passphrase	如果有設置過密鑰密碼，則在此輸入

4. 保存憑據。

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 文檔）：

策略名稱	說明
Known hosts file (默認)	使用 ~/.ssh/known_hosts 進行校驗
Accept first connection	第一次連接自動信任并緩存主機密鑰（適用于自動化場景）
Manually provided keys	手動維護一組受信任的主機密鑰
No verification (不推薦)	完全跳過驗證，存在安全風險

在 Jenkins 中配置方式：

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

4. 這里我們選擇 Manually provided keys，并將 GitHub 的SSH 公鑰添加到文本框中。可以使用本地的 known_hosts 文件，或者直接從 GitHub 獲取：

ssh-keyscan -t rsa github.com

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. 常見問題與排查建議

問題	原因	解決方案
構建報錯 “Permission denied (publickey)”	公鑰未配置正確	檢查公鑰是否添加至 Git 倉庫
報錯 “Host key verification failed”	主機密鑰未受信任	設置正確的主機驗證策略或添加到 known_hosts
連接 GitHub 太慢	國內網絡問題	嘗試使用加速服務或鏡像倉庫

7. 總結

通過配置 SSH 部署密鑰，你可以：

• 避免 Jenkins 使用 HTTP 協議拉取代碼時的 RPC 錯誤；
• 提升 CI 流程中的穩定性；
• 加強身份驗證安全性。

建議將 deploy_key 設置為項目獨立密鑰，避免多個項目共享同一密鑰，提高安全性與可維護性。