1. 项目概述为什么在.NET 5 WebAPI里硬要搭WebSocket服务端我第一次接到这个需求时客户原话是“页面要实时显示设备在线状态每秒刷新一次但不能用轮询——太耗资源老板说看到HTTP请求瀑布流就头疼。”当时团队里有人提议“加个SignalR”我拦住了。不是SignalR不好而是这个项目有三个硬约束部署环境只允许开一个端口、前端是纯静态HTML原生JS不引入任何框架、后续要迁移到边缘网关设备上跑。这三个条件一叠加SignalR那套HubJSON序列化长连接心跳的整套机制光是依赖项体积和内存占用就直接出局。.NET 5 WebAPI自带的Microsoft.AspNetCore.WebSockets中间件就是为这种“轻量级、可控性高、不想要魔法”的场景准备的。它不封装协议细节不自动处理重连不内置广播逻辑——听起来像缺点实则是优势。你清楚知道每个字节怎么进、怎么出连接生命周期完全由你掌控。比如设备上线时服务端主动推送一条结构化JSON设备断线时你能在OnCloseAsync里精确记录离线时间戳而不是等SignalR的超时检测默认30秒。这种确定性在工业数据采集、IoT设备管理这类对时序精度敏感的场景里比“省事”重要十倍。核心关键词全在这里了.NET 5非.NET Core 3.1或.NET 6意味着不能用WebApplication.CreateBuilder新语法得手写Startup.cs、WebAPI不是MVC没有View所有逻辑必须走Controller或Middleware、WebSocket服务端注意是“服务端”重点在AcceptWebSocketAsync、WebSocketManager、WebSocket对象生命周期管理。这不是教你怎么点几下鼠标生成模板而是带你从Program.cs第一行开始把WebSocket握手、帧解析、心跳保活、异常熔断这些底层动作全部掰开揉碎塞进WebAPI管道里。适合谁适合正在维护老系统、需要嵌入式部署、或者想真正搞懂WebSocket底层机制的开发者。别怕下面每一步我都贴了真实调试日志和内存快照对比。2. 整体架构设计与技术选型逻辑2.1 为什么放弃SignalR而选择原生WebSocket很多人看到“实时通信”第一反应就是SignalR但在这个项目里SignalR成了最该被排除的选项。原因不是它功能弱恰恰相反是它功能太强、太“智能”反而破坏了可控性。我列个对比表这是我在某边缘计算网关上实测的数据对比维度原生WebSocketSignalR默认配置实测影响内存占用单连接1.2MB4.7MB网关设备只有512MB RAMSignalR撑不住20个并发首次握手耗时83ms纯HTTP Upgrade210ms协商传输方式建立Hub上下文设备上线延迟超阈值触发告警误报消息序列化开销直接byte[]写入零序列化自动JSON序列化Base64编码同样1KB数据网络传输体积大37%连接中断检测WebSocket.CloseStatus立即返回默认30秒超时后才触发OnDisconnectedAsync设备突然断电服务端30秒内仍认为在线最关键的是第三点消息序列化开销。SignalR为了兼容多种传输方式Server-Sent Events、Long Polling强制把所有消息转成JSON再编码。而我们的设备协议是二进制帧前2字节是命令ID后4字节是时间戳接着是变长负载。用SignalR就得在前后端各加一层编解码器等于把简单问题复杂化。原生WebSocket直接收发byte[]设备发什么服务端就收什么连BitConverter.ToInt32()都省了。提示如果你的项目不需要二进制协议、不关心内存占用、且前端已用Vue/React配SignalR客户端那SignalR仍是首选。但凡有一条不符合原生WebSocket的确定性就是刚需。2.2 为什么必须基于WebAPI而非Kestrel裸服务有人会问“既然要轻量干脆不用ASP.NET Core直接用Kestrel写个裸WebSocket服务”这想法很酷但落地会踩坑。我们试过——在某次压力测试中当并发连接数超过800时裸Kestrel服务的CPU飙升到95%而同样配置的WebAPIWebSocket中间件只有62%。差异在哪ASP.NET Core的WebSocketManager内置了连接池和异步I/O调度优化。它把每个WebSocket连接映射到一个WebSocketConnection对象这个对象内部用MemoryPoolbyte管理缓冲区避免高频new byte[4096]导致GC风暴。而裸Kestrel需要自己实现这套内存管理工作量远超收益。更实际的约束是部署。客户要求所有服务必须走统一网关Nginx而Nginx对WebSocket的支持依赖于Upgrade头透传。WebAPI的UseWebSockets中间件会自动设置WebSocketOptions.KeepAliveInterval TimeSpan.FromSeconds(120)并确保Upgrade头不被中间件链截断。裸Kestrel服务则需要手动配置Connection: upgrade和Upgrade: websocket头稍有不慎Nginx就把WebSocket降级成普通HTTP前端报Error during WebSocket handshake: Unexpected response code: 200。2.3 架构分层如何让WebSocket不污染WebAPI业务逻辑这是最容易被忽略的设计点。很多初学者把WebSocket处理逻辑全塞进WebSocketController里结果Controller越来越臃肿单元测试无法覆盖热更新时还得重启整个API。我们的方案是三层解耦接入层Controller只做三件事——验证用户Token、检查设备ID合法性、调用WebSocketManager.AcceptWebSocketAsync()。绝不处理任何业务消息。会话管理层WebSocketSessionManager全局单例用ConcurrentDictionarystring, WebSocketSession管理所有连接。Key是设备ID非Session IDValue是封装了WebSocket对象、心跳计时器、最后通信时间戳的WebSocketSession类。这里实现了连接复用同一设备ID重复连接时自动关闭旧连接避免“设备在线但指令发不出去”的脏状态。业务分发层MessageRouter收到WebSocket消息后根据首字节命令ID路由到对应处理器如DeviceStatusHandler、FirmwareUpdateHandler。每个处理器都是独立类可单独单元测试支持插件式加载。这种分层让代码可测试性大幅提升。我们给MessageRouter写了23个单元测试用例覆盖了命令ID不存在、消息体长度不足、心跳包格式错误等所有边界情况而Controller层测试只需验证Token校验逻辑——因为WebSocket连接建立后的所有行为都不再经过Controller。3. 核心细节解析与实操要点3.1 Startup.cs配置避开.NET 5的两个致命陷阱.NET 5的Startup.cs配置看似简单但有两个坑会让WebSocket直接失效且错误日志毫无提示。第一个坑在ConfigureServices// ❌ 错误写法在AddControllers之后注册WebSocket服务 services.AddControllers(); services.AddWebSockets(); // 这行必须在AddControllers之前 // ✅ 正确顺序WebSocket服务必须优先注册 services.AddWebSockets(options { options.KeepAliveInterval TimeSpan.FromSeconds(120); options.ReceiveBufferSize 4 * 1024; // 4KB接收缓冲区够用 }); services.AddControllers();为什么顺序重要因为AddWebSockets()会向DI容器注入IWebSocketManager而AddControllers()内部会扫描所有ControllerBase子类如果WebSocketController里依赖IWebSocketManager但IWebSocketManager还没注册就会在运行时抛InvalidOperationException。这个错误不会在启动时报而是在第一个WebSocket连接请求时才暴露日志里只有一句Object reference not set to an instance of an object排查起来极其痛苦。第二个坑在Configure方法的中间件顺序// ❌ 错误顺序UseRouting放在UseWebSockets之后 app.UseWebSockets(); // WebSocket中间件 app.UseRouting(); // 路由中间件——错这会导致WebSocket升级失败 app.UseEndpoints(endpoints { /* ... */ }); // ✅ 正确顺序UseRouting必须在UseWebSockets之前 app.UseRouting(); app.UseWebSockets(); // 现在WebSocket中间件能正确识别Upgrade请求 app.UseEndpoints(endpoints { /* ... */ });原理是UseRouting负责解析HTTP请求路径和方法UseWebSockets需要知道当前请求是否匹配WebSocket升级路径如/ws/device才能决定是否执行AcceptWebSocketAsync()。如果UseWebSockets在UseRouting之前它根本不知道请求该路由到哪个Controller只能放行所有请求导致WebSocket握手永远卡在HTTP 101 Switching Protocols阶段。注意UseWebSockets中间件本身不处理具体业务逻辑它只是“守门员”检查请求头是否有Upgrade: websocket。真正的连接处理全在Controller里完成。3.2 WebSocketController实现如何安全地接管连接WebSocketController是整个服务的入口但它的职责必须极度单一。我们定义了一个WebSocketController : ControllerBase里面只保留一个Connect方法[ApiController] [Route(api/[controller])] public class WebSocketController : ControllerBase { private readonly IWebSocketSessionManager _sessionManager; private readonly ILoggerWebSocketController _logger; public WebSocketController(IWebSocketSessionManager sessionManager, ILoggerWebSocketController logger) { _sessionManager sessionManager; _logger logger; } [HttpGet(connect)] public async Task Connect() { if (!HttpContext.WebSockets.IsWebSocketRequest) { _logger.LogWarning(非WebSocket请求被拒绝); HttpContext.Response.StatusCode StatusCodes.Status400BadRequest; return; } // 1. Token验证从Query或Header取 var token Request.Query[token].ToString(); if (!ValidateToken(token)) { _logger.LogWarning(Token验证失败{Token}, token); HttpContext.Response.StatusCode StatusCodes.Status401Unauthorized; return; } // 2. 设备ID提取强制从Query参数避免POST体解析 var deviceId Request.Query[device_id].ToString(); if (string.IsNullOrWhiteSpace(deviceId) || deviceId.Length 32) { _logger.LogWarning(设备ID非法{DeviceId}, deviceId); HttpContext.Response.StatusCode StatusCodes.Status400BadRequest; return; } // 3. 接管WebSocket连接 using var webSocket await HttpContext.WebSockets.AcceptWebSocketAsync(); _logger.LogInformation(WebSocket连接建立{DeviceId}, deviceId); // 4. 启动会话在后台Task中运行不阻塞HTTP线程 _ Task.Run(() _sessionManager.HandleWebSocketAsync(webSocket, deviceId)); } private bool ValidateToken(string token) !string.IsNullOrEmpty(token) token.StartsWith(DEV_); // 简化示例实际用JWT }关键点解析绝不使用async voidConnect方法是async Task但内部Task.Run启动后台任务。这是因为AcceptWebSocketAsync()会将HTTP连接升级为WebSocket之后HTTP上下文HttpContext就失效了。如果在Connect里直接await HandleWebSocketAsync()会导致HttpContext被释放后还尝试访问引发ObjectDisposedException。设备ID必须从Query获取很多教程教人从POST Body读设备ID这是大忌。WebSocket握手是HTTP GET请求Body为空。强行读Body会触发HttpRequest.Body的同步读取阻塞整个Kestrel线程池。日志必须带设备ID在高并发场景下日志里不带设备ID等于没日志。我们用_logger.LogInformation(WebSocket连接建立{DeviceId}, deviceId)这样在Serilog里能按DeviceId字段快速过滤。3.3 心跳保活与异常熔断如何让连接不死不僵WebSocket连接最大的痛点不是建立失败而是“假在线”——设备端网络断了服务端却还认为连接正常。原生WebSocket没有内置心跳必须自己实现。我们的方案是双心跳机制服务端主动心跳Ping在WebSocketSession类里启动一个Timer每90秒发送一次Ping帧private readonly Timer _pingTimer; private volatile bool _isConnected true; public WebSocketSession(WebSocket webSocket, string deviceId) { WebSocket webSocket; DeviceId deviceId; _pingTimer new Timer(async _ { if (!_isConnected || WebSocket.State ! WebSocketState.Open) return; try { // 发送Ping帧WebSocket协议规定Ping帧必须是2字节内容任意 var pingBuffer new byte[2] { 0x01, 0x02 }; await WebSocket.SendAsync(new ArraySegmentbyte(pingBuffer), WebSocketMessageType.Ping, true, CancellationToken.None); } catch (Exception ex) { _logger.LogWarning(ex, 发送Ping失败{DeviceId}, DeviceId); await CloseAsync(WebSocketCloseStatus.InternalServerError, Ping failed); } }, null, TimeSpan.FromSeconds(90), TimeSpan.FromSeconds(90)); }客户端响应心跳Pong但光发Ping不够必须监听客户端的Pong响应。.NET 5的WebSocket类不直接暴露Pong事件但我们可以通过ReceiveAsync捕获private async Task ReceiveLoop() { var buffer new byte[1024]; while (_isConnected WebSocket.State WebSocketState.Open) { try { var result await WebSocket.ReceiveAsync( new ArraySegmentbyte(buffer), CancellationToken.None); if (result.MessageType WebSocketMessageType.Close) { await CloseAsync(result.CloseStatus.Value, result.CloseStatusDescription); break; } // 关键捕获Pong帧WebSocketMessageType.Pong if (result.MessageType WebSocketMessageType.Pong) { _lastPongTime DateTime.UtcNow; // 更新最后Pong时间 continue; } // 处理业务消息 await _messageRouter.RouteAsync(this, buffer, result.Count); } catch (WebSocketException ex) when (ex.WebSocketErrorCode WebSocketErrorCode.ConnectionClosedPrematurely) { _logger.LogInformation(连接被客户端主动关闭{DeviceId}, DeviceId); break; } catch (Exception ex) { _logger.LogError(ex, 接收消息异常{DeviceId}, DeviceId); break; } } }熔断判断逻辑有了_lastPongTime我们就能做熔断// 在定时检查任务中 if ((DateTime.UtcNow - _lastPongTime).TotalSeconds 180) // 3分钟没收到Pong { _logger.LogWarning(设备失联触发熔断{DeviceId}, DeviceId); await CloseAsync(WebSocketCloseStatus.EndpointUnavailable, No Pong received); }这个180秒是精心计算的服务端Ping间隔90秒网络抖动预留90秒容错。实测在4G弱网环境下99.2%的Pong都能在120秒内到达180秒足够覆盖极端情况。4. 实操过程与核心环节实现4.1 从零搭建完整代码清单与配置说明现在把所有碎片拼起来给出可直接运行的最小可行代码。项目结构如下DeviceMonitor.Api/ ├── Controllers/ │ └── WebSocketController.cs ├── Services/ │ ├── WebSocketSessionManager.cs │ ├── WebSocketSession.cs │ └── MessageRouter.cs ├── Handlers/ │ ├── DeviceStatusHandler.cs │ └── FirmwareUpdateHandler.cs ├── Startup.cs └── Program.csStep 1注册服务Startup.cspublic void ConfigureServices(IServiceCollection services) { // ⚠️ 陷阱1WebSocket服务必须在AddControllers之前注册 services.AddWebSockets(options { options.KeepAliveInterval TimeSpan.FromSeconds(120); options.ReceiveBufferSize 4 * 1024; }); services.AddControllers(); // 注册自定义服务 services.AddSingletonIWebSocketSessionManager, WebSocketSessionManager(); services.AddSingletonIMessageRouter, MessageRouter(); // 注册消息处理器 services.AddTransientIDeviceStatusHandler, DeviceStatusHandler(); services.AddTransientIFirmwareUpdateHandler, FirmwareUpdateHandler(); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseHttpsRedirection(); // ⚠️ 陷阱2UseRouting必须在UseWebSockets之前 app.UseRouting(); app.UseWebSockets(); // WebSocket中间件 app.UseEndpoints(endpoints { endpoints.MapControllers(); }); }Step 2会话管理器WebSocketSessionManager.cspublic interface IWebSocketSessionManager { Task HandleWebSocketAsync(WebSocket webSocket, string deviceId); Task BroadcastAsync(string deviceId, byte[] message); Task CloseSessionAsync(string deviceId); } public class WebSocketSessionManager : IWebSocketSessionManager { private readonly ConcurrentDictionarystring, WebSocketSession _sessions new ConcurrentDictionarystring, WebSocketSession(); private readonly ILoggerWebSocketSessionManager _logger; public WebSocketSessionManager(ILoggerWebSocketSessionManager logger) { _logger logger; } public async Task HandleWebSocketAsync(WebSocket webSocket, string deviceId) { // 设备ID重复连接先关闭旧会话 if (_sessions.TryGetValue(deviceId, out var oldSession)) { _logger.LogInformation(设备重复连接关闭旧会话{DeviceId}, deviceId); await oldSession.CloseAsync(WebSocketCloseStatus.NormalClosure, Reconnected); } // 创建新会话并加入字典 var session new WebSocketSession(webSocket, deviceId, _logger); _sessions.TryAdd(deviceId, session); try { await session.StartAsync(); } finally { // 会话结束从字典移除 _sessions.TryRemove(deviceId, out _); _logger.LogInformation(WebSocket会话结束{DeviceId}, deviceId); } } public async Task BroadcastAsync(string deviceId, byte[] message) { if (_sessions.TryGetValue(deviceId, out var session)) { await session.SendAsync(message); } } public async Task CloseSessionAsync(string deviceId) { if (_sessions.TryGetValue(deviceId, out var session)) { await session.CloseAsync(WebSocketCloseStatus.NormalClosure, Admin closed); } } }Step 3会话核心类WebSocketSession.cspublic class WebSocketSession { public WebSocket WebSocket { get; } public string DeviceId { get; } public DateTime LastActiveTime { get; private set; } private readonly ILogger _logger; private readonly IMessageRouter _router; private readonly Timer _pingTimer; private readonly Timer _livenessTimer; private volatile bool _isConnected true; private DateTime _lastPongTime DateTime.UtcNow; public WebSocketSession(WebSocket webSocket, string deviceId, ILogger logger, IMessageRouter router null) { WebSocket webSocket; DeviceId deviceId; _logger logger; _router router ?? throw new ArgumentNullException(nameof(router)); // 启动Ping定时器90秒 _pingTimer new Timer(SendPing, null, TimeSpan.FromSeconds(90), TimeSpan.FromSeconds(90)); // 启动存活检查定时器每30秒检查一次Pong _livenessTimer new Timer(CheckLiveness, null, TimeSpan.FromSeconds(30), TimeSpan.FromSeconds(30)); } public async Task StartAsync() { LastActiveTime DateTime.UtcNow; _lastPongTime DateTime.UtcNow; try { await ReceiveLoop(); } catch (Exception ex) { _logger.LogError(ex, 会话异常终止{DeviceId}, DeviceId); } finally { _pingTimer?.Dispose(); _livenessTimer?.Dispose(); } } private async Task ReceiveLoop() { var buffer new byte[4096]; while (_isConnected WebSocket.State WebSocketState.Open) { try { var result await WebSocket.ReceiveAsync( new ArraySegmentbyte(buffer), CancellationToken.None); LastActiveTime DateTime.UtcNow; if (result.MessageType WebSocketMessageType.Close) { await CloseAsync(result.CloseStatus.Value, result.CloseStatusDescription); break; } if (result.MessageType WebSocketMessageType.Pong) { _lastPongTime DateTime.UtcNow; continue; } if (result.MessageType WebSocketMessageType.Binary || result.MessageType WebSocketMessageType.Text) { await _router.RouteAsync(this, buffer, result.Count); } } catch (WebSocketException ex) when (ex.WebSocketErrorCode WebSocketErrorCode.ConnectionClosedPrematurely) { _logger.LogInformation(客户端主动断开{DeviceId}, DeviceId); break; } catch (Exception ex) { _logger.LogError(ex, 接收消息异常{DeviceId}, DeviceId); break; } } } private async Task SendPing(object state) { if (!_isConnected || WebSocket.State ! WebSocketState.Open) return; try { var pingBuffer new byte[2] { 0x01, 0x02 }; await WebSocket.SendAsync(new ArraySegmentbyte(pingBuffer), WebSocketMessageType.Ping, true, CancellationToken.None); } catch (Exception ex) { _logger.LogWarning(ex, Ping发送失败{DeviceId}, DeviceId); await CloseAsync(WebSocketCloseStatus.InternalServerError, Ping failed); } } private void CheckLiveness(object state) { if ((DateTime.UtcNow - _lastPongTime).TotalSeconds 180) { _logger.LogWarning(设备失联触发熔断{DeviceId}, DeviceId); _ CloseAsync(WebSocketCloseStatus.EndpointUnavailable, No Pong received); } } public async Task SendAsync(byte[] message) { if (!_isConnected || WebSocket.State ! WebSocketState.Open) return; try { await WebSocket.SendAsync(new ArraySegmentbyte(message), WebSocketMessageType.Binary, true, CancellationToken.None); } catch (Exception ex) { _logger.LogError(ex, 发送消息失败{DeviceId}, DeviceId); } } public async Task CloseAsync(WebSocketCloseStatus status, string description) { if (!_isConnected) return; _isConnected false; try { await WebSocket.CloseAsync(status, description, CancellationToken.None); } catch (Exception ex) { _logger.LogWarning(ex, 关闭WebSocket异常{DeviceId}, DeviceId); } } }Step 4消息路由器MessageRouter.cspublic interface IMessageRouter { Task RouteAsync(WebSocketSession session, byte[] buffer, int length); } public class MessageRouter : IMessageRouter { private readonly IServiceProvider _serviceProvider; private readonly ILoggerMessageRouter _logger; public MessageRouter(IServiceProvider serviceProvider, ILoggerMessageRouter logger) { _serviceProvider serviceProvider; _logger logger; } public async Task RouteAsync(WebSocketSession session, byte[] buffer, int length) { if (length 2) { _logger.LogWarning(消息体过短丢弃{Length}, length); return; } var commandId buffer[0]; // 首字节为命令ID var payload new byte[length - 1]; Array.Copy(buffer, 1, payload, 0, length - 1); try { switch (commandId) { case 0x01: var statusHandler _serviceProvider.GetRequiredServiceIDeviceStatusHandler(); await statusHandler.HandleAsync(session, payload); break; case 0x02: var updateHandler _serviceProvider.GetRequiredServiceIFirmwareUpdateHandler(); await updateHandler.HandleAsync(session, payload); break; default: _logger.LogWarning(未知命令ID{CommandId}, commandId); break; } } catch (Exception ex) { _logger.LogError(ex, 处理命令ID {CommandId} 失败, commandId); } } }Step 5前端连接示例纯JavaScriptscript let socket; const deviceId DEV_123456789; const token DEV_abc123; function connectWebSocket() { const url wss://your-api.com/api/websocket/connect?device_id${deviceId}token${token}; socket new WebSocket(url); socket.onopen function(event) { console.log(WebSocket连接成功); // 启动心跳浏览器不支持自动Pong需手动响应 startHeartbeat(); }; socket.onmessage function(event) { if (event.data instanceof Blob) { const reader new FileReader(); reader.onload function() { const bytes new Uint8Array(reader.result); console.log(收到二进制消息, bytes); }; reader.readAsArrayBuffer(event.data); } }; socket.onclose function(event) { console.log(WebSocket关闭, event.code, event.reason); // 自动重连指数退避 setTimeout(connectWebSocket, Math.min(1000 * Math.pow(2, retryCount), 30000)); }; socket.onerror function(error) { console.error(WebSocket错误, error); }; } function startHeartbeat() { setInterval(() { if (socket.readyState WebSocket.OPEN) { // 发送Pong帧2字节 const pong new Uint8Array([0x01, 0x02]); socket.send(pong); } }, 90000); // 每90秒发一次 } // 页面加载时连接 window.addEventListener(load, connectWebSocket); /script4.2 性能压测与调优实录代码写完只是开始真正的考验在压测。我们用k6工具模拟了三种场景场景1单设备高频率消息模拟传感器上报并发用户1每秒发送50条消息每条20字节结果CPU稳定在12%内存增长平缓无GC压力。WebSocketSession对象生命周期正常释放。场景2多设备中等频率模拟真实产线并发用户500每秒发送5条消息/设备结果CPU峰值68%内存占用312MB平均延迟83ms。关键指标WebSocket.CloseStatus统计中EndpointUnavailable占比0.02%即每万次连接仅2次熔断符合SLA要求。场景3弱网模拟丢包率5%延迟300ms工具tc命令配置Linux网络规则结果熔断率升至1.8%但重连成功率99.94%。分析日志发现大部分熔断发生在设备刚上线的前10秒——因为客户端Pong响应延迟超过180秒。解决方案将初始熔断阈值从180秒动态调整为300秒待连接稳定后再切回180秒。实操心得压测时一定要监控dotnet-counters的System.Runtime指标。重点关注gc-heap-size堆内存大小和threadpool-queue-length线程池队列长度。如果后者持续100说明I/O操作阻塞了线程池需要检查SendAsync/ReceiveAsync是否用了ConfigureAwait(false)——在.NET 5中WebSocket的异步方法默认不捕获上下文所以无需显式配置这点比.NET Core 3.1更省心。5. 常见问题与排查技巧实录5.1 连接建立阶段的典型问题Q1前端报错Error during WebSocket handshake: Unexpected response code: 200这是最常见问题90%的原因是Nginx配置错误。检查Nginx的location块# ❌ 错误配置缺少Upgrade头透传 location /api/websocket/ { proxy_pass https://backend; } # ✅ 正确配置必须透传Upgrade和Connection头 location /api/websocket/ { proxy_pass https://backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; }Q2服务端日志显示非WebSocket请求被拒绝但前端明确发了WebSocket请求抓包看HTTP请求头。常见原因是前端URL写错了❌wss://api.com/api/websocket少/connect✅wss://api.com/api/websocket/connect必须匹配Controller里的[HttpGet(connect)]另一个原因是HTTPS证书问题。wss://要求证书域名与URL完全一致。如果用自签名证书前端Chrome会拦截需手动访问https://api.com并点击“高级-继续前往”才能生效。5.2 连接维持阶段的问题Q3连接建立后几分钟就自动断开日志无异常这是典型的防火墙或负载均衡器超时设置。云厂商SLB默认空闲超时60秒而我们的KeepAliveInterval设为120秒导致SLB在60秒时主动断开连接。解决方案方案A推荐在Startup.cs中将options.KeepAliveInterval改为TimeSpan.FromSeconds(50)确保小于SLB超时值。方案B联系云厂商将SLB空闲超时调至300秒部分厂商不支持。Q4设备频繁断线重连日志显示ConnectionClosedPrematurely这不是服务端问题而是设备端TCP KeepAlive未开启。在设备固件中必须设置int keepalive 1; int idle 60; // 60秒无数据后开始探测 int interval 10; // 每10秒探测一次 int count 3; // 连续3次失败才断开 setsockopt(sockfd, SOL_SOCKET, SO_KEEPALIVE, keepalive, sizeof(keepalive)); setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPIDLE, idle, sizeof(idle)); setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPINTVL, interval, sizeof(interval)); setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPCNT, count, sizeof(count));5.3 消息收发阶段的疑难杂症Q5服务端能收消息但发给设备的消息设备收不到首先确认设备是否正确处理了WebSocketMessageType.Ping。很多嵌入式WebSocket库如libwebsockets默认不响应Ping需手动调用lws_callback_on_writable(wsi)触发Pong发送。其次检查消息长度.NET 5的SendAsync对单次发送长度有限制默认4MB但设备端缓冲区可能只有2KB。解决方案在SendAsync前分片public async Task SendAsync(byte[] message) { const int maxChunkSize 2048; for (int i 0; i message.Length; i maxChunkSize) { var chunk new ArraySegmentbyte(message, i, Math.Min(maxChunkSize, message.Length - i)); await WebSocket.SendAsync(chunk, WebSocketMessageType.Binary, i maxChunkSize message.Length, CancellationToken.None); } }Q6日志里大量ObjectDisposedException但服务还能用这是WebSocket对象被多次Dispose的典型症状。根源在WebSocketSessionManager.HandleWebSocketAsync里❌ 错误using var webSocket await HttpContext.WebSockets.AcceptWebSocketAsync();✅ 正确去掉using因为WebSocket的生命周期由WebSocketSession管理HandleWebSocketAsync方法结束后webSocket对象必须保持有效。5.4 生产环境避坑清单问题类型现象根本原因解决方案内存泄漏服务运行7天后内存占用从200MB涨到1.2GBConcurrentDictionary中的WebSocketSession未及时移除因CloseAsync未被调用在WebSocketSession.StartAsync()的finally块中强制移除字典项不依赖CloseAsync回调CPU飙高某个设备ID连接后CPU持续95%设备发送畸形消息如长度字段为0xFFFFFFFF导致Array.Copy死循环在MessageRouter.RouteAsync开头添加长度校验if (length 1024*1024) throw new ArgumentException(Message too large);时间不同步设备上报的时间戳比服务端慢3小时设备固件时区未设置UTC时间被当成本地时间解析强制设备固件使用UTC时间服务端不做时区转换所有时间戳存为long毫秒值日志爆炸单日志文件超2GB磁盘写满WebSocketSession的_logger.LogInformation每秒打10次未分级改为_logger.LogDebug生产环境日志级别设为Warning仅错误和熔断事件打Information最后分享一个真实案例某次上线
