Keycloak18.0.1启动报错context-propagation jar不存在如何解决

报错核心是Keycloak安装目录结构异常，出现lib目录嵌套。
正常Keycloak 18.0.1的依赖包路径为${安装根目录}/lib/main/xxx.jar，但报错中读取的路径为/srv/keycloak/lib/lib/main/xxx.jar，多嵌套了一层lib目录，导致启动构建阶段扫描依赖时找不到对应jar包。
常见触发场景：

• 手动复制、迁移解压文件时操作失误：将压缩包内的子文件直接复制到了已存在的lib目录下，而非Keycloak根目录，造成目录嵌套
• 残留错误环境变量：系统中配置的KEYCLOAK_HOME指向了错误路径，或残留旧版本Keycloak的配置，导致启动脚本读取路径规则异常
• 安装包损坏/解压不完整：下载的ZIP包校验不通过，解压时出现目录结构错乱

方案1：全量重新部署（推荐，出错概率最低） #

1. 删除当前损坏的部署目录

rm -rf /srv/keycloak

2. 重新解压官方安装包，不要手动拆分复制子目录

# 假设安装包存放在当前执行目录
unzip keycloak-18.0.1.zip -d /srv/
# 重命名为目标路径
mv /srv/keycloak-18.0.1 /srv/keycloak

3. 校验目录结构
   执行以下命令，如果能正常返回文件信息，说明结构正确：

ls /srv/keycloak/lib/main/org.eclipse.microprofile.context-propagation.microprofile-context-propagation-api-1.2.jar

4. 清理冲突环境变量
   检查/etc/profile、~/.bashrc、/etc/environment等系统配置文件中是否存在手动配置的KEYCLOAK_HOME项，如果指向非当前部署路径，直接删除对应配置，刷新配置后重新连接shell即可。Keycloak 18+版本的启动脚本会自动识别根目录，无需额外配置该环境变量。
5. 启动开发模式服务

cd /srv/keycloak
bin/kc.sh start-dev

方案2：快速修复现有部署 #

如果不想重新解压部署，可按以下步骤操作：

1. 进入lib目录，检查是否存在嵌套的lib子目录：

cd /srv/keycloak/lib
ls

2. 如果存在嵌套的lib文件夹，将其中所有内容移动到当前lib目录，删除空的嵌套文件夹：

mv ./lib/* ./
rm -rf ./lib

3. 清理历史构建缓存后重新启动：

cd /srv/keycloak
bin/kc.sh build --clean
bin/kc.sh start-dev

如果按以上步骤操作后仍报同类路径错误，校验本地下载的Keycloak ZIP包SHA256值，确认安装包未损坏后重新解压部署即可。

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