企业官网建设流程全解析

如果你最近把一个Blazor Server项目部署到Linux服务器上，用nginx做反向代理，八成会遇到一个非常磨人的问题：页面能打开，静态资源也正常，但只要是实时交互的功能——比如数据看板自动刷新、消息推送、在线聊天——全部失灵。浏览器控制台里永远飘着一行红色的WebSocket connection failed。我第一次踩这个坑时，整整排查了一个晚上，最后发现问题不在Kestrel，也不在代码里，而是nginx默认不会把WebSocket协议的Upgrade握手请求原样转发给后端。

这篇文章就把这条完整的部署链路拆开讲清楚：Blazor应用怎么发布到Linux、怎么用systemd守护进程、nginx怎么配置反向代理，以及最核心的WebSocket代理细节。跟着配置走一遍，你就能得到一个页面和实时连接都稳定的生产环境。适合正在部署Blazor Server的开发者，也适合对nginx代理WebSocket原理还比较模糊的朋友。

1. 发布前的架构确认：Blazor与WebSocket的真实关系

1.1 Blazor Server和WebAssembly两种模式的区别

Blazor应用有两种运行模式，很多人部署时没搞清自己用的是哪一种，导致配置方向完全跑偏。

Blazor Server模式下，整个UI逻辑都在服务器上执行。浏览器端只是接收渲染好的DOM指令，页面上的每一次点击、输入、事件触发，都是通过一个叫SignalR的长连接通道发给服务器，服务器处理完再把界面更新的指令推回来。这个长连接默认优先走WebSocket，连不上时才会回退到Server-Sent Events或Long Polling。所以WebSocket代理配置正确与否，直接影响Blazor Server是不是“能用”。

Blazor WebAssembly则相反，程序集直接下载到浏览器里跑，页面交互不依赖服务器连接。但如果你在这个模式下用了SignalR做实时功能，比如实时图表更新、协作编辑，那本质上和Blazor Server一样需要WebSocket通道。换句话说，不管哪种模式，只要项目里用到了SignalR实时通信，nginx的WebSocket代理配置就是绕不开的环节。

我在实际项目里遇到最多的情况是：开发环境直接访问localhost:5000，浏览器和Kestrel之间没有中间层，WebSocket握手随便成功；一旦部署到Linux服务器上，浏览器先连nginx，再由nginx转发给Kestrel，多了一层代理就多了一层协议处理。nginx默认不转发Upgrade头，于是SignalR握手失败，整个应用退化成“能看不能点”的静态页面。

1.2 nginx在整条链路里到底扮演什么角色

用nginx做反向代理，通常是为了解决几个问题：统一入口端口、TLS证书终止、静态资源缓存、多应用负载均衡。对于Blazor应用来说，nginx放在浏览器和Kestrel中间，实际上是把外部的HTTPS流量转成内部HTTP流量，再转发给监听在localhost某个端口上的ASP.NET Core应用。

举个例子，Kestrel监听5000端口，浏览器访问https://your-domain.com时，nginx接收请求，把请求内容转发给http://127.0.0.1:5000。这时候nginx就是一个典型的七层反向代理。对于普通HTTP请求，这套机制很简单，配置一个proxy_pass就够了；但对于WebSocket这种“先HTTP握手、后协议升级”的连接，nginx必须额外处理两个关键请求头：Upgrade和Connection。

浏览器发起的WebSocket握手，本质上是一个带着特殊请求头的HTTP GET请求：Upgrade: websocket表示客户端想升级协议，Connection: Upgrade表示这个连接要变成双向流。nginx收到这个请求后，默认行为是把头转发给后端，但如果不显式配置Upgrade和Connection，后端Kestrel就不知道客户端想升级成WebSocket，只能按普通HTTP请求处理，握手自然失败。

所以整条链路的配置核心就一句话：让nginx把Upgrade和Connection头忠实地传给后端，并且把代理的HTTP版本设置成1.1。下面每一节都会围绕这个核心展开。

2. 发布Blazor应用到Linux：从publish到systemd

