深入了解 Jenkins、GitLab 和 SSH 密钥的配置与管理

深入了解 Jenkins、GitLab 和 SSH 密钥的配置与管理

在现代软件开发中，持续集成和持续交付（CI/CD）已经成为了至关重要的实践。Jenkins 作为一个开源自动化服务器，广泛用于构建、测试和部署软件项目。而 GitLab 则是一个强大的源代码管理平台，提供 Git 仓库托管服务。在将这两者结合时，SSH 密钥的配置和管理是必不可少的。本文将详细探讨 Jenkins 和 GitLab 中 SSH 密钥的生成、配置、常见问题及其解决方案。

一、SSH 密钥的基础知识

1. 什么是 SSH 密钥？

SSH（Secure Shell）密钥是一种加密方法，用于在计算机之间安全地传输数据。它通常由一对密钥组成：私钥和公钥。公钥可以公开分发，而私钥则必须严格保密。

• 公钥：用于加密信息，可以与任何人共享。服务器使用公钥来加密消息，只有拥有私钥的人才能解密。
• 私钥：用于解密信息，必须安全存储，绝不能与他人分享。

2. SSH 密钥的优点

• 安全性高：相比传统的用户名和密码，SSH 密钥提供了更高的安全性。
• 无密码登录：配置好后，可以实现无密码登录，提升操作的便利性。
• 可自动化：在 CI/CD 流程中，SSH 密钥可以自动化操作，避免手动输入密码。

二、在 Linux 上生成 SSH 密钥

生成 SSH 密钥的过程相对简单。在 Linux 系统中，您可以通过以下步骤生成 SSH 密钥对：

打开终端。

执行以下命令：

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

这里，-t rsa 指定密钥类型为 RSA，-b 2048 指定密钥长度为 2048 位，-C 用于添加注释（通常是您的电子邮件地址）。

根据提示选择密钥保存位置和输入密码（可选）。默认情况下，密钥会保存在 ~/.ssh/id_rsa 和 ~/.ssh/id_rsa.pub。

示例生成过程：

$ ssh-keygen -t rsa -b 2048 -C "your_email@example.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/home/your_user/.ssh/id_rsa): 
Created directory '/home/your_user/.ssh'.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/your_user/.ssh/id_rsa
Your public key has been saved in /home/your_user/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx your_email@example.com
The key's randomart image is:
+---[RSA 2048]----+
|                 |
|        .        |
|   . . .o .     |
|  . + = + + .    |
| o o S = + . o   |
|..= E O . = =    |
| .+ = = + +      |
|  +.*B * + .     |
| o==+ o . o      |
+----[SHA256]-----+

在此过程中，会生成一个私钥（id_rsa）和一个公钥（id_rsa.pub）。

三、将公钥添加到 GitLab

生成 SSH 密钥后，下一步是将公钥添加到 GitLab。执行以下步骤：

复制公钥：

使用以下命令查看并复制公钥内容：

cat ~/.ssh/id_rsa.pub

登录 GitLab：进入您的 GitLab 账户。

导航到 SSH 密钥设置：

点击右上角的头像，选择 Preferences > SSH Keys。

添加公钥：

在 Key 字段中粘贴您的公钥，然后点击 Add key。

四、在 Jenkins 中配置 SSH 密钥

Jenkins 需要使用 SSH 密钥来访问 GitLab 仓库。以下是配置 SSH 密钥的步骤：

1. 登录 Jenkins：打开 Jenkins 的网页界面并登录。
2. 进入凭据管理：在左侧菜单中选择 Manage Jenkins > Manage Credentials。
3. 添加 SSH 凭据：
   • 选择合适的域（通常是 (global)）。
   • 点击 Add Credentials。
   • 在凭据类型中选择 SSH Username with private key。
   • 填写 Username（通常为 git）。
   • 在 Private Key 部分，选择 Enter directly，并将私钥（id_rsa）的内容粘贴到此处，包括起始和结束标记。

示例填充内容：

Username: git
Private Key: 
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAtyTw3I2gNoC+nmw8Lk6sX3WxNMab+ng5uFJpunDG18S1CHAH
...
-----END RSA PRIVATE KEY-----

1. 保存凭据。

五、验证 Jenkins 与 GitLab 的连接

配置完 SSH 密钥后，需要验证 Jenkins 是否能够成功连接到 GitLab：

1. 创建新任务： 在 Jenkins 首页，点击 New Item 创建一个新任务。
2. 选择 Git 源： 在任务配置页面，选择 Git 作为源代码管理工具，输入 GitLab 仓库的 SSH URL，如 git@gitlabnew.1nmob.com:ad/server/ysx-adcontrol.git。
3. 配置凭据： 在 Credentials 下拉菜单中选择之前添加的 SSH 凭据。
4. 保存并构建： 点击 Save，然后点击 Build Now 进行构建。
5. 检查构建日志： 如果连接成功，构建日志中将显示成功克隆仓库的信息；如果出现错误，检查日志以了解具体问题。

六、常见问题及解决方案

1. Host key verification failed

错误信息：

Host key verification failed.

原因：Jenkins 试图连接到 GitLab 时，发现该主机的密钥未在 known_hosts 文件中，导致 SSH 拒绝连接。

解决方案：

手动将 GitLab 的公钥添加到 Jenkins 服务器的 ~/.ssh/known_hosts 文件中。可以使用以下命令：

ssh-keyscan gitlabnew.1nmob.com >> ~/.ssh/known_hosts

确保 SSH 配置文件中未启用严格主机密钥检查（StrictHostKeyChecking）。

2. SSH Authentication failed

错误信息：

Permission denied (publickey).

原因：SSH 密钥未正确配置或未在 GitLab 中添加公钥。

解决方案：

• 确保将公钥正确添加到 GitLab。
• 确保 Jenkins 中配置的私钥与生成公钥时使用的私钥相匹配。

3. Git version too old

错误信息：

The recommended git tool is: NONE

原因：Jenkins 可能正在使用过时的 Git 版本。

解决方案：

更新 Jenkins 所在服务器的 Git 版本。使用以下命令安装最新版本的 Git：

sudo yum update git  # CentOS
sudo apt-get update && sudo apt-get install git  # Ubuntu

七、总结

在 Jenkins 和 GitLab 的集成中，SSH 密钥的配置是至关重要的。通过正确的步骤生成 SSH 密钥、将公钥添加到 GitLab，以及在 Jenkins 中配置 SSH 凭据，可以有效地实现无缝的代码管理和持续集成。

此外，处理 SSH 连接中的常见问题可以帮助确保构建流程的顺利进行。通过本篇博客，您应该对 SSH 密钥的生成、配置及其在 Jenkins 和 GitLab 中的使用有了深入的了解，为您的 CI/CD 流程奠定坚实的基础。