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

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

Source: https://hibira.io/zh-cn/blog/go-backend-realtime
Updated: 2026-11-20

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

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

```text
flow: Go 后端用 HTTP 发布；浏览器通过 WebSocket 接收
你的 Go 服务 --HTTP API--> *Hibira|ws.hibira.io --WebSocket--> 浏览器与 App
浏览器与 App --订阅私有频道时--> /pusher/auth|你的 Go 服务
*Hibira --Webhook--> /pusher/webhook|你的 Go 服务
```

## 步骤 1：安装并创建客户端

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

在启动时创建一个客户端，从环境变量读取 App ID、key 和 secret（[创建应用](https://hibira.io/signup)后就能看到），之后传给需要发布事件的 handler 或 service：

```go
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 调用。以订单发货为例：

```go
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 服务提供，所以“谁能看到哪个频道”完全由你的代码决定：

```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` 把三个端点挂上去：

```go
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 服务：

```js
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 签名：

```go
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 集成指南](https://hibira.io/zh-cn/guides/go)里，从应用页面打开时会自动填好你的主机地址。需要推送通知的话，[推送通知指南](https://hibira.io/zh-cn/guides/push-notifications)里有 Go 的示例。想看完整的场景，可以参考[订单追踪](https://hibira.io/zh-cn/use-cases/order-tracking)和[协作与在线状态](https://hibira.io/zh-cn/use-cases/collaboration-presence)。如果你用 Claude Code 或其他 AI 助手写代码，也可以让它通过 [Hibira MCP 服务器](https://hibira.io/zh-cn/mcp-server)获取 Go 的集成指南，直接改好你的项目。
