安全重载Jenkins配置，无需重启

重载Jenkins配置听起来无害，直到你在繁忙的控制器上执行此操作，并发现并非所有更改都能在作业运行时干净地应用。正确的命令取决于更改的内容。

如果你编辑了JENKINS_HOME中的XML文件、从备份恢复了作业，或在Web UI之外更改了文件，Jenkins可以从磁盘重载配置。如果你安装或升级了插件、更改了Java选项，或需要刷新运行时状态，安全重启通常是更好的工具。这些是不同的操作。

应避免的误导性快捷方式是在脚本控制台中使用System.exit(10)。根据Jenkins的启动方式，它可能导致进程管理器、Servlet容器或服务包装器重启Jenkins，但这并不是一个干净的“重载配置”命令。它可能中断工作并隐藏意图。请改用Jenkins CLI或内置的管理操作。

使用CLI从磁盘重载配置

最清晰的命令是reload-configuration：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration

这告诉Jenkins丢弃已加载的配置并重新从磁盘读取。在受控的文件更改后（例如恢复作业配置或应用自动化生成的配置）非常有用。

在运行之前，检查三件事：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null

该账户需要管理权限才能重载配置。不要使用某人笔记本电脑上的个人管理员令牌进行日常自动化。使用托管的管理员账户，将令牌保存在密钥存储中，并根据你的策略定期轮换。

如果你更喜欢Web UI，请使用Manage Jenkins，并在你的Jenkins版本和已安装组件中可用时使用重载选项。CLI更容易审计，因为命令可以存在于运行手册中。

何时安全重启是更好的选择

安全重启会等待正在运行的构建完成，然后重启Jenkins。它比重载慢，但当运行时状态必须重建时，它更可靠。

在插件安装或升级、Java选项更改、Jenkins核心升级，或仅在完整控制器重启后出现的行为之后，使用安全重启。

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" safe-restart

如果环境允许，你也可以使用/safeRestart端点，但CLI形式更容易标准化。

不要承诺零停机。重载可能会短暂影响UI，而安全重启会在构建排空后有意重启控制器。如果代理断开连接或插件行为异常，用户可能会注意到。在影响范围可接受的时间安排操作。

更安全的重载运行手册

首先，宣布维护窗口，即使时间很短。然后检查正在运行的内容：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs

对于快速队列检查，通过CLI使用Groovy：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" groovy = <<'EOF'
Jenkins.instance.queue.items.each { item ->
  println "Queued: ${item.task.fullDisplayName}"
}
Jenkins.instance.computers.each { computer ->
  computer.executors.findAll { it.isBusy() }.each { executor ->
    println "Running on ${computer.displayName}: ${executor.currentExecutable}"
  }
}
EOF

备份你要依赖的配置。至少要有JENKINS_HOME的最近备份，特别是config.xml、作业目录、凭据元数据和插件状态。小心处理凭据文件；将备份作为机密保护。

运行重载：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration

然后验证控制器是否响应：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null

在宣布工作完成之前，检查系统日志和一个代表性作业。成功返回的重载仍可能暴露错误的作业XML、缺失的插件或权限问题。

关于Groovy重载脚本

脚本控制台功能强大，因为它在Jenkins控制器内部运行。这也是为什么需要谨慎的原因。任何脚本控制台用户都可以读取机密、修改作业、禁用安全控制或破坏控制器。

如果你需要Groovy进行检查，请保持只读且简短。例如：

println Jenkins.instance.version
println Jenkins.instance.items.size()
println Jenkins.instance.queue.items.size()

除非你已经针对你的Jenkins版本和插件进行了测试，否则避免使用未记录的内部重载调用。内部API可能会更改，插件特定的重载方法可能不会重载你关心的状态。

对于“配置即代码”设置，请使用插件文档化的重载机制，而不是通用的Jenkins重载。JCasC有自己的模型和验证行为，一个在磁盘上看起来正确的配置文件在应用时仍可能失败。

如果重载出错该怎么办

如果Jenkins返回时缺少作业、视图损坏或插件错误，不要继续点击重载。捕获系统日志，记录时间，并将更改的文件与备份进行比较。常见原因包括格式错误的XML、引用已卸载插件的作业配置，或在Jenkins仍在写入文件时进行的手动编辑。

如果UI不稳定但进程仍在运行，安全重启可能会清除临时状态。如果配置确实有问题，请先恢复之前的文件，然后重载或重启。

最安全的模式很简单：对磁盘配置更改使用reload-configuration，对运行时和插件更改使用safe-restart，并将脚本控制台保留用于你可以逐行解释的、经过深思熟虑的管理脚本。