开心每一天

Appearance

Docker 安装 Jenkins ​

Jenkins 官方镜像：https://hub.docker.com/r/jenkins/jenkins

Github Document: https://github.com/jenkinsci/docker/blob/master/README.md

安装 ​

shell
docker run -d --name jenkins -p 8080:8080 -p 50000:50000 --restart=always jenkins/jenkins:lts-jdk17

# 指定时区 -e PHP_TZ="Asia/Shanghai"
docker run -d --name jenkins -p 8080:8080 -p 50000:50000 -e PHP_TZ="Asia/Shanghai" --restart=always jenkins/jenkins:lts-jdk17

# 挂载卷
mkdir /opt/jenkins
chmod 777 /opt/jenkins

docker run -d --name jenkins -p 8080:8080 -p 50000:50000 -e PHP_TZ="Asia/Shanghai" --restart=always -v /opt/jenkins:/var/jenkins_home jenkins/jenkins:lts-jdk17

访问：http://localhost:8080

然后等待 jenkins 初始化，这个过程需要很长时间。jenkins 初始化完成后，浏览器自动进入 Jenkins 页面。

这个过程可能遇到问题：浏览器界面一直显示 Please wait while Jenkins is getting ready to work …

方案一：重启容器试试，有时候网络就好了，建议先多尝试几次。

方案二：如果方案一重试了好几次都不行，可能是网络被墙的太彻底的原因，尝试以下改动：

shell
docker exec -it jenkins /bin/bash

cd ~

# 找到一个名为：hudson.model.UpdateCenter.xml 的文件
ll

# 修改内容
# 将 https://updates.jenkins.io/update-center.json
# 更改为：https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json
vim hudson.model.UpdateCenter.xml

# 保存，退出

# 退出容器
exit

# 重启 jenkins
docker restart jenkins

解锁 Jenkins ​

shell
# 在启动日志中查看第一次登录时的密码
# You can access logs with command 'docker logs CONTAINER_ID' in order to check first login token.
docker logs jenkins
# docker logs -f jenkins

# 或者进入容器中查看
docker exec -it jenkins /bin/bash

cat /var/jenkins_home/secrets/initialAdminPassword

然后输入初始密码，进入新手入门配置。

新手入门 ​

点击：安装推荐的插件（如果自己选插件的话容易遗漏一些依赖项）

然后下一步，进入漫长的安装过程中，等待安装完成，如果有失败项，页面可以进行安装重试，如果实在安装不成功，也可以跳过，然后进入系统后，再在插件管理处纠正安装。

进入：【创建第一个管理员用户】这个可以直接【使用 admin 账户继续】

进入：【实例配置】默认 url 不用修改，【保存并完成】

初始安装到这里就完成了。

插件安装 ​

进入【系统管理】-【插件管理】检查如下插件是否安装，没安装的安装一下。

  • Git plugin ：拉取代码时需要（推荐插件安装的时候默认已安装）
  • Maven Integration ：编译 jar 时需要
  • NodeJS ：编译前端工程时需要
  • Publish Over SSH ：发送文件以及远程执行脚本、命令时需要

在左侧【Download progress】菜单下可以查看下载进度，在这个页面勾选【安装完成后重启 Jenkins(空闲时)】复选框，下载完成后会自动重启 jenkins 服务。

全局工具配置 ​

进入【系统管理】-【全局工具配置】

JDK 安装 ​

镜像 jenkins/jenkins:lts-jdk17 中默认使用的 jdk 17，如果刚好符合你的要求，那么下面可以略过。

可以通过以下命令查看默认 jdk 安装位置和环境变量：

shell
docker exec -it jenkins /bin/bash

jenkins@99fc0e7f70af:/$ java -version
openjdk version "17.0.11" 2024-04-16
OpenJDK Runtime Environment Temurin-17.0.11+9 (build 17.0.11+9)
OpenJDK 64-Bit Server VM Temurin-17.0.11+9 (build 17.0.11+9, mixed mode)

jenkins@99fc0e7f70af:/$ javac -version
javac 17.0.11

jenkins@99fc0e7f70af:/$ echo $PATH
/opt/java/openjdk/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

配置如下信息：

shell
# 别名
JDK17
# JAVA_HOME
/opt/java/openjdk

