离线部署 Jenkins 填坑指南
离线部署 Jenkins 填坑指南
你好，我是悟空。
本文目录如下：
一、背景
之前我带着大家实践了如何在 Windows 系统在线部署 Jenkins、如何通过 Jenkins 部署前后端项目，以及 Jenkins 的权限管理。
在实际项目中，通过这些实践，目前已经稳定运行了两个月，现在又有了一个新项目也是需要用 Jenkins 来实现自动化部署，但新项目的部署环境是 Linux 离线环境，所以我需要在离线环境上再部署一遍。
因为部署 Jenkins 的机器上没有网络，所以部署的过程中遇到了很多坑，本篇文章也是为了记录期间遇到的坑，以及解决方案。
二、依赖项
部署后端项目时需要依赖 Java、Maven、Git，对应的离线包版本如下表所示。
序号 | 依赖项 | 版本 |
|---|---|---|
1 | Linux 服务器 | 建议 ubuntu 20 以上 |
2 | Jenkins 离线 war 包 | 2.426.1（当前最新版本） |
3 | Java 离线包，后端部署需要 | Java 11, Java 17 or Java 21 |
4 | Maven 离线安装，后端部署需要 | Maven 3.8.8 |
5 | Git 离线包，拉取代码 | 2.9.5（当前最新版本） |
关于离线部署前端项目会放到下一讲。
三、下载 Jenkins 安装包
安装包路径：
https://get.jenkins.io/war-stable/
选择版本：2.426.1
下载完是一个 war 包，后续用 Java 启动这个 war 包即可。
四、安装 Java
下载 Java 17 安装包
创建目标目录
sudo mkdir -p /usr/local/java
复制安装包到目标目录
sudo cp /path/to/jdk-17_linux-x64_bin.tar.gz /usr/local/java
解压安装包
cd /usr/local/java
sudo tar -xvzf jdk-17_linux-x64_bin.tar.gz
移除压缩包
sudo rm jdk-17_linux-x64_bin.tar.gz
配置环境变量
sudo vim /etc/profile
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
export JAVA_HOME=/usr/local/java
export PATH=$PATH:$JAVA_HOME/bin
加载环境变量
source /etc/profile
检查 Java 版本
java -version
java 版本
五、启动 Jenkins
启动方式分为两种：
- 直接启动
- 后台静默启动
直接启动 jenkins
执行启动的命令：
java -jar jenkins.war --httpPort=8082
后台静默启动
执行启动的命令：
nohup java -jar jenkins.war --httpPort=8082 >nohup.out 2>&1 &
打开 Jenkins 站点
打开 Jenkins 站点 http://<你的服务器ip>:8082。
遇到异常，提示如下：
java.lang.RuntimeException: Fontconfig head is null, check your fonts or fonts configuration
解决方案：
将安装了 java8 的 fontconfig.bfc 文件拷贝到 jenkins 那台服务器上的 java lib 目录下
fontconfig.bfc 示例路径：C:\Program Files\Java\jre1.8.0_191\lib\fontconfig.bfc
拷贝到 /usr/local/java/lib/ 目录
再次启动，运行成功。另外有一个提示无法访问 jenkins 更新网站的错误，可以忽略，因为该服务器没联网所以访问不到。
jenkins 运行目录
另外还需要从打印的日志找到 jenkins 的运行目录，后续会用到。
如下图所示，在 /home/xxx/.jenkins 目录。
jenkins 运行目录
该目录下有一个非常重要的目录：plugins，我们可以拷贝一些插件到这个目录里面，这样 jenkins 就可以启动这些插件了。
六、配置 maven
下载地址：
https://maven.apache.org/download.cgi
解压文件夹：
cd /usr/local
tar -zvxf /usr/local/maven/apache-maven-3.8.8-bin.tar.gz
mv apache-maven-3.8.8/* maven
sudo rm -rf apache-maven-3.8.8
sudo rm -rf /usr/local/maven/apache-maven-3.8.8-bin.tar.gz
添加环境变量：
sudo vim /etc/profile
配置信息：
export M2_HOME=/usr/local/maven
export MAVEN_HOME=/usr/local/maven
export PATH=${M2_HOME}/bin:${PATH}
加载配置
source /etc/profile
查看 maven 配置是否生效：
mvn -version
七、配置 Git
下载安装包
网站路径：https://mirrors.edge.kernel.org/pub/software/scm/git/
拷贝到这个目录下 /usr/local/git/，如果没有 git 目录则新建一个。
sudo mkdir -p /usr/local/git
解压 git 安装包
sudo tar -xvzf /usr/local/git/git-2.9.5.tar.gz -C /usr/local/git
编译 git
cd /usr/local/git
./configure --prefix=/usr/local/git
make && make install
提示没有 gcc 编译器
解决方案：离线安装依赖包。
- 下载依赖的安装包
下载地址：https://pkgs.org/search/?q=libnl-genl
- 安装依赖的安装包
dpkg -i xxx.deb
再次编译，提示编译成功
添加 git 环境变量
export PATH=$PATH:/usr/local/git/bin
source /etc/profile
查看 git 版本
git --version
八、安装 Jenkins 插件
离线环境下，不能通过直接选择插件安装的方式，所以需要将插件的离线包导入到 plugins 目录下。
- 方式一：在线下载插件离线包并导入到 Jenkins 后台。
- 方式二：批量拷贝同版本 Jenkins 在线安装的插件。
方式一：下载插件并导入
以下两个站点都可以在线下载插件。
https://plugins.jenkins.io/
http://updates.jenkins-ci.org/download/plugins/
安装 Git 插件
可能会提示依赖的插件不存在，如下所示：
- Plugin is missing: structs (308.v852b473a2b8c)
- Plugin is missing: workflow-scm-step (2.13)
- Plugin is missing: scm-api (595.vd5a_df5eb_0e39)
- Plugin is missing: mailer (408.vd726a_1130320)
- Plugin is missing: credentials (2.6.1)
- Plugin is missing: git-client (3.11.0)
- Plugin is missing: script-security (1131.v8b_b_5eda_c328e)
- Plugin is missing: workflow-step-api (622.vb_8e7c15b_c95a_)
- Plugin is missing: credentials-binding (1.27.1)
- Plugin is missing: ssh-credentials (1.19)
因为有些插件依赖其他插件，所以需要先将其他插件安装，如果再安装的过程中又遇到缺失其他的插件，都按这种方式处理。
方式二：批量拷贝已安装的插件
先在有网的机器上部署相同的版本的 Jenkins，然后在线安装所需插件，最后批量拷贝插件到离线的 Jenkins 插件目录下。
插件所在的目录一般在这里：
/home/<user>/.jenkins/plugins/
拷贝之后，重启 Jenkins 就会自动安装这些插件了。
九、配置全局工具
配置 Maven settings
在 Jenkins 后台系统管理->全局工具配置中添加 Maven settings 配置，如下图所示。
路径为 Maven setting 的文件路径：/usr/local/maven/conf/settings.xml。
配置 Maven 安装
在 Jenkins 后台系统管理->全局工具配置中添加 Maven 安装配置，如下图所示。
路径为 Maven 的安装路径：/usr/local/maven/。
配置 Java JDK
在 Jenkins 后台系统管理->全局工具配置中添加 Java 配置，如下图所示.
路径为 Java 的安装路径：/usr/local/java/。
JDK 路径配置
配置 Git
在 Jenkins 后台系统管理->全局工具配置中添加 Git 配置，如下图所示：
路径为 Java 的安装路径：/usr/bin/git。
十、问题
问题 1、pipeline 输入框没有显示出来
F12 调试工具可以报错信息如下：
jenkins workflow-editor.js Ajax is not defined ReferenceError: Ajax is not defined
原因
插件有问题。
解决方案
替换所有插件文件。安装一个同样版本的 jenkins，并在线下载插件，并删除原 jenkins 的插件目录，然后替换全部插件文件。
问题 2、bat 命令不识别
java.io.IOException: Batch scripts can only be run on Windows nodes
原因
当前 Jenkins 部署在 Linux 系统中，所以不能识别 bat 命令。因为 bat 命令是 windows 系统使用的命令，而 sh 命令才是 linux 系统使用的命令。
解决方案
将 bat 改为 sh。
问题 3、执行 sudo 命令需要密码
SSH: EXEC: STDOUT/STDERR from command [sudo docker service update --force job-executor] ...
SSH: EXEC: connected
sudo: no tty present and no askpass program specified
原因
由于 jenkins 帐号并没有开启免密码导致的。
解决方法
给jenkins添加不用密码使用sudo的权限。
sudo vi /etc/sudoers
在sudoers文件中加一行：
jenkins ALL=(ALL) NOPASSWD:ALL
问题 4、RoleBasedAuthorizationStrategy 插件问题
报错信息
SEVERE jenkins.InitReactorRunner$1#onTaskFailed: Failed Loading global config
com.thoughtworks.xstream.mapper.CannotResolveClassException: com.michelin.cio.hudson.plugins.rolestrategy.RoleBasedAuthorizationStrategy
原因
jenkins 插件安装有问题导致无法启动 jenkins
解决方案
修改 /home/xxx/.jenkins/config 文件
<authorizationStrategy class="hudson.security.FullControlOnceLoggedInAuthorizationStrategy">
<denyAnonymousReadAccess>true</denyAnonymousReadAccess>
</authorizationStrategy>
问题 5、需要更新插件版本
部分插件由于缺少依赖无法加载。要恢复这些插件提供的功能，需要修复这些问题并重启 Jenkins。
原因
缺少插件或版本不正确。
解决方案
将对应的版本的插件 xxx.jpi 下载后，在后台上传，部署插件完成后，勾选重启 jenkins 服务。
问题 6、Git 拉取代码提示证书问题
报错信息：
server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile:
原因
缺少证书。
解决方案
跳过 Git 的证书验证。
git config --global http.sslVerify false
问题 7、配置环境变量后，找不到 sudo 命令
报错信息：
Command 'sudo' is available in '/usr/bin/sudo'
原因
环境变量配置有问题，找不到
解决方案
使用以下命令重新打开 /etc/profile 文件
/usr/bin/sudo /usr/bin/vim /etc/profile
把以下环境变量配置到 profile 中的其他环境变量之前
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
问题 8、Jenkins 时区问题相差 8 小时
解决方案
进入 Jenkins 的系统管理页面。
点击“脚本命令行”。
执行以下命令以设置时区为北京时间：
System.setProperty('org.apache.commons.jelly.tags.fmt.timeZone', 'Asia/Shanghai')
确保时区设置正确以便任务构建和定时构建按照北京时间触发。
十一、总结
本篇讲解了在离线环境下如何部署 Jenkins、Jenkins 插件、Maven、Java、Git 工具。
在部署的过程中遇到了很多坑，遇到一个解决一个，希望大家在以后遇到类似问题时，能根据本文档缩短排查问题的时间。