插件选型、升级与回退

验证：未记录

适用版本: 未记录
验证范围: 尚未登记验证记录。

Jenkins 插件运行在 Controller 中，常常提供新的权限、凭据类型、Pipeline 步骤和外部连接。选型先看它改变了哪条信任边界，再看维护状态和兼容性；不要把“安装量高”当作批准依据。官方插件管理

1. 建立准入记录#

给每个直接选择的插件记录下表；依赖插件也要进入实际版本清单，但不必为每个依赖写独立教程。

字段	要核对的事实
用途与负责人	哪个受保护的 Job/能力需要它，谁负责升级和退出
插件 ID 与来源	Jenkins 插件站点的准确 ID、发布记录、维护与安全警告
兼容组合	核心 LTS、Java、插件及其依赖的最低要求；在目标组合启动验证
新增能力	全局权限、凭据访问、脚本执行、Webhook、云 API、Agent 连接
退出路径	哪些配置和 Job 引用了它，禁用后如何恢复

当前样本清单是部署输入，不是推荐安装所有插件的清单。没有业务使用者的插件不应仅因“常用”而预装。第三方插件在安装前核查其页面的安全警告和组织维护要求；有未解决问题时评估替代方案或推迟接入。

2. 固定完整运行组合#

配置即代码中的 plugins.txt 固定顶层插件版本，但依赖解析也会影响最终组合。构建一次候选镜像，把最终镜像 digest、Jenkins 核心、Java、实际安装的全部插件版本、JCasC 提交号作为一个发布记录。生产和预生产晋级同一个镜像 digest；不要在两个环境分别执行在线“更新所有插件”。

在隔离实例中，通过 Manage Jenkins → Plugins → Installed 核对实际版本和依赖。把记录与上次基线比较，重点确认新增、删除、降级和安全公告。持久 Home 内旧插件可能影响预装版本，因此必须用目标 Home 的恢复副本验证启动，而不能只测试空白 Home。不要为“清理差异”直接删 plugins/ 目录。

以下是在隔离实例导出实际插件版本的方式。管理员 API token 放在权限为 0600 的 netrc 文件，不写进命令参数或构建日志；输出只含插件 ID、版本和启用状态。JENKINS_URL 指向隔离实例。

: "${JENKINS_URL:?}" "${JENKINS_NETRC:?}"
curl --fail --silent --show-error --globoff --netrc-file "$JENKINS_NETRC" \
  "$JENKINS_URL/pluginManager/api/json?tree=plugins[shortName,version,active,enabled]" |
  jq -r '.plugins[] | [.shortName, .version, .active, .enabled] | @tsv' |
  sort > plugins-actual.tsv
diff -u plugins-previous.tsv plugins-actual.tsv || true

JENKINS_NETRC 的格式是 machine HOST login USER password API_TOKEN，文件只给执行者读取；不要归档该文件。差异要逐项判定，不能用 || true 的退出码代表升级验收成功。

3. 分阶段升级与负向验收#

阅读目标核心版本的 LTS 升级指南和所涉插件发布记录、安全警告；确定受影响 Job、API 和配置字段。
备份 Home 与密钥，创建隔离恢复副本；断开生产 Webhook、Agent 与云身份。
在副本上运行候选镜像，确认启动无插件依赖或 JCasC 错误，实际插件清单与发布记录一致。
验证一个普通构建、一个不可信 PR、一个凭据拒绝案例、一个 Agent 创建与删除案例，以及一次发布锁互斥。按组织真实路径增减案例。
维护窗口内晋级相同镜像和配置；观察队列、失败 Job 与告警。失败时使用对应 Home 快照、密钥、镜像 digest 和配置提交整体恢复。

插件升级可能改变序列化数据或配置格式，不能假设把镜像改回旧版本就能安全降级同一个 Home。操作顺序和恢复边界见备份、升级与排障。

4. 禁用和卸载#

先在恢复副本停用候选插件，检查依赖它的 Job、JCasC、凭据类型、Agent 模板和 Pipeline 步骤是否还能加载。禁用是观察退出影响的第一步；卸载前要确认没有其他插件依赖它，并保存可恢复备份。插件卸载后原配置可能保留，不能把“插件不在列表”视为所有敏感设置已消失。官方禁用与卸载说明