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。