# 用 Go 後端做即時功能：不必自己維運 WebSocket 伺服器

> 用官方的 pusher-http-go 從 Go 發布即時事件、授權私人與 presence 頻道、驗證 webhook，瀏覽器則連到 Hibira。

Source: https://hibira.io/zh-tw/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-tw/guides/go)，打開應用程式頁面時會自動填好你的主機位址。需要推播通知的話，[推播通知指南](https://hibira.io/zh-tw/guides/push-notifications)有 Go 的範例。想看完整的情境，可以參考[訂單追蹤](https://hibira.io/zh-tw/use-cases/order-tracking)和[協作與線上狀態](https://hibira.io/zh-tw/use-cases/collaboration-presence)。如果你用 Claude Code 或其他 AI 助理寫程式，也可以讓它透過 [Hibira MCP 伺服器](https://hibira.io/zh-tw/mcp-server)取得 Go 的整合指南，直接改好你的專案。
