Buffalo 的 WebSocket 路由必须跳过中间件直连 handler，因中间件会提前写响应头破坏握手；需在 routes.go 中置于所有 app.Use() 之后、常规路由之前，handler 内直接调用 upgrader.Upgrade，禁用 Buffalo Context 相关操作，并显式配置 CheckOrigin、Subprotocols 等参数。
Buffalo 路由必须跳过中间件直连 handler
Buffalo 的 app.GET("/ws", websocketHandler) 看似正常，但若该路由经过 app.Use() 链（比如日志、CORS、gzip 中间件），gorilla/websocket.Upgrader.Upgrade() 会静默失败——浏览器只报 WebSocket connection to 'ws://' failed，无任何错误细节。这是因为 WebSocket 升级要求响应头**一字不差**：Upgrade: websocket、Connection: Upgrade 和正确的 Sec-WebSocket-Accept；而任意中间件提前调用 WriteHeader() 或写入 body，就会锁定 header，破坏协议握手。
实操建议：
- 在
routes.go中注册路由时，确保它出现在所有app.Use(...)调用之后、所有app.GET/POST常规路由之前（或至少不被包裹） - handler 内部必须直接调用
upgrader.Upgrade(c.Response().Writer, c.Request(), nil)，禁止使用c.Response().WriteHeader()或c.Render() - 不要试图在 handler 里做
c.Set("key", val)或其他上下文操作——buffalo.Context包装的ResponseWriter不适配 WebSocket 升级流程
Upgrader 必须显式配置 CheckOrigin 和 Subprotocols
默认零值的 websocket.Upgrader 在生产环境大概率失效：Cloudflare 等 CDN 会静默丢弃无 Sec-WebSocket-Protocol 头的请求；未校验 Origin 则可能被扫描工具耗尽连接数。
实操建议：
-
CheckOrigin必须是白名单函数，例如：func(r *http.Request) bool { return r.Header.Get("Origin") == "https://your-frontend.com" }，禁用return true -
Subprotocols显式传入，如[]string{"chat-v1"}；客户端需匹配，否则握手被拒绝 -
ReadBufferSize和WriteBufferSize设为65536，避免 burst 消息触发频繁小内存分配 - 启用压缩：
EnableCompression: true，但仅对文本消息生效，且需客户端支持permessage-deflate
每个连接必须启动独立 writePump goroutine
*websocket.Conn 不是线程安全的。如果广播逻辑、心跳 goroutine 和消息接收协程同时调 conn.WriteMessage()，大概率触发 write tcp: use of closed network connection 或消息错发。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
实操建议：
- 在 upgrade 成功后，立即启动一个专属
writePumpgoroutine，从chan []byte（或chan Message）读取消息并串行调用conn.WriteMessage() - channel 缓冲区大小设为
16–64：太小易阻塞发送方，太大则堆内存压力陡增 - 务必在连接关闭时 close channel 并等待
writePump退出，否则 goroutine 泄漏
WebSocket 跨域不能靠 Buffalo CORS 中间件
Buffalo 自带的 middleware.CORS 对 /ws 路由完全无效——因为 Upgrader.Upgrade() 绕过整个中间件链。你在 app.Use() 里写的 Access-Control-Allow-Origin，根本不会出现在 WebSocket 握手响应里。
实操建议：
- 跨域控制全靠
Upgrader.CheckOrigin回调，它在握手前被调用，返回false则直接拒连 - 若需支持凭据（
credentials: true），CheckOrigin必须严格比对 Origin，且不能返回通配符* - 某些 CDN（如 Cloudflare）会缓存预检响应，记得在握手成功后手动加
Vary: Origin头，否则不同源请求可能拿到错误缓存
真正卡住人的地方，往往不是代码写不出来，而是没意识到 Buffalo 的 Context 和 ResponseWriter 在 WebSocket 场景下是“假朋友”——它们的存在本身就会破坏协议。升级连接这一步，必须彻底脱离 Buffalo 的抽象层，回归原生 http.ResponseWriter 和 http.Request。
