开源 IM 框架 · 自己部署 · Apache-2.0

自己部署的即时通讯，每一帧都经得起比对

Talkwire 由一个 Go 实时服务端、Android 与 Web 客户端 SDK 和一份线协议组成。你的业务后端只实现身份、好友、资料、推送和媒体几个接口，就能得到单聊、群聊、媒体消息、已读回执、撤回、多端在线与离线推送。

开始接入在线试用阅读开发手册

github.com/dishikun2786-prog/Talkwire

wss://im.example.com/ws/im已连接

→{"id":"1","action":"login","token":"eyJ…","device":"web-a1"}
←{"id":"1","action":"login","code":200,"uid":"uid_mF3xQ…","protocol":1,"capabilities":["errcode","reply-id","multi-device","sync-summary"]}
→{"id":"2","action":"sync_summary"}
←{"id":"2","action":"sync_summary","code":200,"topics":[{"topic":"grp_k8sQ…","lastSeq":43,"isGroup":true}]}
→{"id":"3","action":"get","topic":"grp_k8sQ…","afterSeq":40}
←{"id":"3","action":"get","code":200,"messages":[{"seq":41,…},{"seq":43,…}]} // 42 已撤回：记下，不再重拉
←{"action":"data","topic":"grp_k8sQ…","from":"uid_Q2b7…","seq":44,"content":"今晚八点发版"}

33 个黄金对话

服务端的每次改动都与参照实现逐帧比对，一帧不同就不合入。

两个协议档位

legacy 与原版客户端逐帧兼容；strict 修正已知缺陷并加上错误码。

32 条红线

丢消息、串号、越权这类事故，每条都对应到用例。

Apache-2.0

核心宽松许可；端到端加密模块采用 AGPLv3，单独发布。

架构

一个服务端，两端 SDK，一组由你实现的宿主接口

用户、好友和资料留在你自己的业务库里。Talkwire 服务端只管连接、消息与离线队列，需要业务数据时回调你的后端；你的后端也可以经内部接口推一张卡片、结束一通电话。

客户端 SDKAndroid · WebiOS 规划中
WebSocket
Talkwire 服务端Go · 线协议 v1legacy / strict 两档 · 多端在线 · 离线队列 · FCM / APNs / Web Push · 数据存 PostgreSQL
宿主接口　内部接口
宿主 · 你的业务后端身份与令牌 · 好友与资料推送文案与媒体 · 通话鉴权与计费

架构与概念宿主接口契约协议概述

能力

聊天应用要的，核心里都有

单聊与群聊
群主、管理员、成员三种角色；邀请、移除、转让与解散。角色以服务端名册为准，拉不到时按普通成员处理。
图片、视频、语音、文件
客户端传到你的存储，消息里只带地址。气泡按内容类型选，不看正文里的文字。
撤回与清空
撤回留下一条墓碑，看得到谁在何时撤回；清空对所有成员生效，离线的成员上线后照样生效。
已读与正在输入
单聊已读位置、可关闭的群已读回执、正在输入。换一台新设备，看过的消息不会重新算成未读。
多端同时在线
一个账号默认最多 10 台设备同时在线。在一台设备上发的消息，在其他设备上像收到的一样出现。
离线推送
FCM、APNs 与 Web Push，按设备登记令牌；通知文案由宿主决定。
在线状态三态
在线、离线、未知，记录会过期。拿不准的时候显示“未知”，不冒充“离线”。
浏览器多标签共用连接
同一账号的多个标签页共用一条 WebSocket；持有连接的标签关掉，其他标签自动接管。
可嵌入的后台页面
聊天记录、通话记录与通话详情；清空只给超级管理员，要写理由并逐字输入确认语。

可靠性

不丢、不乱、不重

这三件事在小桃子的线上系统里都出过事故。Talkwire 把每一次的修法写进协议规范，再用用例钉住。

发送：同一条只存一次
每条消息带 clientMsgId。回执丢了就保持“发送中”，重连后用同一个 id 再发，服务端认出来，只存一次。
红线 C2
补拉：从连续段末尾开始
4041424344
漏掉的从缺口补；离线时被撤回、本机没收过的 42 也记下，不会每次重连都从那里重拉。strict 档一次请求就知道哪些会话变了。
红线 C3 · 协议第 8.1、8.2 节
迁移：旧客户端不用改
legacy 档与原版服务逐帧一致，已经发出去的客户端照常工作；新客户端换到 strict 档，拿到错误码、请求关联和 8 处缺陷修正。
协议第 0.3、18 节