但你可能想用其他版本，比如 jdk 8，这时就需要额外安装 jdk 了，但是 OpenJDK 8 在 Debian 11 不再提供支持了，只能手动安装。

安装过程略（可参考其他博客安装），假定已经安装到 /opt/java8/bin 目录下了，配置如下信息。

配置如下信息：

shell
# 别名
JDK8
# JAVA_HOME
/opt/java/jdk1.8.0_202

至此，jenkins 构建时，便会使用这里配置的 JDK。

git 安装 ​

安装推荐的插件中已经包含了 git，因此无需额外安装，使用默认配置信息即可。

配置如下信息：

shell
# NAME
Default
# Path to Git executable
git

注：git 也可以手动安装，手动安装只需要配置 git 程序的位置。

注：上面代码段里的 git 相当于 Windows 下的 git.exe，在容器中已经加到了环境变量，可以直接使用 git 命令。

maven 安装 ​

配置如下信息：

shell
# NAME
maven
# MAVEN_HOME
/opt/maven/

然后勾选【自动安装】复选框，选择从 Apache 安装，再选择一个版本即可，容器中就会自动安装到配置的 /opt/maven/ 目录下。

注：maven 也可以手动安装，手动安装就不需要勾选自动安装复选框了，只需要配置 MAVEN_HOME 的位置。

NodeJS 安装 ​

配置如下信息：

shell
# 别名
nodejs
# 安装目录
/opt/nodejs

然后勾选【自动安装】复选框，选择Install from nodejs.org，再选择一个版本即可，容器中就会自动安装到配置的 /opt/nodejs 目录下。

注：nodejs 也可以手动安装，手动安装就不需要勾选自动安装复选框了，只需要配置安装目录的位置。

系统配置 ​

进入【系统管理】-【系统配置】

向下拉滚动条，找打【Publish over SSH】下的【SSH Servers】，点击【新增】按钮，新增一个或多个 SSH Server(根据需要)

SSH Server 配置示例如下：

shell
# Name
Vitality: 192.168.1.100:22
# Hostname
192.168.1.100
# Username
root
# 勾选复选框：Use password authentication, or use a different key
# 输入密码

# Remote Directory
/

# 点击【高级】按钮，展开后，填写端口等信息
# Port
22
# Timeout (ms)
300000

点击右下角【Test Configration】按钮，左下角有【Success】字样即代表连接成功。

然后保存即可，这样一个 SSH Server 就配置完成了，后面就可以直接引用。

其中，Remote Directory 值表示连接服务器后，进入的服务器根目录，建议配置为：/

凭据管理 ​

一般 git 拉取代码都需要用户名和密码，除非是开源的，这时候就需要添加凭据。

以配置 git 凭据为例，进入 【系统管理】-【凭据】，鼠标移动并点击表格列【域】下面的【全局】字样，进入全局凭据管理。

然后点击右上角【+ Add Credentials】，然后选择【Username with password】，输入 gitee 的登录用户名，私人令牌密码（ID 不用填写），保存即可。

下面就到正题了

Maven 构建和部署 ​

进入 Dashboard 首页，创建【构建一个 maven 项目】，输入名称，点确定后，进入配置。

源码管理 ​

选择【Git】单选框，输入代码仓库信息：

shell
# Repository URL
https://gitee.com/mengweijin/vitality.git
# Credentials
# Credentials 下拉框会自动带出【凭据】中提前配置的信息，直接选择即可。如果没有提前配置，这里也可以新增凭据。
# 指定分支（为空时代表any)
*/master

构建环境 ​

勾选在构建日志中添加时间戳前缀的复选框

Build ​

maven 的执行命令，可以加需要的构建参数。

shell
# Root POM
pom.xml
# Goals and options
clean package -Dmaven.test.skip=true -Psit

Post Steps ​

maven 打包后的后处理操作。勾选【Run only if build succeeds】单选框，只有打包成功才执行后处理操作。

点击【Add post-build step】按钮，可以选择【Send files or execute commands over SSH】选项，发送打包好的 jar 到目标主机并执行命令启动程序。

SSH Publishers

shell
# SSH Server 从前面【系统配置】中配置的服务器选择
Vitality: 192.168.1.100:22
# 然后点击【高级】

# 这个可以打印远程服务器上的日志
勾选【Verbose output in console】复选框

