Jenkins插件01:安装、升级与回滚

《Jenkins 插件生产治理》系列第 1/9 篇

01　先理解 Jenkins 插件体系

一个可维护的 Jenkins 平台通常可以分为以下几层：

1.1 插件的四种关系

插件包通常是 .hpi 或 .jpi 文件。Jenkins 官方更新中心会提供插件元数据、依赖和最新兼容版本。

1.2 生产环境选择插件的标准

安装前至少检查：

1. 插件是否仍在维护，是否显示“up for adoption”或已停止维护。
2. 插件页面的 Health Score、最近发布时间和未关闭问题。
3. 当前版本要求的 Jenkins 最低版本。
4. 页面是否存在未修复的 Security Warning。
5. 是否已有 Jenkins 核心、Pipeline 标准步骤或现有插件提供同等能力。
6. 是否支持 Pipeline，而不是只支持 Freestyle。
7. 是否会在 Controller 上执行用户脚本、访问网络或渲染 HTML。

02　插件安装、更新、回滚和卸载

2.1 Web 页面安装

适合少量插件和测试环境。

1. 进入 Manage Jenkins → Plugins。
2. 在 Available plugins 中搜索插件名称或 ID。
3. 打开插件详情，检查最低 Jenkins 版本、依赖、健康度和安全警告。
4. 勾选插件，选择 Install。
5. 安装完成后做一次测试构建；生产环境建议在维护窗口重启 Controller。

如果可用插件列表为空，可检查更新中心地址、代理、DNS 和 TLS；然后使用 Check now 刷新元数据。

2.2 Jenkins CLI 安装

适合临时自动化，但不如 plugins.txt 容易复现。

常用选项：

• -deploy
  ：安装完成后立即加载；并非所有插件都能无重启生效。
• -restart
  ：成功安装后重启 Jenkins，生产环境慎用。
• SOURCE
  ：可以是更新中心的插件 ID、本地文件或 URL。

不要把用户名、密码或 API Token 直接写入代码仓库和命令历史。应从受保护的环境变量、临时凭据文件或 Secret 管理系统读取。

2.3 Docker 镜像内预装：推荐的可复现方式

plugins.txt：

Dockerfile：

构建时，Jenkins Plugin Installation Manager 会解析并安装依赖。生产环境建议进一步锁定已验证版本，例如：

上面的版本只是格式示意，不应原样使用。正确流程是：在测试环境解析一组与当前 Jenkins LTS 兼容的版本，验证通过后把实际版本锁定到仓库。

2.4 离线安装

1. 在能访问互联网的相同 Jenkins 版本环境中解析插件及全部依赖。
2. 保存插件包、校验值和插件清单。
3. 通过 Manage Jenkins → Plugins → Advanced settings 上传插件包，或放入 $JENKINS_HOME/plugins/。
4. 确认文件属主和权限正确后重启 Jenkins。
5. 在系统信息和已安装插件页面核对加载结果。

不要只下载一个主插件的 .hpi。缺少依赖或依赖版本不兼容，是离线安装失败最常见的原因。

2.5 更新前的标准流程

至少验证登录、权限、凭据、Webhook、参数页面、共享库、Agent 连接、构建、归档和通知。

2.6 回滚与卸载

• 更新前完整备份 $JENKINS_HOME，包括 plugins/、任务配置、凭据相关文件和密钥。
• 插件降级可能遇到配置格式不向后兼容，不应只替换单个 .jpi 后直接启动生产。
• 卸载前查看 Installed plugins 中的依赖关系，先停用使用该插件的任务。
• Disable
   适合观察期；确认没有任务依赖后再 Uninstall。
• 不要在运行中的 Controller 上手工删除依赖插件文件。

可用以下 Groovy 在 Script Console 查看已加载插件，但 Script Console 权限极高，只应允许少数管理员使用：

///　写在最后

插件数量不是能力指标。能说明每个插件为什么存在、谁负责、如何升级和回滚，才是生产 Jenkins 的起点。

我是做梦的笔，持续分享 AI、云原生与研发效能实践。