2.1 dotnet publish参数怎么选才不出幺蛾子

发布Blazor应用没有太多玄学，但参数选错会在部署时浪费大量时间。标准命令是：

dotnet publish -c Release -r linux-x64 --self-contained false -o ./publish

这里有几个参数要说明。-c Release是发布Release版本，这个没什么争议。-r linux-x64指定运行时标识符，如果服务器是ARM架构，要改成linux-arm64。最需要花心思的是--self-contained参数。

我个人的建议是：如果这台服务器上将来还要跑其他.NET项目，优先用框架依赖模式，运行时统一升级维护；如果只想省事、不想管服务器上的运行时版本冲突，直接选自包含。两种模式我都实际用过，框架依赖模式对系统环境要求更高，服务器上新装runtime后偶尔会遇到版本不匹配的问题；自包含模式则是什么都不用装，拷上去就能跑，但发布目录里会多出一堆原生运行库，部署文件明显变大。

还有一个容易忽略的细节：框架依赖模式下，服务器上只需要安装ASP.NET Core Runtime，不需要装完整的SDK。装SDK也不是不行，但生产环境里多装一个SDK就多一份安全风险和维护成本，没必要。

2.2 服务器环境准备与进程守护配置

发布后的文件通过scp或rsync传到服务器上，我习惯放在/var/www/myapp目录下。然后需要创建一个服务配置文件，让应用在后台持续运行。注意不要用nohup dotnet MyApp.dll &这种方式裸跑，服务器一重启就没了，也没法自动拉起。

用systemd是Linux上最标准的做法。先创建一个服务文件：

# /etc/systemd/system/myapp.service [Unit] Description=My Blazor Application After=network.target [Service] WorkingDirectory=/var/www/myapp ExecStart=/usr/bin/dotnet MyApp.dll Restart=always RestartSec=10 Environment=ASPNETCORE_ENVIRONMENT=Production Environment=ASPNETCORE_URLS=http://127.0.0.1:5000 User=www-data [Install] WantedBy=multi-user.target

配置说明：WorkingDirectory必须指向应用目录，因为ASP.NET Core会从这个目录读取appsettings.json和静态资源；ExecStart指定启动命令；Restart=always表示进程意外退出时自动重启，这是生产环境必备；RestartSec=10是重启间隔，避免故障时疯狂重启刷日志；User=www-data用低权限用户运行，不要用root。

这里我用ASPNETCORE_URLS=http://127.0.0.1:5000把Kestrel绑定到本机5000端口，这样外部无法直接访问应用，只能通过nginx转发进来。如果不在环境变量里指定端口，默认会监听5000和5001两个端口，5001还是HTTPS，容易造成困扰。

配置好之后，启动并设置开机自启：

sudo systemctl daemon-reload sudo systemctl enable myapp sudo systemctl start myapp # 查看运行状态和日志 sudo systemctl status myapp sudo journalctl -u myapp -f

journalctl -f这个命令在排查故障时特别有用。部署完先看一眼日志，确认Kestrel正常启动、没有报错，再去做nginx配置，否则问题出在应用层还是代理层都分不清。

3. nginx安装与WebSocket代理的核心配置

3.1 nginx安装、目录结构与站点文件规范

以Debian/Ubuntu系为例，安装nginx很简单：

sudo apt update sudo apt install nginx

安装完成后，nginx默认会启动，监听80端口。Debian系nginx的配置目录结构是：/etc/nginx/nginx.conf是主配置，/etc/nginx/sites-available/是站点可用配置目录，/etc/nginx/sites-enabled/是站点启用目录。

惯例做法是在sites-available里创建站点配置文件，再软链到sites-enabled：

sudo nano /etc/nginx/sites-available/myapp sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp

这样做的原因是方便管理多个站点，禁用一个站点时只需删除软链，不需要动原文件。改完配置后一定要先检查和重载：

sudo nginx -t sudo nginx -s reload

nginx -t会检查配置文件语法，有错误会明确指出是哪个文件第几行。这个步骤不能省，我见过不少人改完配置直接reload，结果语法错误nginx拒绝启动，整个服务都挂了。

