← 博客

用 Go 后端做实时功能:不必自己运维 WebSocket 服务器

· Hibira

用官方的 pusher-http-go 从 Go 发布实时事件、授权私有与 presence 频道、验证 webhook,浏览器则连接到 Hibira。

Go 很适合写 WebSocket 服务器,所以很多团队的第一个念头是自己来:开一个 hub、用 goroutine 管理每条连接、收到事件就广播出去。一台机器的时候这样很顺。等到要跑两台以上、要做 presence(谁在线)、要处理断线重连和部署时的连接迁移,WebSocket 就从一个功能变成一套需要运维的系统。

另一种做法是让 Go 后端只负责“决定要发什么”,把“维持几万条连接”交给托管服务。Hibira 使用 Pusher Channels 协议,所以你可以直接用 Pusher 官方的 Go 库 pusher-http-go,前端用 pusher-js。这篇文章走过五件事:创建客户端、发布事件、私有与 presence 频道的授权、前端连接,以及接收 webhook。

你的 Go 服务
HTTP API
Hibiraws.hibira.io
WebSocket
浏览器与 App
浏览器与 App
订阅私有频道时
/pusher/auth你的 Go 服务
Hibira
Webhook
/pusher/webhook你的 Go 服务
Go 后端用 HTTP 发布;浏览器通过 WebSocket 接收

步骤 1:安装并创建客户端

go get github.com/pusher/pusher-http-go/v5

在启动时创建一个客户端,从环境变量读取 App ID、key 和 secret(创建应用后就能看到),之后传给需要发布事件的 handler 或 service:

import pusher "github.com/pusher/pusher-http-go/v5"

func newRealtime() *pusher.Client {
	return &pusher.Client{
		AppID:  os.Getenv("HIBIRA_APP_ID"),
		Key:    os.Getenv("HIBIRA_APP_KEY"),
		Secret: os.Getenv("HIBIRA_APP_SECRET"),
		Host:   "ws.hibira.io",
		Secure: true,
		// 在启动时就设好,不要让库在第一次请求时才创建
		HTTPClient: &http.Client{Timeout: 3 * time.Second},
	}
}

HTTPClient 这一行值得特别说明。没有设置时,pusher-http-go 会在第一次发出请求时才创建一个默认 5 秒超时的 http.Client,并写回客户端对象。如果多个 goroutine 同时第一次发布,这就是一个数据竞争,go test -race 会检测到。启动时自己设好,顺便把超时调成适合你服务的值。

步骤 2:发布事件

发布就是一次 HTTP 调用。以订单发货为例:

func shipOrder(rt *pusher.Client, w http.ResponseWriter, r *http.Request) {
	order := Order{ID: 1024, Status: "shipped"}
	// … 先把订单状态写入数据库 …

	socketID := r.Header.Get("X-Socket-ID") // 前端发来的,可以为空
	if err := rt.TriggerExclusive("private-user-42", "order-updated", order, socketID); err != nil {
		log.Printf("realtime: %v", err) // 发布失败不影响订单本身
	}
	json.NewEncoder(w).Encode(order)
}

几条实践建议:

  • 先写数据库,再发布。 实时事件是通知,不是数据源。客户端重连后应该重新读一次 API,而不是依赖可能没收到的事件。
  • 排除发起者。 TriggerExclusive 带上前端的 socket ID,发起这个操作的标签页就不会再收到一次自己的更新。只需要对所有人广播时,用 Trigger 就好。
  • 一次发多个。 同一个请求要更新多个频道时,用 TriggerMulti(同一个事件发到多个频道)或 TriggerBatch(不同事件),减少往返次数。
  • 不要阻塞请求。 发布在延迟敏感的路径上时,可以交给后台 goroutine 或任务队列处理,但要记得处理错误和服务关闭时的收尾。

安全提醒: X-Socket-ID 只能用于避免事件回送到发起操作的页面,不能当作调用者的身份凭据。频道授权应以服务端验证过的 Session 或 JWT 为准,并校验表单格式与请求大小,避免静默截断数据。

步骤 3:私有与 presence 频道的授权

以 private- 和 presence- 开头的频道,在订阅前会向你的服务器要一个签名。这个端点由你的 Go 服务提供,所以“谁能看到哪个频道”完全由你的代码决定:

