# 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)