AnyTalk IM · 后端文档

单二进制、前后端分离。HTTP 对外暴露两类接入：REST（请求-响应型：账号、联系人、会话管理、上传、通话控制）与 WebSocket（/ws，实时消息收发与在场/回执/输入中信令）。

存储：PostgreSQL 用户 / 关系 / 会话 / 消息 / 资产元数据；Redis 在线状态、1v1 通话状态机锁、跨节点消息总线与漏斗（fanout）镜像；对象存储后端（S3）自 M4 起接入，当前开发期使用本地磁盘。

媒体面由 LiveKit 承载：call-<callID> 为 1v1 通话房间、room-<convID> 为群语音房。服务端仅签发 token（JWT，LiveKit 私钥签名），音频 / 视频流转发由 LiveKit 完成；房间进出事件通过 LiveKit webhook 回注。

• RTM（实时消息）：WebSocket → 网关 Gateway → 入站 Dispatcher（msg.* 消息 / presence.query 在线）→ 领域 Service → 持久层。msg.new、msg.receipt 等出站事件经 Redis 总线 push:uid:{id} 扇出，多节点 / 多设备自动收。
• REST：标准 Authorization: Bearer <token> 鉴权。写入型操作通过领域 Service 落库并经同一总线推送。
• 1v1 通话：呼叫先建 Redis 忙线锁（防止同时被多路呼叫），LiveKit 房间 + 双方 token 签发，状态机派生于 Redis：ringing → accepted / rejected / canceled / timeout，通话中忙线锁自动续期。

登录 / 注册返回 JWT（HS256,应用密钥），后续请求置于 Authorization: Bearer <token>。首期为无状态 JWT，登出仅由客户端删除本地 token（POST /v1/auth/logout 为预留占位）。

1v1 会话或群均要求请求者属于对应会话成员（40301 不是该会话成员）。分组操作（改资料 / 拉人 / 踢人）需 owner 或 admin；转让仅 owner。

连接

GET /ws?token=<JWT>（token 走 query，不用 Header）。升级成功后服务端先推一条 ready 信封。底层心跳由 gorilla/websocket 负责（服务端 25s ping / 60s pong 超时）。单条入站消息上限 64KB。

统一信封（Outbound / Inbound）

{
  "rid":  "req-1",          // 请求 ID（入站请求带，出站服务器推送不带）
  "type": "msg.send",       // 业务类型
  "data": { ... },          // 业务负载
  "ts":   1720000000000     // 可选时间戳
}

应答（Ack）

对带 rid 的入站请求，服务端回 ack 信封，ok 标识成败：

入站请求（客户端 → 服务端）

所有入站请求建议携带 rid 以接收 ack；不理会匹配类型的信封数据会被静默忽略。

data: { "conversation_id":1001, "type":"text", "body":"你好",
       "content":{...}, "client_msg_id":"c-1", "reply_to":0 }

data: { "conversation_id":1001, "message_id":500 }

data: { "conversation_id":1001, "message_id":500 }

data: { "message_id":500 }

data: { "conversation_id":1001, "is_typing":true }

data: { "user_ids":[ 1, 2, 3 ] }

连接建立时先收 ready。以下事件由服务端主动推送，客户端按 type 分发。

HTTP 状态码与业务错误码 code 对照如下；错误体统一 {"error":{code,message}}。

单二进制 cmd/anytalk，环境变量驱动（默认以 development 启动，生产须覆盖默认密钥，见 config.Validate）：

注：所有 ID 为 64 位雪花 ID（最长 18 位），超出浮点安全范围，客户端务必以 Int64 / Long 解析。