Ubuntu/Apache部署Blazor Server的代理配置与WebSocket故障排查

现有配置核心问题 #

• 规则匹配顺序错误：Apache的ProxyPass按配置从上到下优先级匹配，你先配置的/ProjectName/HTTPS代理规则会拦截所有请求，后面写的_blazorWebSocket代理规则根本不会触发。
• 规则冲突：同时使用mod_rewrite和mod_proxy两套逻辑处理WebSocket跳转，重复代理会导致连接直接中断。
• 缺少必要请求头：没有透传WebSocket升级相关的头信息，后端Kestrel识别不到WebSocket升级请求，只会按普通HTTP请求处理。
• 无效配置：根路径的ProxyPassReverse写了ws协议、多余的ProxyPassMatch规则都会干扰正常请求转发。
• 之前部署Shiny正常是因为Shiny的WebSocket路径没有子路径适配的特殊要求，Blazor依赖的SignalR端点对路径匹配、请求头的要求更严格。

修复步骤 #

1. 先启用Apache必要的代理模块，执行以下命令：

a2enmod proxy proxy_http proxy_wstunnel headers ssl

2. 删除原有配置中<IfModule rewrite_module>块内所有WebSocket相关的重写规则，不需要用rewrite处理WebSocket跳转，proxy_wstunnel模块原生支持ws协议代理。
3. 删除原有代理配置中多余的错误规则：包括ProxyPassMatch ^/ProjectName/_blazor/(.*)那行、根路径指向ws地址的ProxyPassReverse那行。
4. 替换为以下正确的代理配置，注意越精确的路径规则越要放在前面：

<IfModule proxy_http_module>
    SSLEngine on
    SSLProxyEngine on
    ProxyPreserveHost On
    ProxyRequests Off

    # 透传必要请求头，供后端识别原始请求信息、WebSocket升级请求
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
    RequestHeader set "X-Forwarded-For" expr=%{REMOTE_ADDR}

    # 最高优先级：匹配_blazor WebSocket端点，走ws协议代理
    ProxyPass /ProjectName/_blazor ws://localhost:5001/_blazor
    ProxyPassReverse /ProjectName/_blazor ws://localhost:5001/_blazor

    # 次优先级：匹配所有其他普通请求，走HTTPS代理
    ProxyPass /ProjectName/ https://localhost:5001/
    ProxyPassReverse /ProjectName/ https://localhost:5001/
</IfModule>

5. 检查Blazor应用端配置，在应用的Program.cs中，app.UseRouting()之前添加子路径配置，和代理的子路径保持一致：

app.UsePathBase("/ProjectName");

6. 执行配置语法检查，确认无报错后重启Apache生效：

apache2ctl configtest
systemctl restart apache2

验证注意事项 #

• 清除浏览器缓存、关闭已打开的站点标签页后重新访问，避免之前缓存的长轮询fallback配置干扰测试结果。
• 单实例部署不需要配置粘性会话，只有多实例负载均衡场景才需要开启。
• 检查服务器本地防火墙是否放行5001端口的回环访问，避免Apache无法连接到后端Blazor应用。

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