Cloudbeaver项目部署中GQL错误的排查与解决

问题背景

在Cloudbeaver项目部署过程中，用户通过oAuth2代理认证后，当因空闲断开连接后再次访问时，前端界面会出现"GQL Error: Not Found"错误。该问题只有在清除浏览器缓存后才能暂时解决，但下次断开连接后又会重现。

错误现象分析

错误发生时，前端控制台显示以下堆栈信息：

GQL Error: Not Found
    at CustomGraphQLClient.overrideRequest
    at async NetworkStateService.sessionExpiredInterceptor
    at async SessionExpireService.sessionExpiredInterceptor
    at async ServerConfigResource.loader
    at async ServerConfigResource.loadingTask
    at async ServerConfigResource.taskWrapper
    at async Task.task

值得注意的是，容器端除了一条新的web会话调试日志外，没有其他异常日志记录。

部署环境特点

该部署采用了以下特殊配置：

1. 使用自定义Helm图表部署Cloudbeaver
2. 通过Traefik Ingress提供服务
3. 配置了三个中间件：
   • URL路径重写中间件（将/cloudbeaver/从URL中去除）
   • 前端根URI重写中间件（将_ROOT_URI_从/改为/cloudbeaver/）
   • oAuth2代理认证中间件（作为额外的认证层）

问题根源

经过深入分析，发现问题主要由以下两个因素共同导致：

1. oAuth2代理认证问题：当oAuth2代理的cookie过期后，前端无法再访问/api/端点，导致403 Forbidden错误，进而引发GraphQL错误。

2. 根URI配置问题：由于前端根URI被重写为/cloudbeaver/，导致无法通过硬刷新来恢复会话状态。

解决方案

1. 配置rootURI：在cloudbeaver.conf配置文件中明确设置rootURI参数，确保前后端路径一致。

2. 调整oAuth2代理配置：移除对/cloudbeaver/api/端点的oAuth2认证要求，允许前端直接访问API接口。

经验总结

在部署Cloudbeaver这类前后端分离的应用时，需要特别注意：

1. 前后端路径一致性：确保前端访问路径与后端API路径配置一致。

2. 认证层设计：额外的认证层（如oAuth2代理）不应干扰应用自身的API通信。

3. 会话管理：理解应用的会话管理机制，避免因多层认证导致的会话冲突。

通过以上调整，成功解决了因oAuth2代理认证和路径配置导致的GQL错误问题，确保了Cloudbeaver在复杂部署环境下的稳定运行。