Streamlit应用在Nginx反向代理下的WebSocket连接问题解析

问题背景

在使用Nginx作为Streamlit应用的反向代理时，开发者经常会遇到URL重写与WebSocket连接的兼容性问题。当尝试通过Nginx将形如/assist的URL重写为/?p=assist时，Streamlit应用的WebSocket连接会出现异常，导致页面无法正常加载。

技术原理分析

Streamlit应用在运行时依赖于WebSocket连接来实现实时数据交互和页面更新。这些WebSocket连接通常会访问以/_stcore/开头的特殊路径。当Nginx配置了URL重写规则时，如果不加区分地对所有请求进行重写，就会意外地修改WebSocket连接的路径，导致连接失败。

典型错误配置

一个常见的错误Nginx配置如下：

upstream streamlit {
    server 127.0.0.1:8502;
}

server {
    listen 80;
    
    # 这个重写规则会影响所有请求
    rewrite ^/([^/?]+)$ /?p=$1 break;
    
    location / {
        proxy_pass http://streamlit;
        # 其他代理设置...
    }
}

这种配置会导致WebSocket尝试连接/assist/_stcore/...这样的路径，而实际上应该连接/_stcore/...。

解决方案

方法一：排除WebSocket路径的重写

通过修改重写规则，使其不处理包含_stcore的请求：

if ($request_uri !~ "_stcore") {
    rewrite ^/([^/?]+)$ /?p=$1 break;
}

方法二：使用重定向替代重写

更安全的做法是使用HTTP重定向而非内部重写：

location "/SomeOldPage" {
    rewrite ^/[^?/]+ /newpage redirect;
}

方法三：明确指定WebSocket路径

为WebSocket连接单独配置location块：

location /_stcore/stream {
    proxy_pass http://streamlit/_stcore/stream;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

最佳实践建议

1. 明确区分普通请求和WebSocket请求：为WebSocket连接设置专门的location块
2. 优先使用重定向而非重写：重定向更安全，不会影响WebSocket连接
3. 设置Streamlit的baseUrlPath：在Streamlit配置中指定子目录路径(如/ui)可以避免很多路径问题
4. 保持WebSocket相关配置完整：确保包含必要的HTTP头设置(Upgrade, Connection等)

总结

在Nginx中代理Streamlit应用时，正确处理URL重写与WebSocket连接的关系至关重要。通过合理配置Nginx的重写规则，为WebSocket连接设置专门的处理路径，并考虑使用重定向替代重写，可以有效解决这类问题，确保Streamlit应用在反向代理环境下正常工作。