如何配置Nginx适配ASP.NET Core SignalR？本地正常部署异常

SignalR 支持 WebSocket、Server-Sent Events、长轮询三种传输协议，本地直连可正常运行但经Nginx代理后失效，核心原因是Nginx默认配置未适配长连接、WebSocket协议升级、实时消息无缓冲转发的要求，按以下步骤调整即可修复：

前置配置修正 #

先排查两处配置错误，避免代理配置正确后依然连接失败：

• 生产环境CORS策略不要保留localhost源，将前端实际部署的域名填入WithOrigins配置中，SetIsOriginAllowed(_ => true)仅建议调试阶段使用，生产环境放开所有源配合AllowCredentials存在跨域安全风险
• 前端SignalR连接地址不要写https://localhost:5001/notification，替换为Nginx对外暴露的服务访问地址，例如https://your-production-domain.com/notification

适配SignalR的Nginx配置 #

配置核心要求：支持WebSocket协议升级、关闭响应缓存/缓冲、调整长连接超时时间、正确透传转发请求头，参考配置如下：

# 按你实际的服务端口、域名调整server块配置
server {
    listen 443 ssl http2;
    server_name your-production-domain.com;
    # 原有SSL证书配置保持不变即可
    # ssl_certificate /path/to/your/cert.pem;
    # ssl_certificate_key /path/to/your/private.key;

    # 定义后端服务地址池，端口替换为你实际的后端服务监听端口
    upstream backend_service {
        server 127.0.0.1:5001;
        keepalive 64; # 维持和后端的长连接池，减少重复握手开销
    }

    # 单独给SignalR Hub路径配置转发规则
    location /notification {
        proxy_pass http://backend_service;
        # 透传基础请求头
        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;

        # WebSocket协议升级必备配置
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 关闭缓冲和缓存，避免SSE、长轮询消息被Nginx缓存无法实时推送到客户端
        proxy_buffering off;
        proxy_cache off;

        # 调整长连接超时时间，需大于SignalR客户端默认的KeepAlive间隔（默认30s），避免Nginx主动断开空闲连接
        proxy_connect_timeout 10s;
        proxy_send_timeout 120s;
        proxy_read_timeout 120s;
    }

    # 其他接口、静态资源的转发规则保持原有配置即可
    location / {
        proxy_pass http://backend_service;
        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;
    }
}

配置生效验证 #

1. 执行nginx -t检查配置文件语法，确认无报错后执行nginx -s reload重载Nginx配置
2. 清空浏览器缓存后重新访问前端页面，查看控制台SignalR日志，输出Connected即为连接正常
3. 如果依然连接失败，优先排查：
   • 后端服务是否正常监听127.0.0.1:5001端口，本地直连后端端口是否可正常访问Hub
   • 前端访问域名是否已经加入后端CORS允许源列表
   • 如果外层接入了CDN、WAF，需要确认对应服务开启了WebSocket协议支持，不要拦截Upgrade请求头

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