Windows下Jenkins2.319.1升2.346.1因${ITEM_FULLNAME}启动失败

安全阿岳

2026-8-27

问题现象

Windows环境下将Jenkins从2.319.1版本升级至2.346.1版本后，Jenkins服务无法正常启动，抛出如下错误信息：

java.nio.file.InvalidPathException: Illegal char <:> at index 87: C:\Users\$DEVTO~1\AppData\Local\Temp\Jenkins-doCheckRawBuildsDir18416011757244540585foo:bar
    at java.base/sun.nio.fs.WindowsPathParser.normalize(WindowsPathParser.java:182)
    at java.base/sun.nio.fs.WindowsPathParser.parse(WindowsPathParser.java:153)
    at java.base/sun.nio.fs.WindowsPathParser.parse(WindowsPathParser.java:77)
    at java.base/sun.nio.fs.WindowsPath.parse(WindowsPath.java:92)
    at java.base/sun.nio.fs.WindowsFileSystem.getPath(WindowsFileSystem.java:229)
    at java.base/java.io.File.toPath(File.java:2290)
    at jenkins.model.Jenkins.checkRawBuildsDir(Jenkins.java:3364)
Caused: jenkins.model.InvalidBuildsDir: D:\JenkinsData\jobs\${ITEM_FULLNAME}\builds contains ${ITEM_FULLNAME} but your system does not support it (JENKINS-12251). Use ${ITEM_FULL_NAME} instead
    at jenkins.model.Jenkins.checkRawBuildsDir(Jenkins.java:3366)
    at jenkins.model.Jenkins.loadConfig(Jenkins.java:3300)
Caused: java.io.IOException
    at jenkins.model.Jenkins.loadConfig(Jenkins.java:3303)
    at jenkins.model.Jenkins.access$1200(Jenkins.java:340)
    at jenkins.model.Jenkins$12.run(Jenkins.java:3398)
    at org.jvnet.hudson.reactor.TaskGraphBuilder$TaskImpl.run(TaskGraphBuilder.java:175)
    at org.jvnet.hudson.reactor.Reactor.runTask(Reactor.java:305)
    at jenkins.model.Jenkins$5.runTask(Jenkins.java:1158)
    at org.jvnet.hudson.reactor.Reactor$2.run(Reactor.java:222)
    at org.jvnet.hudson.reactor.Reactor$Node.run(Reactor.java:121)
    at jenkins.security.ImpersonatingExecutorService$1.run(ImpersonatingExecutorService.java:68)
    at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
    at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
    at java.base/java.lang.Thread.run(Thread.java:834)
Caused: org.jvnet.hudson.reactor.ReactorException
    at org.jvnet.hudson.reactor.Reactor.execute(Reactor.java:291)
    at jenkins.InitReactorRunner.run(InitReactorRunner.java:49)
    at jenkins.model.Jenkins.executeReactor(Jenkins.java:1193)
    at jenkins.model.Jenkins.<init>(Jenkins.java:983)
    at hudson.model.Hudson.<init>(Hudson.java:86)
    at hudson.model.Hudson.<init>(Hudson.java:82)
    at hudson.WebAppMain$3.run(WebAppMain.java:247)
Caused: hudson.util.HudsonFailedToLoad
    at hudson.WebAppMain$3.run(WebAppMain.java:264)

此前历次版本升级均未出现同类异常，查阅官方版本发布说明、升级指南文档，均未找到对应变量相关的变更记录。

触发原因

这个问题的核心是旧版本Jenkins存在校验逻辑疏漏：

当前配置的构建存储路径使用了${ITEM_FULLNAME}变量，该变量输出的任务全限定名使用/作为层级分隔符，Windows系统路径不识别该分隔符，嵌套任务场景下会生成不符合Windows路径规则的字符串，本身就不兼容Windows环境。
2.319.1及更早版本没有在启动阶段强制校验构建目录配置的合法性，错误配置不会阻断服务启动，只会在后续运行特定任务时偶发路径错误，所以之前升级一直没触发问题。
2.332及之后的版本补全了启动阶段的构建路径合法性校验逻辑，检测到Windows环境下使用${ITEM_FULLNAME}变量时会直接阻断启动，避免后续运行时出现更难排查的数据损坏、构建丢失问题。这个修复属于稳定性补丁，没有放在大版本的醒目变更提示里，很难在发行注记里直接搜到。
错误栈最开头的Illegal char <:>报错是校验逻辑生成临时测试路径时自带的测试后缀触发的系统级报错，属于校验流程的正常输出，不需要单独处理。

修复步骤

按以下操作修改配置即可恢复服务启动：

先结束所有残留的Jenkins进程，打开Jenkins主目录（从报错看主目录是D:\JenkinsData）下的config.xml配置文件。
在文件中搜索rawBuildsDir配置项，当前配置值大概率为${JENKINS_HOME}/jobs/${ITEM_FULLNAME}/builds，将其中的${ITEM_FULLNAME}替换为${ITEM_FULL_NAME}。注意两个变量的下划线差异：${ITEM_FULL_NAME}会自动适配当前操作系统的路径分隔符，Windows环境下会自动将任务层级的分隔符替换为\，不会生成非法路径。
保存配置文件，重新启动Jenkins服务即可正常加载。
如果担心历史构建路径不匹配，可以在启动前先检查D:\JenkinsData\jobs目录下的历史目录结构，确认层级分隔符为\，和新变量的路径生成规则一致，不会出现历史构建无法识别的问题。

内容的提问来源于stack exchange，提问作者SebG