3.2 Upgrade和Connection头：WebSocket代理的关键原理

WebSocket连接建立的关键在于HTTP的协议升级机制。客户端发起一个普通的GET请求，请求头里带Upgrade: websocket和Connection: Upgrade，服务器如果同意升级，返回101 Switching Protocols，之后这个TCP连接上跑的就不再是HTTP协议，而是WebSocket双工数据流。

nginx在转发这个握手请求时，有两个默认行为会造成麻烦。第一，nginx向上游服务器发起请求时默认使用HTTP/1.0版本，而HTTP/1.0的协议语义里没有完整的Connection头处理机制，后端收到请求后无法正确识别升级意图。第二，nginx默认不会把客户端的Upgrade和Connection头透传给上游，因为这两个头字段在普通请求里是逐跳的，不应被转发。

所以在配置里，需要显式设置三件事：把代理HTTP版本设为1.1，把Upgrade头传给后端，把Connection头设置成合适的值。

关于Connection头的值，网上最常见的配置是固定写死proxy_set_header Connection "upgrade"。但这样做有一个问题：这个location块里同时处理普通HTTP请求和WebSocket握手请求，对于普通请求，后端收到Connection: upgrade会感到困惑，可能影响连接行为。更严谨的做法是配合map指令，根据请求头里是否真的有Upgrade来动态决定：

map $http_upgrade $connection_upgrade { default upgrade; '' close; }

这段map的意思是：如果请求头里有Upgrade字段，就把connection_upgrade变量设为upgrade；如果为空，就设为close。然后在location块里引用$connection_upgrade变量。这样做的好处是普通HTTP请求和WebSocket握手请求都能得到正确的Connection头语义，一个location块通吃所有流量。

3.3 我的完整nginx配置逐行解析

下面是我在多个Blazor项目里实际使用的nginx完整配置，经过生产验证，可以直接参考：

# /etc/nginx/sites-available/myapp # 模块级map配置，放在server块外面 map $http_upgrade $connection_upgrade { default upgrade; '' close; } # HTTP -> HTTPS 跳转 server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; } # HTTPS 服务 server { listen 443 ssl http2; server_name your-domain.com; # 证书配置，按你的实际证书路径修改 ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; # 应用根路径，匹配所有请求 location / { proxy_pass http://127.0.0.1:5000; # 核心三行：WebSocket代理的关键 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-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 关闭代理缓冲，保证实时数据及时推送 proxy_buffering off; proxy_cache off; # 超时设置，后面详说 proxy_connect_timeout 10s; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }

这段配置的核心就在location /块里。proxy_pass http://127.0.0.1:5000把所有请求转发给Kestrel；proxy_http_version 1.1告诉nginx向上游用HTTP/1.1发请求；两个proxy_set_header解决Upgrade和Connection头的透传问题。

要注意的是，这个配置里没有单独为/_blazor路径写location。Blazor Server的SignalR端点默认挂在/_blazor下，但因为根路径的location已经配置了WebSocket转发头，所有请求都覆盖到了，不需要再单独处理。如果之前有人在网上看到过单独配置/_blazor的版本，那是理解有偏差的写法，一个通用location足以覆盖所有WebSocket端点。

3.4 超时、缓冲、连接复用：参数推算与调优思路

nginx的默认超时参数对WebSocket长连接来说偏短。proxy_read_timeout默认60秒，表示nginx两次读取上游数据之间的最大间隔。WebSocket连接建立后，如果没有数据包传输，60秒后nginx就会判定超时断开连接。浏览器端的SignalR虽然默认有keepalive心跳机制，但有几种情况仍然可能触发这个超时，比如浏览器标签页被切到后台时心跳频率降低，或者客户端网络不稳定导致心跳包丢失。

