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，破坏协议握手。

实操建议：

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

• 在 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 或消息错发。

实操建议：

• 在 upgrade 成功后，立即启动一个专属 writePump goroutine，从 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。