TabbyML 项目在 Nginx 反向代理下的 WebSocket 配置指南

在部署 TabbyML 项目时，许多用户选择使用 Nginx 作为反向代理来提高安全性和可用性。然而，当通过 Nginx 反向代理访问 TabbyML 的聊天功能时，可能会遇到无法正常工作的问题。本文将深入分析这一问题的原因，并提供完整的解决方案。

问题背景

TabbyML 是一个开源的机器学习项目，其聊天功能依赖于 WebSocket 协议来实现实时通信。当直接访问 TabbyML 服务时，WebSocket 连接可以正常建立，但通过 Nginx 反向代理后，连接往往会失败。

根本原因分析

WebSocket 协议与传统的 HTTP 协议有所不同，它需要在初始 HTTP 握手后升级为持久连接。Nginx 默认配置并不自动处理这种协议升级，导致 WebSocket 连接无法正确建立。

解决方案

要使 TabbyML 的聊天功能在 Nginx 反向代理下正常工作，需要在 Nginx 配置中添加特定的 WebSocket 支持指令。以下是完整的配置示例：

server {
    listen 80;
    server_name your.domain.com;

    location / {
        proxy_pass http://localhost:8080;  # 替换为实际的TabbyML服务地址
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # WebSocket 支持配置
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

关键配置说明

1. proxy_http_version 1.1：强制使用 HTTP/1.1 协议，这是 WebSocket 协议升级的必要条件。

2. Upgrade 和 Connection 头：这两个头部信息是 WebSocket 握手过程中的关键部分：

   • Upgrade 头指示协议升级
   • Connection: upgrade 确认连接升级

3. 超时设置（可选）：对于长时间运行的 WebSocket 连接，可以适当增加超时设置：

   proxy_read_timeout 86400s;
   proxy_send_timeout 86400s;
   

验证配置

配置完成后，可以通过以下步骤验证是否正常工作：

1. 重新加载 Nginx 配置：sudo nginx -s reload
2. 在浏览器中访问 TabbyML 的聊天界面
3. 使用浏览器开发者工具检查 WebSocket 连接状态

常见问题排查

如果配置后仍然无法正常工作，可以检查以下方面：

1. 确认后端 TabbyML 服务本身正常工作
2. 检查 Nginx 错误日志：/var/log/nginx/error.log
3. 确保防火墙允许 WebSocket 端口（通常为 80 或 443）
4. 验证 SSL 配置（如果使用 HTTPS）

最佳实践建议

1. 对于生产环境，建议启用 HTTPS 以加密 WebSocket 通信
2. 考虑添加适当的访问控制和速率限制
3. 监控 WebSocket 连接状态和资源使用情况

通过以上配置，TabbyML 的聊天功能应该能够在 Nginx 反向代理环境下正常工作。这种配置不仅适用于 TabbyML，也适用于其他基于 WebSocket 的应用程序。