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