Go 服務端 SDK Demo 執行指南

這是一個用 drim.Client 寫的單程序 Web 聊天示例：Go 後端呼叫服務端 SDK，接收帶簽名的回撥，再通過 WebSocket 推送給頁面。前端是內嵌的原生 ES 模組，不需要 Node.js、前端構建工具或額外的 Go 依賴。

與客戶端 Demo 的區別

專案	本頁的服務端 Demo	客戶端 Demo
原始碼目錄	`demo/`	`demo/`
SDK 包名	`drim`	`im`
Go 版本	1.23 或以上	1.26.5 或以上
應用配置	IM 地址、AppKey、Client ID 和 Client Secret	IM 地址和 AppKey
使用者身份	使用者的登入令牌（User Token）由 Demo 後端代為儲存	每個瀏覽器會話持有一個使用者客戶端
即時更新	IM 發來的簽名回撥經 Demo 校驗後推給瀏覽器	使用者的長連線 → Demo → 瀏覽器
預設埠	`127.0.0.1:8092`	`:8090`

服務端 SDK 負責使用者、好友、群和訊息等管理操作。使用者看到的聊天記錄、使用者自己撤回訊息和修改密碼，由 Demo 以使用者的身份呼叫客戶端介面完成，不屬於服務端 SDK 的公開 API。兩個 Demo 都使用名為 demo_sid 的 Cookie，Cookie 不按埠區分，所以同時體驗時請使用不同的瀏覽器或無痕視窗。

準備

下載服務端 SDK + Demo ZIP，校驗後完整解壓。從解壓後的模組根目錄啟動；使用完整的 IM 倉庫時先進入 sdk/server/go。
準備可訪問的 IM 服務地址，以及同一應用的 AppKey、Client ID 和 Client Secret。
在這個應用中建立兩個測試賬號，或使用 Demo 的註冊入口；用密碼登入要求應用策略允許。
配置下面的即時回撥。沒有回撥時也能開啟頁面、呼叫介面，但對方的訊息不會即時出現。

需要在本機執行 IM 測試服務時，使用完整的 IM 倉庫（SDK 壓縮包中沒有服務端和基礎設施），在倉庫根目錄啟動測試服務（harness）：

bash

make infra-up
go build -o /tmp/im-harness ./sdk/conformance/harness
/tmp/im-harness -env .env -addr 127.0.0.1:18880 -control 127.0.0.1:18890 \
  -db im_go_demo_test -redis-prefix go-demo-test:

測試服務的 GET /env 和 GET /credentials 返回這次建立的應用配置，它的控制介面只用於本機開發。連線已部署的 IM 時，直接使用控制台中的應用配置，不需要啟動測試服務。

啟動

下載服務端 SDK + Demo ZIP · SHA256 校驗檔案

解壓後進入 deeprespond-im-server-go-sdk-1.0.3，設定應用的憑據，在這個目錄中執行：

bash

export IM_CLIENT_ID='替换为应用的 Client ID'
export IM_CLIENT_SECRET='替换为应用的 Client Secret'
go run ./demo \
  --api http://127.0.0.1:18880 \
  --app-key '组织#应用' \
  --addr 127.0.0.1:8092 \
  --callback-credentials '地址ID:回调密钥'

開啟 http://127.0.0.1:8092，用同一應用的賬號登入；在另一個瀏覽器（或無痕視窗）中登入第二個賬號。在 SDK 模組目錄執行 go build -o im-go-server-demo ./demo 可以生成內嵌頁面的二進位制，用同樣的引數執行；Windows 上輸出名用 im-go-server-demo.exe。

引數	預設值或環境變數	說明
`--api`	`http://127.0.0.1:18480`	IM 服務地址；使用上面的本機測試服務時改為 18880 埠
`--app-key`	`APP_KEY`	`组织#应用`
`--client-id`	`IM_CLIENT_ID`	應用的 Client ID
`--client-secret`	`IM_CLIENT_SECRET`	同一應用的 Client Secret
`--addr`	`127.0.0.1:8092`	瀏覽器訪問 Demo 的監聽地址
`--callback-credentials`	無	`地址ID:密钥`，多個用逗號分隔
`--debug`	關閉	輸出 SDK 的除錯日誌

配置即時回撥

按順序建立、啟動、驗證，以免 Demo 還沒有開始監聽時驗證失敗：

在控制台中為應用建立回撥地址，指向 Demo 的 /im/callback，儲存地址 ID 和金鑰。
把地址 ID 和金鑰填入 --callback-credentials，啟動 Demo。簽名校驗和 URL 驗證由 SDK 處理。
在控制台中驗證地址，驗證成功後開啟事件訂閱。

需要訂閱的事件：

