Jira Cloud上传Spring Boot插件出现JWT报错如何解决

AI 小北

2026-8-27

问题根因说明

你日志中打印的Could not find an installed host、Failed to authenticate request属于正常的预期WARN日志，不是致命报错，是Atlassian Connect Spring Boot（ACSB）框架处理首次安装回调的标准流程：

Jira首次向你的应用发送/installed生命周期回调时，应用本地数据库还没存储当前Jira实例的授权信息，第一次JWT校验自然查不到对应host记录
框架默认对安装回调接口放通未知来源的合法JWT请求，对应日志里的Received JWT authentication from unknown host, but allowing anyway
最后一行Saved installation for host https://KoK345.atlassian.net日志已经说明安装回调处理成功，Jira实例的授权信息已经写入应用存储，这一段流程没有问题。

真正导致应用上传后不可用的问题，集中在配置和实现的几个错误点。

存在的配置/实现错误

描述符（connect.json）配置不规范：直接复用了官方示例的应用keyatlassian-connect-spring-boot-sample-basic，如果当前Jira实例之前安装过官方示例应用，会出现安装覆盖冲突；后续如果要上架Atlassian Marketplace，这个key也不符合全局唯一要求。另外配置的generalPages挂载位置system.top.navigation.bar是Jira旧版UI的导航位，新版Jira Cloud不会在顶部导航渲染该位置的应用入口，会导致安装后找不到应用入口。
静态资源映射缺失：配置的应用入口页是/index.html，如果没有把该文件放到Spring Boot默认的静态资源目录（src/main/resources/static/、src/main/resources/public/等），访问时会直接返回404。
安全配置拦截风险：如果自定义了Spring Security安全规则，没有把/installed、/uninstalled生命周期路径加入白名单，或者手动把X-Frame-Options响应头修改为DENY/SAMEORIGIN，会导致Jira无法在iframe中加载应用页面，出现白屏。
上下文路径不匹配：如果在Spring Boot配置中设置了server.servlet.context-path服务上下文路径，connect.json里所有路径（生命周期回调、页面地址）都没有加对应前缀，会导致路径不匹配返回404。

修复步骤

修正connect.json配置：
- 替换key字段为自定义全局唯一值，推荐用反向域名格式，比如com.yourname.jira-custom-addon
- 把generalPages的location从废弃的system.top.navigation.bar改成新版Jira支持的位置：要放在顶部用户菜单下用userNavigation，要放在项目左侧侧边栏用jira.project.sidebar.plugins.navigation
- 如果配置了服务上下文路径，所有接口、页面路径前都要加上对应前缀
- 上传前校验JSON语法，确保没有多余逗号、括号不匹配、非法转义字符问题
  修正后的参考配置：
```
{
  "key": "com.yourcustom.jira-demo-addon",
  "baseUrl": "https://你的ngrok公网地址",
  "name": "Custom Jira Addon",
  "authentication": {
    "type": "jwt"
  },
  "apiMigrations": {
    "signed-install": true
  },
  "lifecycle": {
    "installed": "/installed",
    "uninstalled": "/uninstalled"
  },
  "modules": {
    "generalPages": [
      {
        "key": "main-app-page",
        "location": "userNavigation",
        "name": {
          "value": "My Addon"
        },
        "url": "/index.html"
      }
    ]
  }
}
```
校验静态资源路径：把入口页index.html放到src/main/resources/static/目录下，启动应用后直接访问https://你的ngrok地址/index.html，确认页面能正常打开，再重新在Jira中上传安装。
检查安全配置：如果自定义了Spring Security规则，确保ACSB框架的自动配置生效，不要拦截生命周期回调路径，不要覆盖框架默认的X-Frame-Options配置（框架默认允许atlassian域名下的页面通过iframe嵌入应用）。
每次重启ngrok后，同步更新connect.json里的baseUrl为新生成的ngrok公网地址，重启Spring Boot应用，再重新上传描述符，避免旧的host缓存导致JWT校验失败。

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