在Nginx+Docker部署Streamlit时遇加载异常问题求助

你的Nginx配置存在几个关键问题，导致Streamlit无法建立正确的实时连接，从而卡在“please wait”状态：

1. 健康检查端点配置错误 #

原配置中location _stcore/health缺少开头的斜杠，且代理目标错误。Streamlit 1.20+的健康检查端点是/_stcore/health，不是/healthz，正确配置应为：

location ^~ /_stcore/health {
    proxy_pass http://webapp/_stcore/health;
}

2. 缺少WebSocket端点代理 #

Streamlit 1.20+使用/_stcore/websocket进行实时通信，你的配置完全遗漏了这个端点，这是页面一直加载的核心原因。需要添加：

location ^~ /_stcore/websocket {
    proxy_pass http://webapp/_stcore/websocket;
    proxy_http_version 1.1;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

3. 路径代理的斜杠一致性问题 #

所有proxy_pass的目标路径末尾建议统一添加斜杠，避免Nginx自动拼接路径时出错，比如：

location ^~ /static {
    proxy_pass http://webapp/static/;
}
location ^~ /vendor {
    proxy_pass http://webapp/vendor/;
}

4. Streamlit配置补充 #

除了你已经设置的项，还需要在.streamlit/config.toml中添加反向代理相关配置，让Streamlit知道自己运行在代理后面：

[server]
enableCORS = false
enableXsrfProtection = false
headless = true
serverAddress = "0.0.0.0"
rootPath = "/"  # 如果站点部署在子路径，这里填对应路径，比如"/app"

或者启动Streamlit时直接传递参数：

streamlit run your_app.py --server.enableCORS=false --server.enableXsrfProtection=false --server.headless=true --server.serverAddress=0.0.0.0

修正后的完整Nginx配置 #

upstream webapp{
    server webapp:8501;
}

server {
    listen 80;

    location / {
        proxy_pass http://webapp/;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location ^~ /static {
        proxy_pass http://webapp/static/;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

    location ^~ /_stcore/health {
        proxy_pass http://webapp/_stcore/health;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

    location ^~ /vendor {
        proxy_pass http://webapp/vendor/;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

    location ^~ /_stcore/stream {
        proxy_pass http://webapp/_stcore/stream;
        proxy_http_version 1.1; 
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }

    location ^~ /_stcore/websocket {
        proxy_pass http://webapp/_stcore/websocket;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

额外检查项 #

• 确保Nginx容器能正常解析webapp上游服务名（比如在同一个Docker网络下）
• 查看Streamlit容器日志，确认是否有连接被拒绝或路径错误的提示
• 检查浏览器开发者工具的网络面板，看是否有404或502请求，重点关注/_stcore开头的请求

内容的提问来源于stack exchange，提问作者Garou