Next-Terminal 反向代理 HTTPS 配置问题分析与解决方案

问题背景

在使用 Next-Terminal 堡垒机系统时，许多用户希望通过反向代理方式实现 HTTPS 访问，但在配置过程中遇到了连接 SSH 资产失败的问题。具体表现为：通过 HTTP 直接映射端口可以正常连接 SSH 资产，但通过 Nginx 等反向代理配置 HTTPS 后，虽然能访问 Web 界面，却无法成功连接 SSH 资产，系统会返回"websocket error undefined"和"connection is closed"的错误提示。

问题分析

这个问题的根源在于 WebSocket 协议在反向代理环境下的特殊处理需求。Next-Terminal 使用 WebSocket 来实现终端会话的实时通信，而 WebSocket 连接在 HTTPS 环境下需要额外的配置才能正常工作。

当直接使用 HTTP 协议时，WebSocket 连接可以无障碍建立。但一旦通过反向代理配置 HTTPS，如果没有正确设置代理头部信息，WebSocket 握手过程就会失败，导致终端会话无法建立。

解决方案

要解决这个问题，需要在反向代理配置中添加对 WebSocket 协议的特殊处理。以下是经过验证的 Nginx 配置方案：

server {
    listen      443 ssl;
    server_name  your.domain.com;

    ssl_certificate      /path/to/cert.pem;
    ssl_certificate_key  /path/to/cert.key;

    ssl_session_cache    shared:SSL:1m;
    ssl_session_timeout  5m;

    ssl_ciphers  HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers  on;

    location / {
        proxy_pass http://localhost:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

关键配置说明

1. proxy_set_header Upgrade $http_upgrade
   这个指令告诉 Nginx 将客户端的 Upgrade 头部传递给后端服务器，这对于 WebSocket 握手至关重要。

2. proxy_set_header Connection "upgrade"
   这个指令确保连接类型被正确设置为"upgrade"，允许协议从 HTTP 切换到 WebSocket。

3. X-Forwarded- 头部*
   这些头部确保后端服务器能够获取客户端的真实 IP 和原始协议信息，对于日志记录和安全检查很重要。

常见问题排查

如果按照上述配置后仍然无法连接 SSH 资产，可以检查以下几点：

1. 确认 Nginx 配置已重新加载（执行 nginx -s reload）
2. 检查防火墙是否放行了 WebSocket 使用的端口
3. 查看 Next-Terminal 和 Nginx 的日志文件，寻找错误信息
4. 确保 SSL 证书有效且未被浏览器拦截

最佳实践建议

1. 在生产环境中，建议使用有效的 CA 签发的 SSL 证书，而非自签名证书
2. 可以考虑添加 HTTP 到 HTTPS 的自动跳转，强制使用安全连接
3. 对于高安全性要求的场景，可以配置额外的 WebSocket 安全策略
4. 定期检查 SSL 证书的有效期，避免因证书过期导致服务中断

通过以上配置和注意事项，Next-Terminal 可以在 HTTPS 反向代理环境下正常工作，既保证了通信安全，又不影响终端连接功能。