Python 服务端 SDK Demo 运行指南

单进程 Web 聊天示例：浏览器访问 FastAPI 后端，后端使用 AsyncDRClient 调用 OpenAPI，并通过签名回调驱动页面实时更新。 Python SDK 从 PyPI 安装，Demo 单独提供源码 ZIP；前端为原生 ES 模块，无需 Node.js 或构建步骤。

下载与准备

下载 Python Demo（1.0.0a0） · 下载 SHA256 校验文件

需要 Python 3.11 或以上、可访问的 IM 服务、AppKey 和同一应用的 Client ID / Client Secret。用同一应用下的两个账号体验互聊，账号可在控制台创建或通过 Demo 注册入口创建，密码登录需要符合应用策略。

包内结构：

text

deeprespond-im-python-demo-1.0.0a0/
├── 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.0a0，执行：

bash

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`	`endpoint_id:secret`，多个用逗号分隔；无回调时没有实时推送
`--debug`	打印调试日志，默认关闭

已有完整仓库时，也可在 sdk/server/python 执行 python -m pip install -r demo/requirements.txt，再运行 python -m demo。 SDK 源码开发与检查使用 uv 的开发依赖组，详见 Demo README。

配置实时回调

在应用控制台创建回调地址，指向 Demo 的 /im/callback，保存地址 ID 和密钥。
将 ID 和密钥填入 --callback-credentials，启动 Demo。
在控制台验证地址，确认成功并启用事件订阅。签名及 URL 验证由 SDK 回调处理器完成。

回调地址必须能从 IM 服务访问。浏览器能访问 Demo 不代表 IM 服务能向它发送回调；地址规则见回调概述。

订阅以下事件，同时设置 filters.message_include_tips=true，推荐批量大小 10、超时 5000 毫秒：

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

本机开发需要完整 IM 仓库。在仓库根目录启动独立测试应用：

bash

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 提供测试应用配置；harness 允许本机回调。通过控制接口创建、验证回调的请求结构见 Demo README。

身份与权限

身份	用途	保存位置
应用身份	SDK 使用 App Token 管理用户、好友、群和发送消息	后端保存 Client Secret 与 App Token
真实设备身份	密码登录产生设备会话，用于用户可见历史、用户撤回和本人改密	后端保存设备 User Token，不发送给浏览器
浏览器会话	页面通过 Cookie 访问本 Demo	Cookie 对应后端进程内会话

每个浏览器动作先验证设备身份；群操作重新读取成员和角色。历史读取应用逐用户删除、清空和入退群边界，管理 SDK 的全量历史不能直接填入用户界面。退出登录吊销真实设备；本人改密原子校验旧密码并轮换令牌，保留当前设备。编辑与撤回回调重新读取权威消息，回调重试不会恢复用户已删除的消息。

文件代理只内联按字节识别的 PNG/JPEG/GIF/WebP，其余强制下载，并设置 nosniff、沙箱 CSP 和禁止缓存。具体业务授权和附件代理要求见调用接口。

功能与结构

演示注册登录、单聊和群聊、文本/图片/文件、引用回复、历史翻页、已读、撤回、逐用户删除与清空、好友与黑名单、群管理、资料和设备管理。正在输入只在本进程内转发；回应、置顶、好友申请及群邀请的接受/拒绝等客户端专属能力会显示明确提示。

文件	职责
`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 检查、真实服务安全回归和双视口截图 E2E 在完整仓库中执行，命令及隔离要求见 Demo README。

Python 服务端 SDK Demo 运行指南 ​

下载与准备 ​

安装与启动 ​

配置实时回调 ​

身份与权限 ​

功能与结构 ​

排查与回归 ​