func pusherAuth(rt *pusher.Client) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		user, ok := currentUser(r) // 你自己的 session 或 JWT 验证
		if !ok {
			http.Error(w, "unauthorized", http.StatusUnauthorized)
			return
		}
		body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 4096))
		if err != nil {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}
		form, err := url.ParseQuery(string(body))
		if err != nil {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}
		channel := form.Get("channel_name")
		if (!strings.HasPrefix(channel, "private-") && !strings.HasPrefix(channel, "presence-")) || !user.CanJoin(channel) {
			http.Error(w, "forbidden", http.StatusForbidden)
			return
		}

		var resp []byte
		if strings.HasPrefix(channel, "presence-") {
			resp, err = rt.AuthorizePresenceChannel(body, pusher.MemberData{
				UserID:   user.ID,
				UserInfo: map[string]string{"name": user.Name},
			})
		} else {
			resp, err = rt.AuthorizePrivateChannel(body)
		}
		if err != nil {
			http.Error(w, "forbidden", http.StatusForbidden)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		w.Write(resp)
	}
}

库只负责签名,不会检查用户有没有权限,所以 CanJoin 这一步一定要自己写。常见的错误是只检查“有没有登录”,结果任何登录的用户都能订阅 private-user-42。presence 频道的 UserInfo 会发给频道里的每个成员,只放可以公开的信息。

用 Go 1.22 之后的 http.ServeMux 把三个端点挂上去:

rt := newRealtime()
mux := http.NewServeMux()
mux.HandleFunc("POST /orders/{id}/ship", func(w http.ResponseWriter, r *http.Request) { shipOrder(rt, w, r) })
mux.HandleFunc("POST /pusher/auth", pusherAuth(rt))
mux.HandleFunc("POST /pusher/webhook", pusherWebhook(rt))
log.Fatal(http.ListenAndServe(":8080", mux))

步骤 4:前端连接

前端用 pusher-js,把主机指向 Hibira,授权端点指向你的 Go 服务:

import Pusher from 'pusher-js';

const pusher = new Pusher('your-app-key', {
  cluster: 'hkg',
  wsHost: 'ws.hibira.io',
  wsPort: 443,
  wssPort: 443,
  forceTLS: true,
  enabledTransports: ['ws', 'wss'],
  channelAuthorization: { endpoint: '/pusher/auth', transport: 'ajax' },
});

pusher.subscribe('private-user-42').bind('order-updated', (order) => {
  renderOrder(order);
});

// 调用自己的 API 时带上 socket ID,让服务器排除这个标签页
await fetch('/orders/1024/ship', {
  method: 'POST',
  headers: { 'X-Socket-ID': pusher.connection.socket_id },
});

授权请求会带上浏览器的 cookie,所以如果前端和 Go 服务在同一个域名下,现有的 session 就能直接用。用 JWT 的话,在 channelAuthorization.headers 里加上 Authorization 头。移动 App 也一样,PusherSwift 和 pusher-java-client 都能设置主机和授权端点。

步骤 5:接收 webhook

想知道“频道什么时候开始有人”“谁加入或离开了 presence 频道”,可以在应用页面设置 webhook 地址。pusher-http-go 会帮你验证 X-Pusher-Key 和 HMAC 签名:

func pusherWebhook(rt *pusher.Client) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
		if err != nil {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}
		hook, err := rt.Webhook(r.Header, body) // 验证 X-Pusher-Key 与签名
		if err != nil {
			http.Error(w, "invalid signature", http.StatusUnauthorized)
			return
		}
		for _, e := range hook.Events {
			switch e.Name {
			case "member_added":
				markOnline(e.UserID)
			case "member_removed":
				markOffline(e.UserID)
			}
		}
		w.WriteHeader(http.StatusOK)
	}
}

Webhook 会把一小段时间内的事件合并成一个请求发出。如果你的端点没有返回 2xx,Hibira 会重试最多五分钟,所以处理要幂等:同一个 member_added 收到两次,结果应该一样。处理很慢的话,先返回 200,再交给后台任务。

上线前检查

  • 用 go test -race 跑过会发布事件的代码。
  • 私有频道的授权检查了“这个用户能不能看这个频道”,而不只是“有没有登录”。
  • App secret 只放在环境变量或密钥管理服务里,不进版本控制,也不出现在前端。
  • 在应用页面的调试控制台确认发布的事件、订阅和 webhook 都有出现。

Go 的基本配置也在 Go 集成指南里,从应用页面打开时会自动填好你的主机地址。需要推送通知的话,推送通知指南里有 Go 的示例。想看完整的场景,可以参考订单追踪和协作与在线状态。如果你用 Claude Code 或其他 AI 助手写代码,也可以让它通过 Hibira MCP 服务器获取 Go 的集成指南,直接改好你的项目。