Beego WebSocket需用beego.WebSocket()注册路由、Get()方法处理、配置alloworigin放行跨域,读写仅通过this.Ctx.Input.Conn,连接池须用sync.Map管理。

Beego 的 WebSocket 不是“加个库就能用”的功能,它依赖框架内置的协议升级中间件和特定路由注册方式;直接套用 gorilla/websocket 的 Upgrade 会触发 http: response.WriteHeader on hijacked connection panic,且默认开启 Origin 校验,本地调试连不上基本就是这个原因。
路由必须用 beego.WebSocket(),不能用 beego.Router()
Beego 对 WebSocket 请求的处理逻辑封装在独立的中间件中,只有通过 beego.WebSocket() 注册的路径才会注入该中间件。若误用 Router(),请求会走普通 HTTP 流程,Upgrade 调用必然失败。
-
beego.WebSocket("/ws", &Wshandler{})✅ 正确:框架识别路径并启用 WebSocket 协议支持 -
beego.Router("/ws", &Wshandler{})❌ 错误:后续调用this.Ctx.Input.Conn为 nil,或触发 hijacked 连接写入错误 - 控制器方法名必须是
Get()(Beego 2.x),其他方法如Post()不会被路由匹配
app.conf 必须配置 websocket.alloworigin
Beego 1.12+ 默认校验请求头中的 Origin,浏览器发起 new WebSocket("ws://localhost:8080/ws") 时自动带上 Origin: http://localhost:8080,但后端未放行就会返回 403 或静默断连。
可水平扩展的 WebSocket 中心模式,支持懒加载 Redis 订阅、连接注册表和优雅关闭。适用于构建可跨多实例扩展的实时 WebSocket 服务器。
- 开发阶段可设为
websocket.alloworigin = *,快速验证逻辑 - 生产环境必须指定域名,例如
websocket.alloworigin = https://myapp.com或http://admin.myapp.com - 若前端跑在
file://或测试工具(如 wscat)发起连接,Origin可能为空,需额外判断,Beego 不支持空 Origin 白名单,此时建议临时改配置或加代理层透传
消息读写只能操作 this.Ctx.Input.Conn,不能调用 Render 或 ServeJSON
WebSocket 连接建立后,HTTP 响应通道已被“劫持”,this.Ctx.ResponseWriter 失效;此时再调用 this.ServeJSON()、this.TplName 或任何涉及 WriteHeader 的方法都会 panic。
- 读消息:用
conn.ReadJSON(&v)或conn.ReadMessage(),其中conn = this.Ctx.Input.Conn - 写消息:统一用
conn.WriteJSON(v),不要尝试this.Data["json"] = v+this.ServeJSON() - 务必检查
conn != nil:它只在Get()方法中 Upgrade 成功后才被赋值,在Prepare()或其他生命周期钩子中访问会 panic - 连接关闭后
conn不自动置 nil,判断是否断开应捕获io.EOF或检查conn.RemoteAddr() == nil
广播需手动维护连接池,sync.Map 是唯一安全选择
Beego 不提供全局连接管理,多个客户端间广播必须自己存、删、遍历连接。用普通 map 并发读写会 crash,而 defer 清理不保证执行时机——Finish() 才是连接真正关闭后的可靠回调点。
- 存储结构推荐:
var connMap = sync.Map{} // key: string(sessionID), value: *websocket.Conn - 注册连接:在
Get()中生成 sessionID(如this.Ctx.Input.Session.Get("uid")),然后connMap.Store(sessionID, conn) - 清理连接:在控制器的
Finish()方法里调用connMap.Delete(sessionID),不是defer - 广播时遍历:
connMap.Range(func(key, value interface{}) bool { conn := value.(*websocket.Conn); conn.WriteJSON(msg) });,注意每个WriteJSON都要单独 recover 异常,避免一个失败中断全部推送
最易忽略的一点:Beego 的 Conn 是对 gorilla/websocket.Conn 的封装,但它的 WriteJSON 和 ReadJSON 底层仍依赖 gorilla 的序列化逻辑,若传入含 channel、func 或 unexported 字段的 struct,会静默失败或 panic —— 广播前务必用 json.Marshal 预检数据结构。

