我的做法是把proxy_read_timeout和proxy_send_timeout都设置为3600s。有人问设这么大是不是浪费资源，其实不会，这个参数只是定义一个空闲连接的最长等待时间，并不是固定占用连接一小时。它只影响空闲状态的连接，连接一旦有数据传输，超时时间会从最后一次传输开始重新计算。所以设大一点对服务器负担没有任何影响，反而能避免很多莫名其妙的掉线。

proxy_buffering off也很关键。nginx默认会缓冲上游返回的数据，攒够一定量再发给客户端。对WebSocket这种实时双工协议来说，nginx根本不会去缓冲升级后的数据，但有时握手阶段的数据或SSE推送会被缓冲影响，造成延迟或连接异常。干脆关闭缓冲最省心。proxy_cache off同理，WebSocket是动态连接，没有任何缓存语义，开着反而可能干扰。

连接复用方面，如果是单应用部署，不需要配置upstream负载均衡。但如果以后要扩展多实例，可以用upstream定义一组后端服务器，配置keepalive 64来复用连接，减少握手开销。目前这个部署规模，一个proxy_pass直接指向应用就够了。

4. HTTPS与WSS：生产环境必须处理的细节

4.1 证书签发与自动续期的实操记录

浏览器在现代版本中已经不再支持HTTP页面下的WebSocket连接，生产环境必须上HTTPS，否则WebSocket握手会被浏览器直接拦截。HTTPS下的WebSocket协议是WSS，就是非常简单的规则：TLS终止在nginx处，nginx把解密后的流量转发给Kestrel时，后端根本不知道TLS的存在，所以Kestrel不需要配置证书。

证书签发我用的是社区里常用的ACME客户端工具。流程大致是：先安装客户端工具，然后在域名解析服务商那里配置一条TXT记录用于验证域所有权，验证通过后签发证书，再设置一个定时任务实现自动续期。证书文件签发后，放到一个nginx能读取的目录，比如/etc/nginx/ssl/，修改配置指向fullchain.pem和privkey.pem。

整个操作里最容易出问题的其实不是申请步骤，而是续期后nginx没有重载导致证书过期没生效。我习惯在续期命令后面加上nginx reload：

# 续期成功后自动重载nginx配置 certbot renew --quiet --deploy-hook "systemctl reload nginx"

这样每次证书更新完，nginx自动加载新证书，不需要人工干预。

listen 443 ssl http2这个配置中的http2参数不影响WebSocket。浏览器发起WebSocket连接时走的是HTTP/1.1的Upgrade机制，不会走HTTP/2的CONNECT帧，所以即使nginx开着HTTP/2，WebSocket连接仍然按HTTP/1.1处理，没有兼容性问题。

4.2 应用侧ForwardedHeaders与客户端IP恢复

nginx转发请求时，应用看到的客户端地址是127.0.0.1，也就是nginx的地址，而不是真实用户的IP。ASP.NET Core需要读取X-Forwarded-For和X-Forwarded-Proto头来恢复真实客户端信息和原始协议。

在Blazor应用里处理这个问题的标准做法是用ForwardedHeaders中间件。在Program.cs中启动链路的开头加上：

builder.Services.Configure<ForwardedHeadersOptions>(options => { options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XProto; }); var app = builder.Build(); app.UseForwardedHeaders(); app.UseStaticFiles(); app.UseRouting(); // 其他中间件

UseForwardedHeaders必须放在UseStaticFiles和UseRouting之前，因为后面这些中间件都可能依赖客户端IP和协议信息。这个步骤对Blazor Server尤其重要，因为SignalR在协商阶段会根据当前请求的Scheme生成连接URL，如果应用不知道请求实际是HTTPS进来的，生成的回连地址可能还是ws://而不是wss://，导致前端连接失败。

.NET 7+也支持通过环境变量ASPNETCORE_FORWARDEDHEADERS_ENABLED=true一键启用转发头处理，但环境变量方式对所有代理头一视同仁，不像中间件可以精细控制信任哪些头。生产环境我更推荐中间件的写法，代码里看得见，也方便限制只信任本机代理。

5. 常见问题排查与稳定性实测

5.1 高频故障对照表

