Jacksen的技术博客

问题1、平台/调度任务/任务调度中心，打开时报错：

前端检查发现一堆权限不匹配的后台API错误：

检查后台hzero-schedule服务的日志，没有错误信息。

看前端错误主要是hzero_platform.iam_permission表中缺少响应的api 记录。

解决方案是：去平台/开发管理/开发管理/系统工具/刷新权限 去手动刷新下IAM权限就好了。

这里点【刷新】的时候，偶尔会遇到违反唯一索引的错误，这种情况可以去数据库把hzero_platform.iam_permission表中，通过模糊搜索code的方法把对应模块的API权限记录全部清除掉，然后再刷新。

备注：之所以出现刷新时有违反唯一索引的错误是刷新的逻辑是增量插入，没有更新，因为开发人员没新增或更改一个API就回去刷新，这个操作比较频繁，用更新会导致性能不好，但增量插入的“增量”逻辑并非跟系统唯一索引完全一致，所以就会导致违反唯一索引的问题。 产研说后面会改进刷新的处理逻辑，会先删除跟增量部分重复的code, 然后再刷新，这样就不会出现违反唯一索引的错误，也不需要去数据库表做响应的删除操作了。

刷新后就没有错误，正常显示了：

问题2、事件管理服务未安装

平台/事件管理/事件源定义 ，访问时出错

分析：

事件管理服务未安装。

解决方案：

选配平台选配事件管理服务进行安装

1、选配平台下载服务的资源：

路径：开放平台/开发者/在线选配/服务端选配

父工程选择hzero父组件1.12.2

$ cd /d02/hzero/project

$ mkdir ps-event

#选配完成后,把事件服务.zip 和resource-package.zip 拷贝到 /d02/hzero/project/ps-event 目录下

$ cd /d02/hzero/project/ ps-event

$ unzip 事件服务.zip

$ unzip resource-package.zip -d ./resource-package

2、执行种子数据导入：

$ cd ./resource-package

#更改 application.yml 中mysql db的地址为mysql-hzero

$ cd /d02/hzero/project/ps-event/resource-package

$ bash database-init.sh

访问：http://localhost:8099/

执行1和3

• 构建服务的jar包

$ cd /d02/hzero/project/ps-event/src/main/resources

#更改application.yml

#mysql连接修改

db.hzero.com.cn->mysql-hzero

#redis连接修改

redis.hzero.com.cn->redis-hzero

#更改 bootstrap.yml

#配置中心修改

dev.hzero.com.cn->hzero-admin

#注册中心修改

dev.hzero.com.cn->hzero-register

#添加网络忽略配置

    inetutils:

      # 指定忽略的网卡

      ignored-interfaces:

       – lo

       – docker0

       – veth.*

#更改POM文件

1.12.2->1.12.2.RELEASE

1.12.0.RELEASE->1.12.2.RELEASE

#拷贝构建和启动脚本

$ cd /d02/hzero/project/ps-alert

$ cp build.sh run.sh run_nobuild.sh stop.sh /d02/hzero/project/ps-event/

# 执行构建并启动服务：

$ bash run.sh

启动成功，可以在注册中心看到：

• 构建前端

检查 /d02/hzero/front/front/package.json