# 由于服务器连接可能失败，所以建议多 Retry 几次，配置参数：每个10秒重试一次，共重试10次
# Retry
10
# Delay
10000

Transfer Set

shell
# Transfer Set
# Source files
vitality-admin/target/vitality-admin.jar
# Remove prefix
vitality-admin/target/
# Remote directory（这里就用到【系统配置】时配置的服务器 Remote Directory 的参数值）
# 注意开头没有 /，/ 已经在服务器  Remote Directory 中配置了
# 直接发送文件到服务器启动位置：/opt/vitality/vitality-admin.jar
opt/vitality
# Exec command（这个文本域框初始有点小，可以用鼠标拖动变大的）

Exec command（这个文本域框初始有点小，可以用鼠标拖动变大的）

shell
# jar 包已经通过 jenkins 流水线放到指定位置了，只需要重启服务
# sed 命令，监控到 tail 日志中包含 “启动成功” 或者 “启动失败” 时退出 tail。
# 注意下面命令中：“启动成功” 后面的 “\” 符号，这里或运算符 “|” 需要被转义才行。
systemctl restart vitality
tail -f /opt/vitality/logs/debug/debug.log -n 200 | sed '/启动成功\|启动失败/ q'

至此，maven 打包并部署的配置就完成了，后续运行 pipeline 构建即可。

Vue 构建和部署 ​

进入 Dashboard 首页，创建【构建一个自由风格的软件项目】，输入名称，点确定后，进入配置。

源码管理 ​

选择【Git】单选框，输入代码仓库信息：

shell
# Repository URL
https://gitee.com/mengweijin/vitality.git
# Credentials
# Credentials 下拉框会自动带出【凭据】中提前配置的信息，直接选择即可。如果没有提前配置，这里也可以新增凭据。
# 指定分支（为空时代表any)
*/master

注：假如 vue 前端工程在仓库根目录下的：vitality-ui 目录下

构建环境 ​

勾选Provide Node & npm bin/ folder to PATH的复选框，这样才会自动安装 nodejs，提供 npm 命令。 勾选在构建日志中添加时间戳前缀的复选框

Build Steps ​

点击【增加构建步骤】按钮，选择【执行 shell】，输入：

注：

  • 查看 $WORKSPACE 目录：浏览器进入【系统管理】-【System】-主目录。默认 $WORKSPACE 为：/var/jenkins_home
shell
cd $WORKSPACE/vitality-ui
npm config set registry https://registry.npmmirror.com
export NODE_OPTIONS=--openssl-legacy-provider
npm install
npm run build

Send files or execute commands over SSH ​

点击【增加构建步骤】按钮，选择【Send files or execute commands over SSH】，输入：

SSH Publishers

shell
# SSH Server 从前面【系统配置】中配置的服务器选择
Vitality: 192.168.1.100:22
# 然后点击【高级】

# 这个可以打印远程服务器上的日志
勾选【Send files or execute commands over SSH】复选框

# 由于服务器连接可能失败，所以建议多 Retry 几次，配置参数：每个10秒重试一次，共重试10次
# Retry
10
# Delay
10000

Transfer Set

