← 部落格

用 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 的整合指南,直接改好你的專案。