看已经包含：

 “devDependencies”: {

 “hzero-front-hevt” : “~1.12.0”,

所以，该服务的前端已经构建过了。

• 测试：功能正常，服务地址改成实际部署环境的：

问题3、API测试数据不全

路径：平台工作台菜单/服务监控/API测试

发现有些已经安装的服务在这里没有显示，比如hzero-license

分析：检查看网络，都调用了哪些API，刷新，结果反而空了；

查hzero-admin后台服务日志：

报内存溢出了：

jakarta.servlet.ServletException: Handler dispatch failed: java.lang.OutOfMemoryError

想想也对，这个展示所有服务的API还是很消耗内存的，之前swagger服务也碰到内存溢出的问题，当时是给调到1G内存的。

解决方案：调整hzero-admin对的启动内存，-Xmx 从300M调整到800M

重启hzero-admin服务，再测试：

注册中心是14个，这里是11个，跟注册中心比还少了3个

继续调整 -Xmx 从800M调整到1200M，重启hzero-admin服务, 结果还是出来11个服务，没有变化，说明再加内存也没用。

缺失的是 hzero-gateway,hzero-license,hzero-swagger 三个服务的API展示

看API调用：hzero-admin 调的是swagger的 tree

执行：把hzero-swagger的-Xmx 从300M调整到800M，重启hzero-swagger服务，再测：还是一样，没有hzero-license和hzero-swagger的API展示，直接调用hzero-admin的这个API来获取hzero-license和hzero-swagger的API文档数据，也是空的。但trail环境上是可以展示hzero-license和hzero-swagger的API文档的。

查hzero-swagger的application.yml配置：

hzero:

  swagger:

skip-service: ${HZERO_SWAGGER_SKIP_SERVICE:register, gateway, oauth}

跳过不显示API的服务列表里面没有hzero-license 和hzero-swagger  所以正常应该显示出来，另外oauth在排除列表中，但实际上却在API测试列表里面显示出来了，这是为什么呢？

问豆包，豆包会告诉你这个列表的来源是hadm_swagger表：

我们去hadm_swagger表中看：

也确实没有hzero-license 和hzero-swagger:

那为什么hzero-license和hzero-swagger没有进入这张表呢？

我们跟豆包聊，关键是先检查 hzero-license服务有没有提供api文档，hzero-license的端口是8105，我们访问 http://dev.hzero.com.cn:8105/v2/api-docs

能正常返回api文档的json数据，加上我们在hzero-admin服务日志中没有看到采集swagger文档的报错信息，判断：问题出在hzero-admin未触发对这个服务的采集流程：

而且在API测试的地方，直接刷hzero-license的API文档返回是空的：

这个明天问下产研吧，什么原因？

产研说hzero_admin没有去调用swagger的api,就是直接请求网关的统一文档入口，从而拉取所有微服务的文档信息并生成服务列表。那个hadm_swagger表也不关键，是拉取之后临时存储的，没有配置作用。之所以hzero-license的api文档在我的环境没有显示出来是因为我用的hzero-license服务版本是2025年5月份之后的版本，新的版本中hzero-license服务的api文档调用显示在程序里面做了限制，禁止其他API直接访问，只允许直接在浏览器中显示。

好了，搞清楚了，这里没有安装配置方面的问题。问题关闭。

后续发现他们说的也不是那么回事。。。

在路径：平台菜单/平台治理/服务管理的地方，把hzero-license服务加上去之后，在swagger-ui.html 和API测试的地方就都能看到了，所以关键是这个服务要向治理平台hzero-admin注册。

问题4、授权信息查看报错

路径：平台工作台菜单/系统管理/授权信息

查看报错，报503错误

分析：

看hzero-license服务正常运行，后台日志没有报错。

估计是hzero_platform.iam_permission表中缺少响应的api 记录。

解决方案是：去平台/开发管理/开发管理/系统工具/刷新权限 去手动刷新下IAM权限

成功完成刷新动作。再测试：

发现还是报错：

去后台看hzero-gateway的服务日志，前端刷新一下，后端就有一堆信息下面这种信息：

把信息给元宝分析错误，结果元宝说没有错误，只是正常的debug信息，元宝建议把hzero-gateway的application.yml配置中关于日志的level部分从debug改成info，以免排查问题因为日志信息太多而收到干扰， 看了一下，确实hzero-gateway的日志太多了，才几个小时就已经有180M了。

按照元宝建议改成info级别日志，重启hzero-gateway 服务。

那么就继续看看路由的缓存问题：在浏览器直接访问：

http://gateway.hzero.com.cn:8080/hlcs/v1/license/info/license-code

返回：

{“failed”:true,”code”:”error.permission.routeNotFound”,”message”:”This request mismatch any routes, uri: %2Fhlcs%2Fv1%2Flicense%2Finfo%2Flicense-code”,”type”:”PERMISSION_SERVICE_ROUTE”,”detailsMessage”:”The route you visited does not exist or the related service is not installed”}

后端直接访问该接口：

$ curl http://172.18.14.48:8105/v1/license/info/license-code

{“timestamp”:”2025-12-11 17:19:04″,”status”:401,”error”:”Unauthorized”,”path”:”/v1/license/info/license-code”}root@desktop-jacksen:/d02/hzero/project/ps-gateway#

问题诊断结论​

✅ ​服务正常运行​：后端服务 hzero-license 已启动并在 8105 端口监听

✅ ​接口路径正确​：/v1/license/info/license-code 接口存在

估计还是iam_permission的问题，但权限已经刷新过了，没解决问题，看下权限表是否已经有了：

权限表中确实已经有了，所以不是权限问题了。

那是没有在网关的路由表里面吗？Hzero-license服务在注册中心可以看见，网关应该可以自动获取到这个服务的路由的吧？

命令行测试：

$ curl -X GET “http://gateway.hzero.com.cn:8080/hlcs/v1/license/info/license-code” \

  -H “Authorization: Bearer 303e3c8f2da80-4cfb-8bc7-53769798d0be”

${“failed”:true,”code”:”error.permission.routeNotFound”,”message”:”This request mismatch any routes, uri: %2Fhlcs%2Fv1%2Flicense%2Finfo%2Flicense-code”,”type”:”PERMISSION_SERVICE_ROUTE”,”detailsMessage”:”The route you visited does not exist or the related service is not installed”}

网关还是找不到路由。如果直接访问这个服务的API也会报未授权，即使带着token

curl    -X GET “http://172.18.14.48:8105/v1/license/info/license-code” \

  -H “Authorization: Bearer 303e3c8f2da80-4cfb-8bc7-53769798d0be”

{“timestamp”:”2025-12-11 18:35:37″,”status”:401,”error”:”Unauthorized”,”path”:”/v1/license/info/license-code”}

那可能是我hzero-gateway的application.yml中没有配置hzero-license的路由。在这个文件中搜索hzero-license，果然是缺失了。

解决方案：

增加hzero-license的路由：

      – id: hlcs

        uri: lb://hzero-license

        predicates:

        – Path=/hlcs/**

        filters:

        – StripPrefix=1

添加后重启， 问题解决。可以正常看到授权信息了：

后来跟产研聊，他们说如果没有在hzero-gateway的application.yml中配置路由，也可以在系统界面上添加，具体路径是：

平台菜单/平台治理/服务管理：

在平台菜单/平台治理/微服务实例，可以看到分别注册到注册中心的微服务实例额注册到hzero-admin的微服务实例：我们可以看到有个微服务没有向治理平台hzero-admin注册。如果向治理平台注册了的话，治理平台就会自动帮这些服务刷路由配置和iam_permission权限了。

治理平台也维护了一份服务路由表，hzero-gateway的GVM内存中的路由表是其自身applicatin.yml中配置的路由信息跟这张表的并集：

问题5、权限组显示错误

路径：平台菜单/系统管理/数据权限控制/权限组管理

分析：

看hzero-platform服务后台日志：

Unknown exception, Request: {URI=/v1/permission-groups-site},

org.springframework.web.servlet.resource.NoResourceFoundException: No static resource v1/permission-groups-site.

……

把整段日志给元宝，元宝分析：

�� 问题根源分析

核心问题在于，Spring Boot 将一个API接口请求误判为静态资源文件请求。这通常由以下一个或几个原因造成：

​控制器（Controller）映射缺失​：Spring MVC 没有找到一个能够处理 /v1/permission-groups-site 这个路径的控制器（例如 @RestController 中定义的 @RequestMapping）。

​静态资源路径配置干扰​：如果应用配置了静态资源映射（例如 spring.mvc.static-path-pattern），且其模式与该 API 路径意外匹配，请求可能会被错误的静态资源处理器截获。

​请求方式不匹配​：控制器上定义的 HTTP 方法（如 @GetMapping, @PostMapping）与您实际发起的请求方法（如 GET, POST）不匹配。

​版本差异与配置过时​：不同版本的 Spring Boot 在静态资源处理上可能存在差异，旧版本的配置方式在新版本中可能已不适用或失效

#

路径：平台菜单/服务监控/API测试，查找hzero-platform的API,确实没有找到permission-groups-site的api.

但是在iam_permission表是有的：

在swagger-ui.html上没找到 hzero-platform的permission-group API

跟产研沟通了下，说这些API在 platform-dpc-saas中，这个组件现在已经默认不依赖了，该组件是数智事业部开发的，他们部门一直在用，而且他们部门认为这个功能需要放在平台层，之前曾经加进来过，所以菜单的种子数据中就有了，但现在产研这边已经不用了，相关菜单也可以去掉。如果要用就是需要在hzero-platform的POM中加下依赖：

<dependency>

            <groupId>org.hzero.plugin</groupId>

            <artifactId>platform-dpc-saas</artifactId>

        </dependency>

加完后，重新build并启动，再测，就正常不报错了：

问题解决。

问题6、jar包管理界面打开报错：

路径：平台菜单/开发管理/个性化管理

点击 jar包管理，报错：The route you visited does not exist or the related service is not installed

分析：这个错误很明显，就是

解决方案：

解决方案：

选配平台选配事件管理服务进行安装

1、选配平台下载服务的资源：

路径：开放平台/开发者/在线选配/服务端选配

父工程选择hzero父组件1.12.2

选配hzero-jar组件

$ cd /d02/hzero/project

$ mkdir ps-jar

#选配完成后,把动态Jar管理.zip 和resource-package.zip 拷贝到 /d02/hzero/project/ps-event 目录下

$ cd /d02/hzero/project/ps-jar-app

$ unzip 动态Jar管理.zip

$ unzip resource-package.zip -d ./resource-package

2、执行种子数据导入：

$ cd ./resource-package

#更改 application.yml 中mysql db的地址为mysql-hzero

$ cd /d02/hzero/project/ps-jar/resource-package

$ chmod +x database-init.sh

$ bash database-init.sh

访问：http://localhost:8099/

执行1和3

• 构建服务的jar包

$ cd /d02/hzero/project/ps-jar/src/main/resources

#更改application.yml

#mysql连接修改

db.hzero.com.cn->mysql-hzero

#redis连接修改

redis.hzero.com.cn->redis-hzero

#redis上面加一层data: 在spring:下一层

#hzero-jar-app->hzero-jar

#更改 bootstrap.yml

#配置中心修改

dev.hzero.com.cn:8010->hzero-admin:8060/hadm/config

#注册中心修改

dev.hzero.com.cn->hzero-register

#添加网络忽略配置

    inetutils:

      # 指定忽略的网卡

      ignored-interfaces:

       – lo

       – docker0

       – veth.*

#更改POM文件

1.12.2->1.12.2.RELEASE

1.12.0.RELEASE->1.12.2.RELEASE

mysql->com.mysql

#拷贝构建和启动脚本

$ cd /d02/hzero/project/ps-alert

$ cp build.sh run.sh run_nobuild.sh stop.sh /d02/hzero/project/ps-jar/

# 执行构建并启动服务：

$ cd /d02/hzero/project/ps-jar

$ bash run.sh

启动报错：

Spring 在寻找：org/hzero/jar/api/  实际路径中不存在：api 子目录

解决方案：把日志发给元宝，按元宝建议多次执行分析-建议-执行再分析的循环未能解决问题，解决了api ,又说缺app等另外3个目录，解决了目录又报其他一些列错误， 后来跟产研沟通，产研说他们在IDE环境启动没问题，要再测试下命令行启动问题的差异，找了下原因，发现是POM文件中多了build部分，而且build部分的版本不对。

解决方案就是把build部分删除掉，就可以正常启动了，然后在注册中心可以看到hzero-jar服务。

• 构建前端

检查 /d02/hzero/front/front/package.json

看尚未包含：

  “devDependencies” : {

    “hzero-front-hjar” : “~1.2.0”,

所以，要加一下。

$ cd /d02/hzero/front/front/

$ cp package.json package.json.bak20251212

更改package.json ,增加上述依赖

$ yarn

$ yarn run build:ms hzero-front-hjar

$ Done in 8.65s

#部署

$ bash  apply_update_to_runtime_env.sh

• 测试：功能正常了：

问题7、接口平台API注册报404错误

路径：平台菜单/接口平台/API配置/API注册

这个菜单打开会报404错误

分析：跟产研沟通，在1.8版本中暂不提供这个功能，这个是在1.9以后的大版本中规划的API维度的一个界面。

解决方案：暂时先禁用掉该菜单。

在 平台菜单/系统管理/菜单管理/菜单配置：

问题8、接口平台API权限汇总查看报404错误

路径：平台菜单/接口平台/API权限/API权限汇总查看

这个菜单打开会报404错误

分析：跟产研沟通，在1.8版本中暂不提供这个功能，这个是在1.9以后的大版本中规划的一个功能。

解决方案：暂时先禁用掉该菜单。在 平台菜单/系统管理/菜单管理/菜单配置：

问题9： 集成平台/服务编排/应用连接器 打开页面一闪而过，白屏

路径：平台菜单/服务编排/应用连接器/应用连接器

分析：

检查 浏览器网络没有报API错误，hzero-orchestration服务后台也没有报错。

只有前端报错，通常这种情况就是看下有没有新的前端版本可以更新，先看下开放平台文档中关于编排的前端模块是啥？

文档路径： 开放平台/社区与合作伙伴/文档中心/技术产品/集星獭JeeStar/1.8.1RELEASE/产品安装部署手册/前后端服务清单

说明编排的的前端模块是：jipaas-front-jorc 1.8.0 服务编排模块

看下当前的package.json中的版本：发现没有这个前端模块

解决方案：

在package.json中增加jipaas-front-jorc 1.8.0 服务编排模块和jipaas-front-jfnt 1.8.0 前置机服务模块

$ cd /d02/hzero/front/front

$ cp package.json package.json.bak20251216

#搜索制品库 https://nexus.saas.hand-china.com，搜索hzero-ui库，切换到HTML View，ctro+F 搜索jipaas-front-jorc， 看到最新版本是2025-10-15的1.7.3-beta.1 没有文档写的1.8.0

先尝试按文档1.8.0

Couldn’t find any versions for “jipaas-front-jitf” that matches “~1.8.0”
? Please choose a version of “jipaas-front-jitf” from this list: (Use arrow keys)
❯ 1.8.0-beta.2

yarn之后还确实有，除了jipaas-front-jitf有1.8.0-beta.2需要选择下，其他两个都没让选，看了  jipaas-front-jorc 和 jipaas-front-jfnt 目录下的json文件还都是1.8.0的

$ yarn build:ms jipaas-front-jitf,jipaas-front-jorc,jipaas-front-jfnt

$ Done in 246.70s.

#然后运行前端部署脚本：

$bash  apply_update_to_runtime_env.sh

再测试：已经正常显示了。

问题解决。