快速开始

接入只有四步

起服务端，实现宿主接口，再把客户端 SDK 接进 App。下面是每一端的最小代码。

# 1. 安装
npm install @talkwire/client @talkwire/storage-idb @talkwire/react

// 2. 连接与同步
import { ImClient, ChatEngine } from "@talkwire/client";
import { IdbChatStore } from "@talkwire/storage-idb";

const client = new ImClient({
  endpoints: ["wss://im.example.com/ws/im"],
  tokenProvider,   // 返回你的后端签发的访问令牌
  deviceName,      // 本浏览器的设备名，存在 localStorage
});
const store = await IdbChatStore.open({ name: "talkwire", encrypt: true });
const engine = new ChatEngine(client, store, { appUserId: userId });
await engine.open();
client.start();

完整的接入步骤npm 包与 Maven 坐标还没有发布，现在从源码接入；包名在首个公开版本时确定，以手册为准。

先不想搭环境？用云端测试服务

imtalk.openedskill.com 上跑着一整套 Talkwire。建一个空间、用两个名字登录，就能互发消息、建群、扫码入群、发图片、撤回、打演示通话；Android 示例和你自己的客户端也能直接连上去。按空间隔离，数据每天北京时间 04:00 清空。

wss://imtalk.openedskill.com/ws/im

打开在线示例

测试服务说明

可选模块

用得上才装，核心不依赖它们

每个模块单独发布、单独开关。核心的依赖树里不会出现 RTC SDK 或 libsignal，构建时有检查。

音视频通话
信令、振铃与断线计时在服务端；媒体走 RTC 适配器，自带阿里云 ARTC 3.0 的适配与宿主签令牌的示例。
扫码入群
群二维码、入群页、入群申请与审核；群满时申请留着，不会被吞掉。
群助手钩子
群里有人 @ 助手时，问题交给你的后端回答，计费也由你决定；答不上来时发兜底文案。
端到端加密AGPLv3
基于 libsignal 的单聊与群发送密钥，服务端只转发信封。许可证不同，单独发布。
视频压缩
Android 上超过 50 MB 的视频先重新编码；失败或没变小时，放得下就发原片。
自定义消息卡片
红包、订单这类业务卡片用你自己的内容类型；状态变了由宿主推一次更新。示例里有一张红包卡。

现状

做到哪里，就写到哪里

首个公开版本之前，接口仍可能调整。每一端验证到什么程度，手册里逐项写明。

组成部分	状态	验证
Go 服务端	可用	黄金对话两档全过、竞态检测；正式压测待在 Linux 上做
Node 宿主 SDK	可用	接入后黄金对话 33/33，契约测试双向通过
Android SDK 与界面套件	可用	单测与真实服务端用例；一台真机上验证了聊天、通话信令、扫码入群与网页互通；FCM、视频压缩、E2EE 未上真机
Web SDK 与 React 套件	可用	单测、端到端用例、与 Android 真机互发
云端测试服务	已上线	imtalk.openedskill.com；每次发布后从公网跑端到端检查 17 步
iOS SDK	规划中	—

代码、协议、用例，全部公开

核心以 Apache-2.0 发布，可以商用、可以改。欢迎提 Issue、补用例、实现别的语言的宿主。

开始接入在线试用贡献指南

自己部署的即时通讯，每一帧都经得起比对

单聊与群聊

图片、视频、语音、文件

撤回与清空

已读与正在输入

多端同时在线

离线推送

在线状态三态

浏览器多标签共用连接

可嵌入的后台页面

发送：同一条只存一次

补拉：从连续段末尾开始

迁移：旧客户端不用改

先不想搭环境？用云端测试服务

音视频通话→

扫码入群→

群助手钩子→

端到端加密AGPLv3→

视频压缩→

自定义消息卡片→

代码、协议、用例，全部公开

音视频通话

扫码入群

群助手钩子

端到端加密AGPLv3

视频压缩

自定义消息卡片