多租户更改

2026-08-11 15:59:57 +08:00
parent 6c800de67d
commit c2076721fc
453 changed files with 102349 additions and 47 deletions
@@ -0,0 +1,632 @@
+# 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)