Python 服務端 SDK Demo 執行指南

這是一個單程序的 Web 聊天示例：瀏覽器訪問 FastAPI 後端，後端用 AsyncDRClient 呼叫 OpenAPI，並由帶簽名的回撥驅動頁面即時更新。 Python SDK 從 PyPI 安裝，Demo 單獨提供原始碼 ZIP；前端是原生 ES 模組，不需要 Node.js，也沒有構建步驟。

下載與準備

下載 Python Demo（1.0.0a2） · 下載 SHA256 校驗檔案

需要 Python 3.11 或以上、可訪問的 IM 服務，以及同一應用的 AppKey、Client ID 和 Client Secret。 用同一應用的兩個賬號互相聊天。賬號可以在控制台建立，也可以用 Demo 的註冊入口建立；用密碼登入要求應用策略允許。

包中的結構：

deeprespond-im-python-demo-1.0.0a2/
├── README.md
├── requirements.txt
├── SHA256SUMS
└── demo/
    ├── __main__.py、main.py、app.py
    ├── 其他后端模块
    └── web/（HTML、CSS、原生 JavaScript 模块）

ZIP 中有 Demo 和依賴清單；SDK、FastAPI、Uvicorn、WebSocket 和上傳解析的依賴由 pip 安裝。 包中沒有 IM 服務端、基礎設施和開發測試工具。

安裝與啟動

解壓後進入 deeprespond-im-python-demo-1.0.0a2，執行：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

export IM_CLIENT_ID='替换为应用的 Client ID'
export IM_CLIENT_SECRET='替换为应用的 Client Secret'
python -m demo \
  --api http://127.0.0.1:18480 \
  --app-key '组织#应用' \
  --client-id "$IM_CLIENT_ID" --client-secret "$IM_CLIENT_SECRET" \
  --addr 127.0.0.1:8091 \
  --callback-credentials '回调地址ID:回调密钥'

開啟 http://127.0.0.1:8091。應用憑據通過命令列引數傳入；上面的環境變數只是為了在終端中替換，Demo 不會自己讀取它們。 Windows 上執行 py -3.11 -m venv .venv，用 .venv\Scripts\Activate.ps1 啟用。在 PowerShell 中把啟動命令合成一行，引數中的環境變數寫作 $env:IM_CLIENT_ID、$env:IM_CLIENT_SECRET。

引數	預設值或說明
--api	http://127.0.0.1:18480，IM 服務地址
--app-key	必填，组织#应用
--client-id / --client-secret	必填，同一應用的服務端憑據
--addr	127.0.0.1:8091，瀏覽器訪問 Demo 的監聽地址
--callback-credentials	地址ID:密钥，多個用逗號分隔；沒有回撥時頁面不會即時更新
--debug	輸出除錯日誌，預設關閉

已經有完整倉庫的，也可以在 sdk/server/python 中執行 python -m pip install -r demo/requirements.txt，再執行 python -m demo。 開發和檢查 SDK 原始碼用 uv 的開發依賴組，見 Demo README。

配置即時回撥

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

回撥地址必須能從 IM 服務訪問。瀏覽器能開啟 Demo，不代表 IM 服務能向它傳送回撥；地址的規則見回撥概述。

訂閱下面的事件，同時設定 filters.message_include_tips=true，建議每批 10 個事件、超時 5000 毫秒：

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

在本機開發需要完整的 IM 倉庫。在倉庫根目錄啟動一個獨立的測試服務（harness）：

make infra-up
go build -o /tmp/harness ./sdk/conformance/harness
/tmp/harness -env .env -addr 127.0.0.1:18580 -control 127.0.0.1:18590 \
  -db im_python_demo_test -redis-prefix python-demo-test:

把 Demo 的 --api 改為 http://127.0.0.1:18580。測試服務的控制介面 GET /env、GET /credentials 返回測試應用的配置，它允許回撥到本機地址。 用控制介面建立和驗證回撥地址的請求格式，見 Demo README。

身份與許可權

身份	用途	儲存在哪裡
應用身份	SDK 用 App Token 管理使用者、好友、群和傳送訊息	後端儲存 Client Secret 和 App Token
使用者的登入身份	使用者以密碼登入後得到的裝置登入，用於讀取使用者能看到的歷史、使用者自己撤回和修改密碼	後端儲存使用者的登入令牌（User Token），不發給瀏覽器
瀏覽器會話	頁面通過 Cookie 訪問 Demo	Cookie 對應 Demo 程序內的會話

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

• 瀏覽器的每個操作，先核對使用者的登入身份；群操作每次都重新讀取成員和角色。
• 讀取歷史時按使用者過濾（各自刪除、清空的訊息，入群前、退群后的訊息）；服務端 SDK 讀到的是管理視角的全部歷史，不能直接給使用者看。
• 退出登入時吊銷真實的裝置登入；修改密碼時在同一步中校驗舊密碼並更換令牌，保留當前裝置的登入。
• 收到編輯和撤回的回撥後，重新從服務端讀取訊息；回撥重發不會讓使用者已經刪除的訊息重新出現。
• 附件只有按檔案內容識別為 PNG、JPEG、GIF、WebP 的直接顯示，其他一律作為下載，並設定 nosniff、沙箱 CSP 和禁止快取。

業務中的許可權檢查和附件轉發的要求見呼叫介面。

功能與結構

演示註冊登入、單聊和群聊、文本/圖片/檔案、引用回覆、翻看歷史、已讀、撤回、各自刪除和清空、好友和黑名單、群管理、資料和裝置管理。 “正在輸入”只在 Demo 程序內轉發；表情回應、置頂、接受或拒絕好友申請和群邀請等只有客戶端才有的功能，介面中會提示。

檔案	職責
main.py、__main__.py	解析引數、建立 SDK 客戶端和啟動
app.py	HTTP、WebSocket、靜態資源和附件
state.py、views.py	狀態和返回給頁面的資料
actions.py、data.py、client_api.py	頁面操作、許可權和以使用者身份呼叫的介面
callbacks.py、bridge.py	處理回撥、推送給瀏覽器、清理會話
web/	原生頁面模組，沒有構建步驟

每個原始碼檔案不超過 500 行，結構測試會檢查檔案行數和模組之間的依賴。會話、令牌和快取都在程序記憶體中，重啟後要重新登入。 兩個賬號請用不同的瀏覽器或無痕視窗；Python 和 Go 的 Demo 都使用 demo_sid Cookie，Cookie 不按埠區分。

排查與迴歸

現象	檢查
No module named demo	是否在解壓後的根目錄執行，demo/__main__.py 是否存在
缺少執行依賴	啟用虛擬環境，重新安裝包中的 requirements.txt
提示缺少應用憑據	是否顯式傳入了對應的引數；Demo 不會自己讀取環境變數
登入失敗	IM 地址、應用、賬號密碼，以及是否允許密碼登入
回撥地址驗證失敗	Demo 是否已經啟動，IM 服務能否訪問回撥地址，地址 ID 和金鑰是否匹配
能傳送，但頁面不即時更新	地址是否已驗證，事件是否已訂閱，簽名金鑰是否正確
兩個視窗的登入互相覆蓋	改用不同的瀏覽器或無痕視窗；不同埠不區分 Cookie
重啟後要重新登入	狀態只在程序記憶體中，重新登入即可

執行 Demo ZIP 不需要 pytest、Playwright 或 SDK 的開發工具。 SDK 的檢查、連真實服務的安全迴歸測試和截圖端到端測試在完整倉庫中執行，命令和隔離要求見 Demo README。