★ FEATURED ARTICLE 我前后差不多把十几种部署组合都折腾过一遍了现在只要你提“Blazor上Linux”我条件反射就是三件套dotnet publish发布、systemd托管进程、Nginx做反向代理。但很多朋友恰恰就卡在第三步尤其是WebSocket这个代理链路上本地跑得好好的一放到服务器上页面能打开SignalR却一直连不上四五个浏览器标签页里全是红色的Failed to connect。这篇文章我就把Blazor应用发布到Linux、用Nginx作为WebSocket代理这条链路从头到尾梳理一遍。不光是给配置还会把Nginx为什么要这么配、Upgrade头到底干了什么、后端代码里需要动哪个开关这些问题讲透。适合两种人看一个是第一次把Blazor往服务器上部署的新手另一个是部署过但遇到WebSocket莫名其妙断连、想搞清楚底层原理的开发者。1. 为什么Blazor应用部署Linux必须考虑Nginx先别急着碰配置文件我们得先把场景理清楚。1.1 两种Blazor运行形态部署策略完全不同Blazor其实包含两种形态很多刚接触的朋友容易混在一起。一种是Blazor Server。在这个模型下浏览器里跑的UI逻辑、事件处理其实都在服务器上浏览器通过SignalR连接跟服务器保持实时通信界面上用户点了按钮这个“点击”要通过WebSocket传到服务器服务器把渲染后的UI补丁再推回浏览器。这个过程依赖长连接而且是持续性的。另一种是Blazor WebAssembly也叫Blazor WASM。这种形态是把整个.NET运行时和程序集下载到浏览器里C#代码在浏览器里跑UI交互基本不需要服务器参与。这种部署跟普通静态站点差不多Nginx只需要托管静态文件。但标题里说的“使用Nginx作为WebSocket代理”显然是针对Blazor Server或者混合方案的场景。因为只有Blazor Server才需要Nginx转发WebSocket而WASM模式压根用不上SignalR。搞清楚自己项目属于哪一种后面的所有决策才有意义。如果你是Blazor Server项目直接对外暴露Kestrel是不现实的必须有一个正向代理层。1.2 为什么非要用Nginx来接Kestrel我见过有人直接把Kestrel绑定0.0.0.0:5000对外开放说实话能跑但不是待遇问题而是安全和稳定性问题。第一Kestrel的性能和抗压上限靠的是本身但它对外暴露后面对恶意请求探测、不规范的UA扫描、慢速连接攻击等等没有一层防护进程很容易被打满。Nginx处理并发连接的方式是事件驱动在静态资源和连接处理上极其强悍天然是一道闸。第二你的应用如果还有静态资源CSS、JS、图片Kestrel也会去处理但Kestrel处理静态文件的能力比起Nginx带sendfile的静态文件响应要弱在高并发下CPU开销相差很大。第三证书终结的问题。HTTPS证书配置在Nginx这一层内部的Kestrel保持HTTP明文就足够了。这个叫TLS终结TLS Termination既省去了在.NET程序里操心证书链续期的麻烦也方便未来加负载均衡和集群。第四也是本文核心——WebSocket支持。Nginx原生支持HTTP Upgrade机制转发WebSocket只需要几行配置。加上它对连接空闲超时的处理非常灵活这是做长连接代理的底线能力。所以标准链路就是浏览器连Nginx的80/443端口Nginx按规则把普通HTTP请求转发到Kestrel把升级成WebSocket的请求也转发到KestrelKestrel处理Blazor应用和SignalR通信。链路一旦建立Nginx就扮演纯粹的“管道”双向流量都透传。1.3 完整的请求链路长什么样我们一步步拆解一次典型的Blazor Server页面交互用户在浏览器输入网址向Nginx发起HTTPS请求。Nginx根据location规则把这个普通HTTP GET请求转发给http://127.0.0.1:5000。Kestrel收到请求返回Blazor Server应用的HTML页面和SignalR连接相关的初始化脚本。浏览器解析页面脚本执行后向服务端发起一个带有Upgrade: websocket头的请求。Nginx识别到这个请求头知道这是一个WebSocket握手请求。Nginx把这个带Upgrade头的请求传给KestrelKestrel找到SignalR对应的Endpoint完成握手并升级连接。浏览器和服务器之间建立了真正的WebSocket长连接后续的UI交互都走这条隧道。整个过程里Nginx最关键的角色转换就是从“请求分发员”变成“透明隧道”。它必须正确处理Upgrade头否则在步骤5就断了。2. Nginx代理WebSocket的核心配置拆解很多教程喜欢直接甩一段配置然后说“照抄就行”。我建议各位还是花两分钟把这段配置的每一行吃透否则出了问题根本不知道去哪排查。2.1 HTTP Upgrade机制到底在做什么普通HTTP请求是“短命”的请求一次响应一次连接关闭。WebSocket不一样它希望这条TCP连接能一直开着用来双向推送数据。但WebSocket的握手还是基于HTTP协议来完成的这就靠Upgrade头来“升舱”。客户端会在握手请求里带上两类关键HeaderUpgrade: websocket Connection: UpgradeUpgrade声明客户端希望切换协议到websocketConnection告诉代理服务器这个请求不是普通的请求你要把Upgrade这个Header逐跳传递下去不能吞掉。Nginx默认是不转WebSocket的。如果你配了一个普通的反向代理没有显式声明这两个HeaderNginx会在代理转发时直接丢掉它们然后Kestrel看到的是一个普通HTTP GET请求自然就不会升级成WebSocketSignalR只能用Server-Sent Events降级体验上有延迟且不稳定。所以必须显式声明location / { proxy_pass http://127.0.0.1:5000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }$http_upgrade是Nginx内置变量它取的是客户端请求里Upgrade头的值。这么写就是“客户端传什么Upgrade头我就原样传给后端”。Connection upgrade则是让Nginx和后端交互时也使用Connection: upgrade整个升级链路在后端视角里是连续的。2.2 除了Upgrade这几行配置同样关键再来看看完整的server块server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:5000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }一个一个过proxy_http_version 1.1这行是硬性的。HTTP/1.0协议不支持Upgrade机制如果你不给Nginx指定HTTP版本默认用的就是1.0WebSocket握手必失败。Nginx官方文档中明确写了“HTTP/1.1 is required for WebSocket proxying”没有商量余地。proxy_set_header Host $host这行是把客户端请求的Host头原样传给后端。如果不设置后端收到的Host可能是127.0.0.1:5000这会导致Kestrel生成的重定向地址和Cookie域名错乱页面跳转全乱套。proxy_set_header X-Forwarded-For和X-Forwarded-Proto是给后端传递真实的客户端来源和协议。这样你用app.UseForwardedHeaders()的时候应用才能正确生成Scheme相关的链接。比如页面里如果需要拼接https://开头的回调地址靠的就是这个Header。proxy_read_timeout 3600s和proxy_send_timeout 3600s这两个超时参数容易被忽略。WebSocket连接建立后会长时间闲置比如你打开页面不操作浏览器和服务器之间可能几分钟都没有数据流动。Nginx默认的proxy_read_timeout是60秒这就意味着一个连接超过60秒没有任何响应Nginx就主动断开它。对Blazor Server这种靠心跳维持的长连接应用来说这个默认值就是坑。你需要把超时时间拉长到至少1小时配合SignalR自带的心跳机制才能保证连接稳定不闪断。上文我用$connection_upgrade而不是写死的upgrade。这样写更灵活可以配合一个map定义处理非WebSocket请求的情况map $http_upgrade $connection_upgrade { default upgrade; close; } server { # ... }这段map的意思是客户端带了Upgrade头就转发upgrade没带Upgrade头就转发close。好处是同一个location既能处理普通HTTP请求又能处理WebSocket升级请求互不干扰。这是我实操最喜欢用的配置组合推荐你也这么写。2.3 一个更完整的HTTPS方案如果是生产环境我建议把证书直接配在Nginx上server { listen 443 ssl; http2 on; server_name your-domain.com; ssl_certificate /etc/nginx/certs/fullchain.pem; ssl_certificate_key /etc/nginx/certs/privkey.pem; location / { proxy_pass http://127.0.0.1:5000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 3600s; proxy_send_timeout 3600s; proxy_buffering off; } } server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; }这里面我特意加了proxy_buffering off。为什么要关缓冲因为WebSocket是双向实时通信Nginx默认会对后端响应做缓冲这在普通HTTP场景下有利于性能但对WebSocket来说它希望数据一到就能立即转发给客户端而不是积攒到一定大小才吐出去。关闭缓冲可以减少实时消息的延迟。实测下来弥补这一行带来的体感差异是有的尤其是频繁刷新UI组件的Blazor页面。3. 发布Blazor应用到Linux的完整流程配置讲清楚了现在走一遍完整的部署流程。我尽量把每一步的关键点都备注清楚按这个流程走基本不会翻车。3.1 发布Blazor应用先说发布。在开发机上执行dotnet publish -c Release -r linux-x64 --self-contained false -o /path/to/publish这里有几个参数说一下-r linux-x64指定运行时标识符。如果你是ARM64的服务器改成linux-arm64。不确定服务器架构可以用uname -m查一下。--self-contained false生成的是依赖框架的部署包服务器上需要安装.NET运行时。如果服务器上不方便装运行时或者你想彻底避免运行时版本冲突可以改用--self-contained true这样发布出来是自带运行时的大包目录体积会多出100MB左右但真的“一把梭”怎么拷过去都能跑。发布完成后输出目录里能看到BlazorApp.dll主程序集appsettings.jsonwwwroot静态文件目录.deps.json、.runtimeconfig.json一大堆依赖的DLL把这个目录整个拷贝到服务器的/var/www/blazorapp即可。3.2 安装.NET运行时如果发布用的是framework-dependent模式服务器上需要装对应版本的运行时。以.NET 8为例sudo apt update sudo apt install -y aspnetcore-runtime-8.0这里装的是aspnetcore-runtime而不是dotnet-runtime前者包含了ASP.NET Core相关的库Blazor Server离不开它。装好后可以用dotnet --info验证。3.3 创建systemd服务直接用dotnet /var/www/blazorapp/BlazorApp.dll这种裸命令启动是不靠谱的进程一退出就没了。生产环境必须用systemd托管让Linux系统负责守护这个进程。新建服务文件/etc/systemd/system/blazorapp.service[Unit] DescriptionBlazor Server APP Afternetwork.target [Service] WorkingDirectory/var/www/blazorapp ExecStart/usr/bin/dotnet /var/www/blazorapp/BlazorApp.dll Restartalways # RestartSec10 EnvironmentASPNETCORE_URLShttp://127.0.0.1:5000 EnvironmentDOTNET_PRINT_TELEMETRY_MESSAGEfalse [Install] WantedBymulti-user.target注意EnvironmentASPNETCORE_URLShttp://127.0.0.1:5000这一行。你绑定的是内网回环地址Nginx和后端都在这台机器上这个地址可以被Nginx访问但外网无法直接访问安全上多了一道保障。启动服务sudo systemctl daemon-reload sudo systemctl enable blazorapp sudo systemctl start blazorapp查状态sudo systemctl status blazorapp看到Active: active (running)就是成功了。我习惯查完status再用curl http://127.0.0.1:5000直接打一下后端确认服务真的在本机端口上响应了再去配Nginx这样能隔离“后端问题”和“反代问题”。3.4 配置Nginx站点把站点配置放在/etc/nginx/sites-available/blazorapp再软链到/etc/nginx/sites-enabled/sudo ln -s /etc/nginx/sites-available/blazorapp /etc/nginx/sites-enabled/配置内容就用上面第三节那段HTTPS方案。保存后测试语法sudo nginx -t然后重载配置sudo systemctl reload nginx到这里整套链路就通了。浏览器访问域名页面加载SignalR握手UI交互实时刷新一切正常。3.5 别忘了后端代码里对转发头的处理很多人配置完成后发现页面虽然出来了但SignalR的请求地址是http://127.0.0.1:5000/hubs/xxx而不是https://你的域名/hubs/xxx这就是后端代码没有识别反向代理的转发头。在Program.cs里加上using Microsoft.AspNetCore.HttpOverrides; var builder WebApplication.CreateBuilder(args); builder.Services.ConfigureForwardedHeadersOptions(options { options.ForwardedHeaders ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto; options.KnownNetworks.Clear(); options.KnownProxies.Clear(); }); var app builder.Build(); app.UseForwardedHeaders();这一步的思路是Nginx转发过来的请求里有X-Forwarded-For和X-Forwarded-Proto头app.UseForwardedHeaders()会读取这些头并修正请求的Scheme和客户端IP这样应用层面就知道“用户是通过HTTPS访问的”从而生成正确的WebSocket地址和跳转链接。在只有一层Nginx代理的情况下按上面这段代码配置没有问题。如果Nginx后面还有如负载均衡之类的中间层需要注意KnownProxies的配置语义别再不加甄别地Clear否则IP伪造风险会变大。4. 常见问题与排查技巧实录这部分是大家最关心的。我整理了部署过程中最容易踩的坑每一个都是我或者身边同事亲手踩过、排查过、解决过的。4.1 WebSocket握手失败排查问题表现页面能打开但浏览器的Console里反复出现Error: Failed to start the transport WebSockets: undefined或者Error: Failed to connect to the server via WebSockets。排查顺序第一步确认SignalR请求到底走的是不是WebSocket。浏览器按F12打开开发者工具切到Network面板筛选WS类型的请求手动刷新页面看请求列表里有没有ws://或wss://开头、状态码101的请求。第二步用Nginx日志确认反代是否把Upgrade头带上去了。在你Nginx配置里加上log_format upgrade_log $remote_addr - $request_method $request_uri upgrade: $http_upgrade connection: $http_connection return: $status; access_log /var/log/nginx/upgrade.log upgrade_log;重载Nginx后再刷新页面看日志。如果upgrade:后面是空说明浏览器没发Upgrade请求过来后端问题如果upgrade: websocket正常是有的但后端返回的不是101而是404或400多半是SignalR路由没匹配上。第三步检查客户端脚本中用到的hub地址跟服务端实际注册的hub地址是否一致。Blazor内置的SignalR连接通常走/_blazor这个路径注意Nginx有没有奇怪的location规则把/_blazor劫持到静态文件或其它处理去了。我遇到过最隐蔽的一个案例是有人配了location ~ \.cshtml$之类的正则匹配把SignalR的请求误伤成了404。4.2 页面刷新直接404路由纵深问题这是另一个高发问题明明首页正常但浏览器一刷新如果访问的是/counter这种子路由Nginx直接返回404。原因还是Nginx配置不完整。Blazor Server的路由默认是服务端处理但刷新时浏览器会向服务器重新请求/counter这个路径。如果Nginx对这个路径没有任何匹配规则找不到对应文件就直接404了。正确做法是加一条try_files指令把不存在的路径回退到Kestrellocation / { try_files $uri $uri/ kestrel; } location kestrel { proxy_pass http://127.0.0.1:5000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }try_files $uri $uri/ kestrel的含义是先试试直接找磁盘上有没有这个路径对应的静态文件找不到就回退到kestrel这个命名location把请求交给后端进程由Blazor的路由系统决定返回哪个界面。这是Blazor部署必备的配置少了它刷新一次404一次特别狼狈。4.3 连接断连频繁服务不稳定表现为操作界面时频繁“尝试重新连接”等待一分钟后才知道要不要丢连接。基本就是超时参数没调好。常见原因一Nginx的proxy_read_timeout默认60秒但你忘了改。连接一闲置Nginx就带着连接走人了。常见原因二网络设备链路层有NAT超时公网环境下如果是你自己的网络环境或某类不受信任的线路中间节点把空闲连接回收了。这种情况光调Nginx没用需要应用层心跳来兜底。SignalR有默认的KeepAliveInterval默认是15秒发一次心跳包。如果你的应用改过这个配置调回15秒就好。我通常在Nginx层面对WebSocket场景统一设置proxy_read_timeout 1h; proxy_send_timeout 1h;这样就算心跳机制偶尔慢半拍空闲连接也不会被Nginx掐断。4.4 应用能访问但始终提示“无法连接后端进程”这种最诡异前端页面和WebSocket链路看起来都正常但一操作就提示后端进程掉了。先查systemd服务状态sudo systemctl status blazorapp sudo journalctl -u blazorapp -f大概率是后端进程根本没起来或者刚起来又崩了。最经典的坑是发布机器和服务器运行时版本不一致。比如开发机用的.NET 8服务器只装了.NET 6运行时的服务器启动时会立刻报错日志里写着framework Microsoft.NETCore.App, version 8.0.0 was not found。这种问题发布前先做一次版本对齐dotnet --list-runtimes看服务器上装了啥同时看看发布目录里的.runtimeconfig.json确认目标框架版本。另一个跟内存相关的知识点默认Kestrel在服务器上能接收的连接数和内存使用上限systemd服务的MemoryMax没设的话默认是不限制的。如果部署的服务器内存本身并不富余比如1GB的小机器我建议在systemd配置里加上[Service] MemoryLimit500M但超了会发生什么各位心里要有数Kestrel遇到OOM时可能整个进程被杀掉。相关预算要根据应用规模自己测算。4.5 WebSocket消息延迟大界面不跟手排查思路分两条线。一条是Nginx的proxy_buffering应设置为off我在前面已经提过。另一条是检查浏览器到服务器的链路延迟可以用ping大致测一下RTT。在云服务器跨地域部署时比如服务器在异地机房、用户在本地开发的场景下每帧交互要经历一次完整的网络往返体感就是每点一下按钮几百毫秒后才出来响应这是网络距离的物理成本。如果项目对实时性要求高部署地域应该尽量贴近用户。这是架构层面的考量往往比调几个参数更有效。5. 部署后的自检清单与体验优化最后分享一份我自己动手部署完一定过一遍的检查清单以及一些让整体体验更顺滑的进阶思路。5.1 部署完成后的五步自检第一步浏览器无痕窗口打开域名地址栏必须显示HTTPS并带锁定图标。第二步F12打开Network面板刷新页面确认/_blazorSignalR请求返回的是一堆消息而非404、400。第三步切换WS筛选方式定位WebSocket连接确认Connection Status是101切换成功的没有频繁刷新重建。第四步把页面挂到一边完完整整等十分钟期间不刷新页面回来直接在界面上操作确认依然响应流畅。第五步用systemctl status确认服务是active (running)状态顺手看一眼nginx -t输出是ok和successful。这套流程走完整套部署才算真正验收通过。5.2 后端配置上的两个优化点一个优化点是关闭静态文件在Kestrel侧的处理。既然Nginx已经托管了静态文件Kestrel侧的静态文件中间件就没必要开了。用Nginx直接服务wwwroot下的资源你会发现页面加载速度快一截。做法是在location /上面再加一个静态文件的locationlocation /css/ { alias /var/www/blazorapp/wwwroot/css/; expires 30d; } location /js/ { alias /var/www/blazorapp/wwwroot/js/; expires 30d; }但注意Assets的指纹版本是自动生成的这个路径直接代理到wwwroot即可Nginx缓存策略别把带哈希的静态文件也设成短缓存否则每次发版都要等缓存过期才能看到新样式。我把expires 30d和try_files组合使用对带指纹的静态文件效果很好文件名变了就是新请求文件名不变说明确实没改。另一个是压缩。Blazor Server页面里涉及的SignalR协议和框架脚本如果不压缩体积可不小。Nginx开启gzip压缩gzip on; gzip_types text/plain text/css application/json application/javascript application/octet-stream; gzip_min_length 1024;尤其是SignalR消息内容大多是JSON文本压缩率很可观。我实测过开启后每个UI增量消息包能压缩到原来的三分之一左右在弱网环境下对比非常明显。5.3 升级到HTTP/3和TLS优先的实践其实到这一步你的部署已经能稳定运行了。再往深走把listen指令改成listen 443 ssl; http2 on; quic_listen 443 quic;HTTP/3基于UDP的QUIC协议对弱网和高延迟链路特别友好对Blazor这种实时交互应用价值很大不过HTTP/3需要服务端和客户端同时支持目前浏览器端条件基本成熟服务器端如果网络环境支持UDP端口可以直接启用。我在另一个放在移动网络较多的生产环境里开了HTTP/3应用重连率大约下降了快三成。5.4 调了很久还是不行怎么办真到了山穷水尽的地步给你一个最笨但最有效的思路层层拆开验证。先临时让Kestrel直接绑定0.0.0.0:5000关掉Nginx用浏览器直接访问http://服务器IP:5000看应用能不能连上WebSocket。如果这一步就失败说明问题在应用或网络环境先查防火墙、云厂商安全组、服务器端口放行策略。如果这一步成功说明是Nginx代理层的问题回到配置逐行排查。把这个思路记住运维里最怕的不是配置复杂而是你同时改了Nginx、页面、代码、端口这么多东西却理不清哪一环出的问题更怕第一反应是推翻重来。剥洋葱一样一层层拆问题往往藏在你最后怀疑的那个环节。我自己部署过很多次这套架构最大的体会是Nginx对WebSocket的支持本身是成熟可靠的出错基本都在配置细节上尤其是HTTP版本、Upgrade跳转、超时这几项。多花十分钟把配置逐行看懂比出问题时干瞪眼翻半天文档强得多。希望这篇写下来能给准备把Blazor应用放到Linux上的朋友省下一些不该踩的坑。
阅读完成 · 觉得有帮助？