shell
# Transfer Set
# Source files
vitality-ui/dist/**
# Remove prefix
vitality-ui/
# Remote directory（这里就用到【系统配置】时配置的服务器 Remote Directory 的参数值）
# 注意开头没有 /，/ 已经在服务器  Remote Directory 中配置了
# 发送文件到服务器备份目录
# 注：为什么上面的 jar 可以不用备份？
#       因为 jar 可以直接从流水线构建历史中下载下来，流水线本身就有历史备份，
#       只是 npm 管理的工程没法在页面直接下载部署的文件出来，才需要曲线备份。
#       当然也可以不备份，有需要了直接 SSH 连接去流水线工作目录去找，然后手动下载。
# $BUILD_NUMBER 是引用的 jenkins 内置变量，是一个构建流水号
opt/vitality/build_vue_$BUILD_NUMBER
# Exec command（这个文本域框初始有点小，可以用鼠标拖动变大的）

Exec command（这个文本域框初始有点小，可以用鼠标拖动变大的）

shell
cp -r /opt/vitality/build_vue_$BUILD_NUMBER/dist/* /usr/share/nginx/html/
systemctl restart nginx

至此，vue 前端打包并部署的配置就完成了，后续运行 pipeline 构建即可。

用户角色和权限分配 ​

安装插件：Role-based Authorization Strategy ​

安装完成后，重启 jenkins 服务。

开启权限全局安全配置 ​

进入【系统管理】-【安全】-【全局安全配置】- 找到【授权策略】，然后切换为：【Role-Based Strategy】，保存。

保存之后，再次进入【系统管理】-【安全】导航，这时候就会发现多了一个【Manage and Assign Roles】选项卡，点击进入。

Manage Roles ​

点击左侧 Manage Roles 菜单，在右侧【Global roles】下的【Role to add】下面输入框输入一个新角色名称，比如：developer，然后点击【Add】按钮，就会添加一个新角色。

然后在复选框中勾选该角色需要的权限，最后点【保存】。

Assign Roles ​

点击左侧 Assign Roles 菜单，在右侧【Global roles】下的表格中点击【Add User】，然后选择一个用户，再然后勾选一个或多个角色复选框，最后保存即可。

至此，就完成了一个最简单的基于角色的用户权限控制。被授权的用户登录进来就只能查看或操作拥有角色权限对应的功能。

Gitee 码云 WebHooks 自动触发构建 ​

需要安装插件 Gitee Plugin

其他类似插件：Generic Webhook Trigger 插件，不过这一章节不需要这个。

然后进入【系统管理】-【凭据】，创建一个新凭据，选项为：

txt
类型选择：【Gitee API 令牌】

Gitee APIV5 私人令牌：填写从 gitee 生成的私人令牌

其他不用填写，保存即可。

注：这个私人令牌的值是和从 gitee 拉取代码时配置的【Username with password】类型的凭据的密码是一样的，但这两个类型不能公用，所以需要同时配置两个，各用各的。

然后进入【系统管理】-【Gitee 配置】参考以下配置：

txt
连接名：Gitee
Gitee 域名 URL: https://gitee.com
证书令牌(Gitee API V5 的私人令牌): 选择【Gitee API 令牌】

高级：
可以勾选上【忽略 SSL 证书错误】的复选框

然后点击右下角【测试】按钮，看是否出现【SUCCESS】字样，没问题保存即可。

配置流水线 ​

进入流水线的配置页面

shell
# 下面这个自动带出来的 URL 实际是需要也给公网可以访问的 URL，而不是 localhost，本文仅是给个示例。
找到并勾选【构建触发器】下面的【Gitee webhook 触发构建，需要在 Gitee webhook 中填写 URL: http://localhost:8080/gitee-project/vitality】选项的复选框。

# 记下来这个 URL 地址，后面在 Gitee 中配置 WebHooks 时要用。
# 地址：http://域名:端口/gitee-project/vitality

# Gitee 触发构建策略
勾选【推送代码】
勾选【接受 Pull Requests】

选择【根据分支名过滤】单选按钮
#包括
master

# Gitee WebHook 密码
点击右侧【生成】按钮，就会自动生成一个类似 uuid 的 Gitee WebHook 密码

保存

配置代码仓库中的 WebHooks ​

进入 Gitee 代码仓库页面，进入【管理】-【WebHooks】-【添加 WebHooks】，填写前面记下来的 URL 和生成的 Gitee WebHook 密码

shell
# URL:
http://localhost:8080/gitee-project/vitality

# WebHook 密码/签名密钥：
输入生成的 Gitee WebHook 密码

# 选择事件
勾选：【Push】 复选框
勾选：激活 复选框

# 然后点击添加按钮保存即可。

然后在浏览器 WebHooks 页面就可以看到类似这样一条记录：

POST → http://localhost:8080/gitee-project/vitality

特别注意：

此时，记录右侧有一个【测试】按钮，但是 Gitee 这个功能是有 Bug 的，在这里测试会直接 404！！！

参考: gitee 连接 Jenkins，webhook 返回 404 问题

所以，正确的测试方式是：直接提交一次代码，然后看 jenkins 有没有触发构建。

npm 构建日志卡在 npm install 不动 ​

一般是因为源比较慢，可切换国内源来解决。

shell
# 进入容器
docker exec -it jenkins /bin/bash

切换源参考：nodejs 的安装以及初始化 npm 环境