632 lines
18 KiB
Markdown
632 lines
18 KiB
Markdown
# Tinode IM 功能详解
|
||
|
||
> 本文档全面介绍 Tinode 即时通讯平台的功能特性，帮助理解产品能力和使用场景。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [产品概述](#产品概述)
|
||
- [核心功能](#核心功能)
|
||
- [消息类型](#消息类型)
|
||
- [会话类型](#会话类型)
|
||
- [用户体系](#用户体系)
|
||
- [群组功能](#群组功能)
|
||
- [文件传输](#文件传输)
|
||
- [推送通知](#推送通知)
|
||
- [视频通话](#视频通话)
|
||
- [安全机制](#安全机制)
|
||
- [扩展能力](#扩展能力)
|
||
- [应用场景](#应用场景)
|
||
|
||
---
|
||
|
||
## 产品概述
|
||
|
||
### 什么是 Tinode
|
||
|
||
Tinode 是一个开源的即时通讯平台，提供完整的 IM 基础设施：
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **开源免费** | GPL 3.0 许可证，代码完全开源 |
|
||
| **跨平台** | 支持 Android、iOS、Web 三端 |
|
||
| **多协议** | WebSocket、gRPC、长轮询 |
|
||
| **多数据库** | MySQL、PostgreSQL、MongoDB、RethinkDB |
|
||
| **高并发** | 支持数万并发连接 |
|
||
| **可扩展** | 支持集群部署、插件系统 |
|
||
|
||
### 核心架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 客户端层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ Android │ │ iOS │ │ Web │ │
|
||
│ │ Tindroid │ │ Tinodious│ │TinodeWeb │ │
|
||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||
└───────┼─────────────┼─────────────┼─────────────────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 协议层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │WebSocket │ │ gRPC │ │Long Poll │ │
|
||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||
└───────┼─────────────┼─────────────┼─────────────────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 服务端 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ Hub │ │ Topic │ │ Session │ │ Auth │ │
|
||
│ │ 连接中心 │ │ 消息路由 │ │ 会话管理 │ │ 认证模块 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 存储层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ MySQL │ │PostgreSQL│ │ MongoDB │ │ RethinkDB│ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 核心功能
|
||
|
||
### 1. 消息收发
|
||
|
||
#### 基本特性
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **实时消息** | WebSocket 实时推送，毫秒级延迟 |
|
||
| **离线消息** | 用户上线自动推送离线期间的消息 |
|
||
| **消息回执** | 已发送、已送达、已读取三种状态 |
|
||
| **消息撤回** | 支持撤回已发送的消息 |
|
||
| **消息引用** | 回复特定消息，形成对话链 |
|
||
| **消息转发** | 转发消息到其他会话 |
|
||
|
||
#### 消息状态流转
|
||
|
||
```
|
||
发送 → 已发送(sent) → 已送达(delivered) → 已读取(read)
|
||
│ │ │
|
||
│ │ └── 接收方打开会话
|
||
│ │
|
||
│ └── 接收方客户端收到
|
||
│
|
||
└── 服务器确认接收
|
||
```
|
||
|
||
### 2. 消息类型
|
||
|
||
#### 文本消息
|
||
|
||
- 纯文本消息
|
||
- 富文本消息（Drafty 格式）
|
||
- 支持@提及功能
|
||
- 支持表情符号
|
||
|
||
#### 多媒体消息
|
||
|
||
| 类型 | 格式支持 | 说明 |
|
||
|------|----------|------|
|
||
| **图片** | JPEG, PNG, GIF, WebP | 自动生成缩略图 |
|
||
| **视频** | MP4, MOV, WebM | 支持视频预览 |
|
||
| **音频** | MP3, AAC, OGG | 语音消息支持 |
|
||
| **文件** | 任意格式 | 文档、压缩包等 |
|
||
|
||
#### 特殊消息
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| **位置** | 地理位置分享 |
|
||
| **名片** | 用户名片分享 |
|
||
| **链接预览** | 自动抓取网页标题、描述、图片 |
|
||
|
||
### 3. 输入状态
|
||
|
||
实时显示对方输入状态：
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `kp` | 正在输入文字 |
|
||
| `kpa` | 正在录制语音 |
|
||
| `kpv` | 正在录制视频 |
|
||
|
||
---
|
||
|
||
## 会话类型
|
||
|
||
### 1. 单聊（P2P）
|
||
|
||
两个用户之间的私密对话：
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **自动创建** | 首次发消息自动创建会话 |
|
||
| **双向同步** | 双方看到不同的会话名（对方用户ID） |
|
||
| **加密存储** | 消息加密存储在数据库 |
|
||
| **阅后即焚** | 支持（需客户端实现） |
|
||
|
||
### 2. 群聊（Group）
|
||
|
||
多用户之间的群组对话：
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **创建群组** | 任意用户可创建群组 |
|
||
| **成员上限** | 默认支持数百人（可配置） |
|
||
| **权限管理** | 所有者、管理员、普通成员 |
|
||
| **邀请加入** | 成员可邀请新成员 |
|
||
| **踢出成员** | 管理员可踢出成员 |
|
||
| **退出群组** | 成员可主动退出 |
|
||
|
||
#### 群组角色
|
||
|
||
| 角色 | 权限 |
|
||
|------|------|
|
||
| **所有者(Owner)** | 全部权限，可转让所有者 |
|
||
| **管理员(Admin)** | 管理成员、修改群信息 |
|
||
| **普通成员(Member)** | 发送消息、查看成员 |
|
||
|
||
### 3. 频道（Channel）
|
||
|
||
单向广播式群组：
|
||
|
||
| 特性 | 普通群组 | 频道 |
|
||
|------|----------|------|
|
||
| 订阅者数量 | 有限制 | 无限制（只读） |
|
||
| 消息发送者 | 所有成员 | 仅管理员 |
|
||
| 加入通知 | 有 | 无 |
|
||
| 消息来源 | 显示发送者 | 不显示 |
|
||
| 用途 | 团队协作 | 内容分发 |
|
||
|
||
### 4. 系统消息（sys）
|
||
|
||
与系统管理员通信的通道：
|
||
|
||
- 普通用户可向系统发送消息（如举报）
|
||
- root 用户可订阅并查看所有消息
|
||
- 用于客服、举报等场景
|
||
|
||
---
|
||
|
||
## 用户体系
|
||
|
||
### 1. 用户属性
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| `username` | 登录名（唯一，用于 basic 认证） |
|
||
| `public` | 公开资料（昵称、头像、简介） |
|
||
| `private` | 私有数据（仅自己可见） |
|
||
| `trusted` | 可信标记（由系统设置） |
|
||
| `tags` | 发现标签（用于搜索） |
|
||
|
||
### 2. 用户状态
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `ok` | 正常状态 |
|
||
| `susp` | 暂停状态（禁止访问，可恢复） |
|
||
| `del` | 已删除状态（软删除） |
|
||
|
||
### 3. 认证方式
|
||
|
||
| 方式 | 说明 |
|
||
|------|------|
|
||
| **Basic** | 用户名 + 密码 |
|
||
| **Token** | 加密令牌（主要方式） |
|
||
| **Anonymous** | 匿名登录（仅创建账户） |
|
||
| **REST** | 外部认证系统集成 |
|
||
|
||
### 4. 多设备登录
|
||
|
||
- 支持同一用户多设备同时在线
|
||
- 每个设备独立会话
|
||
- 消息同步到所有设备
|
||
- 设备标识（User Agent）区分
|
||
|
||
---
|
||
|
||
## 群组功能
|
||
|
||
### 1. 群组管理
|
||
|
||
#### 创建群组
|
||
|
||
```
|
||
{sub topic="new"} → 创建普通群组
|
||
{sub topic="nch"} → 创建频道
|
||
```
|
||
|
||
#### 群组信息
|
||
|
||
| 信息 | 说明 |
|
||
|------|------|
|
||
| 名称 | 群组名称 |
|
||
| 头像 | 群组图标 |
|
||
| 简介 | 群组描述 |
|
||
| 标签 | 发现标签 |
|
||
|
||
### 2. 成员管理
|
||
|
||
#### 邀请加入
|
||
|
||
```
|
||
发送者: {set topic="grpXXX" sub={user="usrYYY", mode="JRWS"}}
|
||
接收者: {pres what="acs"} → 收到邀请通知
|
||
```
|
||
|
||
#### 权限控制
|
||
|
||
| 权限 | 说明 |
|
||
|------|------|
|
||
| `J` | 加入权限（订阅话题） |
|
||
| `R` | 读取权限（接收消息） |
|
||
| `W` | 写入权限（发送消息） |
|
||
| `P` | 在线状态（查看成员状态） |
|
||
| `A` | 管理权限（审批、踢人） |
|
||
| `S` | 分享权限（邀请他人） |
|
||
| `D` | 删除权限（硬删除消息） |
|
||
| `O` | 所有者（完全控制） |
|
||
|
||
### 3. 群组操作
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| 修改群名 | 所有者权限 |
|
||
| 修改群头像 | 所有者权限 |
|
||
| 修改群公告 | 管理员权限 |
|
||
| 设置管理员 | 所有者权限 |
|
||
| 踢出成员 | 管理员权限 |
|
||
| 解散群组 | 所有者权限 |
|
||
|
||
---
|
||
|
||
## 文件传输
|
||
|
||
### 1. 上传方式
|
||
|
||
#### 带外上传（推荐）
|
||
|
||
大文件通过 HTTP POST 单独上传：
|
||
|
||
```
|
||
POST /v0/file/u
|
||
Content-Type: multipart/form-data
|
||
|
||
响应: {ctrl: {params: {url: "/v0/file/s/xxx.jpg"}}}
|
||
```
|
||
|
||
#### 消息引用
|
||
|
||
```json
|
||
{
|
||
"pub": {
|
||
"head": {"mime": "text/x-drafty"},
|
||
"content": {"ent": [{"data": {"ref": "/v0/file/s/xxx.jpg"}}]}
|
||
},
|
||
"extra": {"attachments": ["/v0/file/s/xxx.jpg"]}
|
||
}
|
||
```
|
||
|
||
### 2. 存储方式
|
||
|
||
| 方式 | 说明 |
|
||
|------|------|
|
||
| **本地文件系统** | 适用于单机部署 |
|
||
| **AWS S3** | 适用于云端部署 |
|
||
| **自定义存储** | 实现 media 接口即可 |
|
||
|
||
### 3. 文件限制
|
||
|
||
| 配置项 | 说明 |
|
||
|------|------|
|
||
| `max_file_size` | 最大文件大小 |
|
||
| `allowed_mime_types` | 允许的 MIME 类型 |
|
||
| `upload_timeout` | 上传超时时间 |
|
||
|
||
---
|
||
|
||
## 推送通知
|
||
|
||
### 1. 支持平台
|
||
|
||
| 平台 | 推送服务 |
|
||
|------|----------|
|
||
| Android | Firebase Cloud Messaging (FCM) |
|
||
| iOS | FCM / APNs |
|
||
| Web | Web Push API |
|
||
|
||
### 2. 推送内容
|
||
|
||
```json
|
||
{
|
||
"topic": "grpXXX",
|
||
"xfrom": "usrYYY",
|
||
"ts": "2024-01-01T00:00:00Z",
|
||
"seq": "123",
|
||
"mime": "text/x-drafty",
|
||
"content": "消息内容..."
|
||
}
|
||
```
|
||
|
||
### 3. 推送策略
|
||
|
||
| 状态 | 推送行为 |
|
||
|------|----------|
|
||
| 前台运行 | 不推送，实时接收 |
|
||
| 后台运行 | 推送通知 |
|
||
| 离线 | 推送通知，上线后同步 |
|
||
|
||
### 4. 设备管理
|
||
|
||
- 每个设备注册唯一 `dev_id`
|
||
- 支持多设备推送
|
||
- 支持设备解绑
|
||
|
||
---
|
||
|
||
## 视频通话
|
||
|
||
### 1. 基本流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 呼叫建立 │
|
||
│ │
|
||
│ 呼叫方 服务端 被叫方 │
|
||
│ │ │ │ │
|
||
│ │──── {note what="call"} ─┼───── {info what="call"} ────>│
|
||
│ │ │ │ │
|
||
│ │ │<──── {note what="call"} ─────│ 接听
|
||
│ │ │ │ │
|
||
│ │<───── {info what="call"} ──────────────────────────────│
|
||
│ │ │ │ │
|
||
│ │<════════════════════ WebRTC Signaling ════════════════>│
|
||
│ │ │ │ │
|
||
│ │<═══════════════════════ Media Stream ═════════════════>│
|
||
│ │ │ │ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2. 通话类型
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| **音频通话** | 纯语音通话 |
|
||
| **视频通话** | 音视频通话 |
|
||
| **屏幕共享** | 共享屏幕内容 |
|
||
|
||
### 3. 信令流程
|
||
|
||
1. **发起呼叫**: `{note what="call", seq=...}`
|
||
2. **接听/拒绝**: `{note what="call", seq=...}`
|
||
3. **挂断**: `{note what="call", seq=...}`
|
||
4. **WebRTC 信令**: 通过 `{note what="data", content=...}` 传递
|
||
|
||
---
|
||
|
||
## 安全机制
|
||
|
||
### 1. 传输安全
|
||
|
||
| 层面 | 措施 |
|
||
|------|------|
|
||
| **传输加密** | TLS/HTTPS/WSS |
|
||
| **API 鉴权** | API Key 验证 |
|
||
| **防篡改** | HMAC 签名 |
|
||
|
||
### 2. 认证安全
|
||
|
||
| 措施 | 说明 |
|
||
|------|------|
|
||
| **Token 加密** | 令牌使用 AES 加密 |
|
||
| **Token 过期** | 可配置过期时间 |
|
||
| **密码哈希** | bcrypt 存储密码 |
|
||
|
||
### 3. 访问控制
|
||
|
||
#### 权限矩阵
|
||
|
||
```
|
||
实际权限 = want AND given
|
||
```
|
||
|
||
| 操作 | 权限要求 |
|
||
|------|----------|
|
||
| 发送消息 | W |
|
||
| 接收消息 | R |
|
||
| 查看成员 | P |
|
||
| 邀请成员 | S |
|
||
| 管理成员 | A |
|
||
| 删除消息 | D |
|
||
| 管理群组 | O |
|
||
|
||
### 4. 数据安全
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **软删除** | 消息标记删除，保留数据 |
|
||
| **硬删除** | 物理删除消息（需 D 权限） |
|
||
| **消息清理** | 自动清理过期消息 |
|
||
|
||
---
|
||
|
||
## 扩展能力
|
||
|
||
### 1. 插件系统
|
||
|
||
通过 gRPC Plugin API 开发插件：
|
||
|
||
```go
|
||
service Plugin {
|
||
rpc Firehose(stream PluginReq) returns (stream PluginResp);
|
||
}
|
||
```
|
||
|
||
#### 插件事件
|
||
|
||
| 事件 | 说明 |
|
||
|------|------|
|
||
| `Account creation` | 账户创建 |
|
||
| `Message publish` | 消息发布 |
|
||
| `Subscription` | 订阅事件 |
|
||
| `Topic creation` | 话题创建 |
|
||
|
||
### 2. 聊天机器人
|
||
|
||
示例：chatbot 插件
|
||
|
||
```python
|
||
# 监听新用户创建
|
||
# 自动发送欢迎消息
|
||
# 回复用户消息
|
||
```
|
||
|
||
### 3. 自定义认证
|
||
|
||
集成外部认证系统：
|
||
|
||
```
|
||
┌─────────────┐ REST API ┌─────────────┐
|
||
│ Tinode │ ───────────────> │ External │
|
||
│ Server │ │ Auth │
|
||
│ │ <─────────────── │ Server │
|
||
└─────────────┘ JSON Resp └─────────────┘
|
||
```
|
||
|
||
### 4. 数据库适配
|
||
|
||
实现 `db.Adapter` 接口即可支持新数据库：
|
||
|
||
```go
|
||
type Adapter interface {
|
||
Open(config string) error
|
||
Close() error
|
||
UserGet(uid string) (*User, error)
|
||
MessageSave(msg *Message) error
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 应用场景
|
||
|
||
### 1. 社交应用
|
||
|
||
| 功能 | 实现方式 |
|
||
|------|----------|
|
||
| 私信 | P2P 话题 |
|
||
| 群聊 | 群组话题 |
|
||
| 发现用户 | fnd 话题 + tags |
|
||
| 用户资料 | me 话题 + public |
|
||
|
||
### 2. 企业办公
|
||
|
||
| 功能 | 实现方式 |
|
||
|------|----------|
|
||
| 部门群组 | 群组话题 |
|
||
| 公司公告 | 频道话题 |
|
||
| 文件共享 | 带外文件 + 消息引用 |
|
||
| 视频会议 | WebRTC 视频通话 |
|
||
|
||
### 3. 客服系统
|
||
|
||
| 功能 | 实现方式 |
|
||
|------|----------|
|
||
| 匿名咨询 | anonymous 认证 |
|
||
| 客服工号 | sys 话题 |
|
||
| 消息记录 | 历史消息查询 |
|
||
| 机器人客服 | chatbot 插件 |
|
||
|
||
### 4. IoT 通知
|
||
|
||
| 功能 | 实现方式 |
|
||
|------|----------|
|
||
| 设备告警 | 群组话题 |
|
||
| 远程控制 | 自定义消息格式 |
|
||
| 数据上报 | 消息 content 字段 |
|
||
|
||
---
|
||
|
||
## 功能对比
|
||
|
||
### 与其他 IM 方案对比
|
||
|
||
| 功能 | Tinode | 自建 WebSocket | 第三方 SDK |
|
||
|------|--------|----------------|-----------|
|
||
| 开源免费 | ✅ | ✅ | ❌ |
|
||
| 多端支持 | ✅ | 需自建 | ✅ |
|
||
| 消息存储 | ✅ | 需自建 | ✅ |
|
||
| 离线推送 | ✅ | 需自建 | ✅ |
|
||
| 群组功能 | ✅ | 需自建 | ✅ |
|
||
| 视频通话 | ✅ | 需自建 | ✅ |
|
||
| 自定义认证 | ✅ | 完全自主 | 受限 |
|
||
| 数据私有 | ✅ | ✅ | ❌ |
|
||
| 部署难度 | 中等 | 高 | 低 |
|
||
|
||
---
|
||
|
||
## 快速体验
|
||
|
||
### 1. Docker 部署
|
||
|
||
```bash
|
||
# 启动 MySQL 版本
|
||
docker run -d -p 6060:18080 \
|
||
--name tinode-server \
|
||
tinode/tinode-mysql:latest
|
||
|
||
# 访问 Web 客户端
|
||
open http://localhost:6060
|
||
```
|
||
|
||
### 2. 默认账户
|
||
|
||
使用 `tinode-db` 工具初始化测试数据：
|
||
|
||
| 用户名 | 密码 | 说明 |
|
||
|--------|------|------|
|
||
| alice | alice123 | 测试用户 |
|
||
| bob | bob123 | 测试用户 |
|
||
| carol | carol123 | 测试用户 |
|
||
| dave | dave123 | 测试用户 |
|
||
| tino | tino123 | 聊天机器人 |
|
||
|
||
### 3. API 测试
|
||
|
||
```bash
|
||
# 使用 tn-cli 测试
|
||
cd tn-cli
|
||
pip install -r requirements.txt
|
||
python tn-cli.py --login-basic=alice:alice123
|
||
```
|
||
|
||
---
|
||
|
||
## 客户端下载
|
||
|
||
| 平台 | 仓库 | 说明 |
|
||
|------|------|------|
|
||
| Web | github.com/tinode/webapp | React SPA |
|
||
| Android | github.com/tinode/tindroid | 原生应用 |
|
||
| iOS | github.com/tinode/tinodious | Swift 原生 |
|
||
|
||
---
|
||
|
||
## 更多文档
|
||
|
||
- [项目结构详解](./PROJECT-STRUCTURE.md)
|
||
- [代码通读指南](./CODE-WALKTHROUGH.md)
|
||
- [消息存储机制](./MESSAGE-STORAGE.md)
|
||
- [API 文档](./API-CN.md)
|
||
- [Drafty 富文本格式](./drafty.md)
|
||
- [视频通话建立](./call-establishment.md) |