Jumpserver WebSocket连接异常问题分析与解决方案

【免费下载链接】JumpServer 广受欢迎的开源堡垒机 项目地址: https://gitcode.com/feizhiyun/jumpserver

问题背景

Jumpserver作为一款开源的堡垒机系统，在4.10.2版本升级后，部分用户反馈出现了WebSocket连接异常中断的问题。该问题表现为SSH会话在几分钟到十几分钟不等的时间内会意外断开，并显示"Connection websocket has been closed"错误信息。

问题现象

根据用户反馈，该问题具有以下典型特征：

1. 会话中断：无论SSH会话中是否有操作活动（包括运行脚本、实时查看日志或设置长时间超时），连接都会在短时间内中断
2. 错误日志：koko组件日志中频繁出现WebSocket相关错误，如：
   • websocket: close 1006 (abnormal closure): unexpected EOF
   • websocket: close 1005 (no status)
   • websocket: close 1001 (going away)
3. 环境特征：问题在Kubernetes和Docker Compose部署环境中均有出现

技术分析

WebSocket连接机制

WebSocket是Jumpserver实现实时终端交互的基础协议。与传统的HTTP请求不同，WebSocket建立的是持久化连接，允许服务器主动向客户端推送数据。在Jumpserver架构中：

1. 前端通过WebSocket与koko组件建立连接
2. koko组件作为中间层，负责转发终端数据
3. 连接稳定性直接影响用户体验

问题根源

从技术角度看，该问题可能涉及多个层面的因素：

1. 超时设置不匹配：虽然用户已调整Nginx的proxy_read_timeout和proxy_send_timeout至600秒，但可能系统内部其他组件的超时设置未同步调整
2. 连接保持机制：WebSocket连接需要定期的心跳包维持，可能心跳机制存在缺陷
3. 网络中间件：在Kubernetes环境中，Ingress控制器可能对WebSocket连接有额外的超时限制
4. 会话管理：SESSION_EXPIRE_AT_BROWSER_CLOSE=true配置可能导致浏览器标签关闭时强制终止会话

解决方案

官方修复

Jumpserver开发团队已在4.10.3版本中修复了该问题。建议用户升级到最新版本，这是最直接有效的解决方案。

临时缓解措施

如果无法立即升级，可尝试以下方法缓解问题：

1. 全面检查超时设置：

   • 确保所有相关组件（包括反向代理、Ingress控制器、Jumpserver配置）的超时设置一致
   • 特别检查Kubernetes Ingress annotations中的超时相关配置

2. 调整Jumpserver配置：

   # 增加WebSocket相关超时设置
   SESSION_COOKIE_AGE: 86400  # 设置较长的会话有效期
   WEBSOCKET_TIMEOUT: 3600    # 设置WebSocket超时为1小时
   

3. 网络层优化：

   • 在Nginx配置中显式声明WebSocket支持：

     proxy_http_version 1.1;
     proxy_set_header Upgrade $http_upgrade;
     proxy_set_header Connection "upgrade";
     

验证方法

升级或调整配置后，可通过以下方式验证问题是否解决：

1. 建立长时间SSH会话（超过原先中断的时间）
2. 执行持续输出命令（如tail -f）
3. 观察koko组件日志中是否仍有WebSocket异常记录

最佳实践建议

1. 升级策略：生产环境升级前，建议在测试环境充分验证新版本稳定性
2. 监控配置：建立WebSocket连接健康度监控，及时发现类似问题
3. 文档查阅：仔细阅读版本发布说明，了解各版本间的配置变更要求
4. 环境一致性：确保所有环境组件（特别是网络中间件）的配置同步更新

总结

WebSocket连接稳定性对Jumpserver这类实时交互系统至关重要。通过版本升级和合理的配置调整，可以有效解决连接异常中断问题。建议用户遵循官方推荐配置，并在复杂环境中特别注意各层组件的协同工作。

【免费下载链接】JumpServer 广受欢迎的开源堡垒机 项目地址: https://gitcode.com/feizhiyun/jumpserver