text

message.sent, message.recalled, message.edited
friend.added, friend.removed, friend.updated, friend_request.received, blacklist.changed
group.created, group.info_changed, group.dismissed
group.members_added, group.members_removed, group.members_updated
user.profile_changed, user.sessions_revoked, user.relogin_required, presence.changed

同時開啟 filters.message_include_tips=true，建議每批 10 個事件、超時 5000 毫秒。本機測試服務允許回撥到 http://127.0.0.1:8092/im/callback；其他環境要使用 IM 服務能訪問到的地址，規則見回撥地址的配置。回撥由 IM 服務發起，瀏覽器能開啟 Demo 不代表 IM 服務能訪問它。用本機測試服務的控制介面建立和驗證地址的請求格式，見 Demo README。

驗證與能力邊界

用兩個賬號登入後，依次試單聊、群聊、文本/圖片/檔案、引用回覆、翻看歷史、已讀、刪除和清空、撤回、資料變化、吊銷裝置和退出登入。

Demo 在後端做了下面這些檢查，你的業務也需要：

頁面上的每個操作，先核對使用者真實的登入會話；群成員和管理員角色每次都從服務端重新讀取。
使用者看到的聊天記錄要按使用者過濾（各自刪除、清空的訊息，入群前、退群后的訊息）；服務端 SDK 讀到的是管理視角的全部記錄，不能直接給使用者看。
使用者撤回訊息時檢查傳送者、角色和撤回時限；修改密碼時校驗舊密碼，並保留當前裝置的登入。
退出登入時吊銷真實的裝置登入；之前的吊銷回撥不會結束之後新建立的登入。
附件只有按檔案內容識別為 PNG、JPEG、GIF、WebP 的直接顯示，其他一律作為下載，並設定 nosniff、沙箱 CSP 和禁止快取。

“正在輸入”只在 Demo 程序內轉發；會話和快取儲存在記憶體中，重啟後要重新登入。表情回應、會話置頂、接受或拒絕好友申請和群邀請不在服務端 OpenAPI 中，介面中會提示；需要這些功能時使用客戶端 SDK。業務中的許可權檢查和附件轉發的要求見呼叫介面。

檔案組織

模組	職責
`main.go`、`http.go`、`media.go`	啟動、路由、註冊登入和附件
`bridge.go`、`wsbridge.go`	瀏覽器連線和 WebSocket 訊息
`state.go`、`views.go`	狀態和返回給頁面的資料
`device.go`、`data.go`	以使用者身份呼叫的介面、列表和許可權
`actions*.go`、`messages.go`	分派頁面操作、業務操作和發訊息
`callbacks.go`、`push.go`、`sessions.go`、`message_events.go`	處理回撥、推送給頁面、清理會話
`web/`、`*_test.go`、`testdata/`	頁面模組；單元測試、併發測試和截圖端到端測試

每個原始碼檔案不超過 500 行；共享狀態用互斥鎖保護，網路呼叫在鎖外執行。Demo 的結構測試會檢查這些規則。

測試與排查

壓縮包中的 SDK 和 Demo 單元測試可以直接執行：

bash

go test ./...

下面的生成檢查、真實整合測試和端到端測試需要完整的 IM 倉庫和單獨的測試應用，在倉庫根目錄執行：

bash

make sdk-server-go-test
IM_TEST_HARNESS=http://127.0.0.1:18890 make sdk-server-go-integration

安全迴歸測試和截圖指令碼的環境變數與執行方式見 Demo README。安全迴歸測試會弔銷測試應用中已有的登入，請不要和瀏覽器端到端測試同時執行。

現象	檢查
提示缺少應用憑據	引數或環境變數是否齊全，是否和 AppKey 屬於同一個應用
登入失敗	賬號、密碼、應用的狀態，以及是否允許密碼登入
回撥地址驗證失敗	`/im/callback` 能否從 IM 服務訪問，地址 ID、金鑰和反向代理的路徑是否正確
能傳送，但對方的頁面不更新	地址是否已經驗證，事件是否已訂閱，金鑰是否正確
兩個瀏覽器視窗的登入互相覆蓋	改用不同的瀏覽器或無痕視窗；Cookie 不按埠區分
重啟後要重新登入	這個示例的狀態只在記憶體中，重新登入即可

Go 服務端 SDK Demo 執行指南 ​

與客戶端 Demo 的區別 ​

準備 ​

啟動 ​

配置即時回撥 ​

驗證與能力邊界 ​

檔案組織 ​

測試與排查 ​

Go 服務端 SDK Demo 執行指南

與客戶端 Demo 的區別

準備

啟動

配置即時回撥

驗證與能力邊界

檔案組織

測試與排查