把这几年部署Blazor应用时遇到的高频问题整理成一张速查表，基本覆盖最常见的失败场景：

这里最诡异的一种情况是“页面能打开但交互全部失灵”。因为HTTP请求在nginx层被正常转发，静态资源和页面HTML都能加载出来，用户根本看不出代理有问题。只有打开浏览器控制台，看到WebSocket连接失败的红字，才知道底层信号通道断了。所以遇到Blazor Server应用“假活”的问题，第一个排查动作永远是看控制台里的网络请求和nginx的访问日志。

5.2 用curl验证代理是否真正支持升级

配置完nginx后，不要急着打开浏览器验证，先用curl发一个模拟的WebSocket握手请求：

curl -i -N \ -H "Connection: Upgrade" \ -H "Upgrade: websocket" \ -H "Sec-WebSocket-Version: 13" \ -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \ https://your-domain.com/

注意这个请求的路径不一定要填/_blazor，填根路径/就可以验证nginx配置是否正确。如果返回的响应码是101 Switching Protocols，说明nginx已经把Upgrade握手请求转发给了后端，代理配置成功。如果返回200或其他状态码，说明握手请求被当成普通HTTP请求处理了，回到第3章的配置逐项检查。

另一个验证方式是在nginx的访问日志里看状态码。WebSocket握手成功时，nginx请求日志中的状态码是101。如果看到101，说明代理链路通了；如果看到200，说明nginx没有识别这个连接需要升级，重点检查Upgrade头的配置。

我实际调试时最喜欢先跑一遍这个curl，几秒钟就能判断问题出在nginx层还是应用层，省去大量盲猜时间。还有一次遇到的问题很隐蔽：服务器防火墙没有放行443端口，页面打开正常（因为走的是80跳转后再到443），但WebSocket握手包被防火墙丢弃，浏览器端表现为一直连接中。所以遇到连接失败，先确认服务器安全组和系统防火墙都放行了443端口，不要一上来就怀疑代码。

5.3 压力场景下的稳定性实测

我这边实际部署的是一套内部实时监控系统，Blazor Server模式，后端用Kestrel，前面就是nginx代理。服务器配置是2核4G的云主机，系统是Ubuntu 22.04，发布模式选的是框架依赖部署，nginx配置就是上面贴的那套模板。

上线初期最大的教训就是超时配置。当时用的是nginx默认的60秒，第一天运行一切正常，第二天早上收到一堆反馈说“昨晚挂到凌晨之后页面就死掉了，刷新一下又能用”。原因就是夜间用户长时间不操作，WebSocket连接空闲超过60秒被nginx切断，浏览器没有及时重连。把超时改到3600秒之后，这个现象再也没出现过。

在并发方面，这套系统日常保持大约200个左右的活动WebSocket连接，nginx的CPU占用几乎是一条平线，内存占用也稳定在合理范围。有几个经验值得说一下：一是worker_processes auto让nginx按CPU核心数自动调整进程数，不需要手动指定；二是worker_connections在默认配置基础上调到了10240，避免高并发时出现worker连接数不足的提示；三是如果后续要扩大规模，优先考虑把SignalR的背板（backplane）做实，比如用Redis做多实例消息同步，再配合nginx的upstream做负载均衡，单机部署这条链路本身已经没有瓶颈。

一些额外想说的

在WebSocket代理这件事上，我用过不止一次的血泪经历换来的核心认知是：反向代理不是一根通透的管子，它会按自己的规则重新组装HTTP头。对WebSocket这种“升级型”协议，nginx的默认态度是“不关我事”，必须显式告诉它：这个连接要升级，请放行。把Upgrade、Connection、proxy_http_version这三个点吃透，Blazor发布到Linux的这道坎就基本迈过去了。

最后分享一个小技巧：以后遇到WebSocket连不上的问题，先开nginx的access_log，找最新的请求状态码。如果看到一片101，说明代理层完全正常，问题就在后端或代码里；如果看不到101，按这篇文章的配置从头对一遍。用日志定位问题，永远比在浏览器控制台和代码里来回猜效率高。