Skip to content

Commit 90ca503

Browse files
skiffer-gitskiffer-git
committed
doc
1 parent 8e50418 commit 90ca503

4 files changed

Lines changed: 225 additions & 20 deletions

File tree

‎docs/guides/introduction/termDefinition.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: '概念解释'
3+
hide_title: true
4+
sidebar_position: 2
5+
---
6+
# 概念解释
7+
8+
## 用户类型
9+
10+
在 OpenIM 系统中，用户分为三种类型：**普通用户**、**APP 管理员**和**通知号**。
11+
12+
### 普通用户
13+
14+
- **组成**：`userID`、`faceURL`、`nickname`、`ex`
15+
- **描述**：普通用户通常由外部业务系统导入，代表 OpenIM 系统的标准终端用户。ex字段作为扩展字段供业务使用。
16+
17+
### APP 管理员
18+
19+
- **权限**：拥有超级权限
20+
- **用途**：通过 APP 管理员的身份调用 REST API 直接操作 OpenIM 系统。
21+
- **内置管理员**：OpenIM 服务器内置一个 APP 管理员，其 `userID` 为 **imAdmin**。
22+
23+
### 通知号
24+
25+
- **功能**：APP 管理员以系统通知号的身份发送通知消息，不受好友关系和群组权限的约束。可通过REST API增加通知号，以及修改通知号昵称和头像。
26+
- **用户体验**：用户收到消息后，消息会以通知号的头像和昵称显示在会话中。
27+
28+
---
29+
30+
## 群组
31+
32+
在 OpenIM 系统中，群组功能包括以下几个方面：
33+
34+
### 群组类型
35+
36+
- **单一群组类型**：当前系统仅支持一种群组类型，不区分小群或大群。
37+
38+
### 群成员限制
39+
40+
- **成员上限**：群成员数量无限制，最高支持 **100,000** 名成员。
41+
42+
### 进群方式
43+
44+
用户可以通过以下三种方式加入群组：
45+
46+
1. **群成员邀请**：现有群成员可以邀请新成员直接加入群组。
47+
2. **发送进群申请**：用户需提交申请，等待群主或管理员批准后方可加入。
48+
3. **允许所有人加群**：任何用户都可以自由加入群组，无需审批。
49+
50+
### 群组角色及权限
51+
52+
群组内共有三种身份，权限依次递减：
53+
54+
1. **群主**
55+
2. **管理员**
56+
3. **普通成员**
57+
58+
#### 群主
59+
60+
- **权限**：拥有最高权限。
61+
- **管理功能**：
62+
- 设置多个管理员，管理员之间权限相同。
63+
- 解散群组。
64+
- 转让群主身份给其他群成员。
65+
- 退群前必须先转让群主身份。
66+
- 处理进群申请。
67+
- 管理群设置，如群公告、群名称等。
68+
69+
#### 管理员
70+
71+
- **权限**：与其他管理员权限相同，次于群主。
72+
- **管理功能**：
73+
- 处理进群申请。
74+
- 管理群设置，如群公告、群名称等。
75+
- 对普通成员进行管理操作，例如踢出群成员、禁言成员。
76+
77+
#### 普通成员
78+
79+
- **权限**：拥有基本的群组使用权限。
80+
- **功能**：参与群聊，查看群公告，发送消息等。
81+
82+
### 权限管理
83+
84+
- **高权限身份操作**：群主和管理员可以对低权限身份进行操作，如踢出群、禁言等。
85+
- **管理员之间权限相同**：管理员之间无上下级关系，彼此权限平等。
86+
87+
### 群主与管理员的管理功能
88+
89+
- **处理进群申请**：群主和管理员可以审核并处理用户的进群申请。
90+
- **群组设置管理**：包括编辑群公告、修改群名称等。
91+
92+
---
93+
94+
## 消息和通知
95+
96+
### 消息
97+
98+
- **定义**：消息指由用户或系统发送的实际内容，包括文字、图片、视频等多媒体形式。
99+
- **功能**：
100+
- **传输内容**：将消息内容传送至接收者。
101+
- **展示与显示**：在接收端清晰展示消息内容，确保用户能够理解和查看。
102+
103+
### 通知
104+
105+
- **定义**：通知指由用户或系统触发的行为，以通知形式发送给相关方。
106+
- **用途**：
107+
- **系统同步**：用于同步系统状态或操作，如群成员同步、好友列表同步等。
108+
- **信息展示**：用于向用户展示重要事件或操作结果，例如进群通知、系统公告等。
109+
110+
---
111+
112+
## 消息推送
113+
114+
### 在线推送
115+
116+
- **定义**：当用户在线时，OpenIM 优先使用自己的长连接通道进行消息推送，此时称为在线推送。
117+
- **特点**：
118+
- **实时性强**：消息能立即传达给接收者。
119+
- **稳定性**：依赖长连接通道，确保消息传输的可靠性。
120+
121+
### 离线推送
122+
123+
- **定义**：当用户不在线时，或者 APP 被杀死，此时 OpenIM 长连接无法推送消息，必须借用第三方推送服务。
124+
- **实现方式**：
125+
- **厂商推送**：利用如 APNs（苹果推送通知服务）等厂商的推送服务进行消息传递。
126+
- **中国境内**：一般使用**个推**服务。
127+
- **境外**：一般使用**Firebase**服务。
128+
- **特点**：
129+
- **覆盖广**：适用于各种网络环境，确保消息能在用户恢复上线时被接收。
130+
131+
---
132+
133+
## 消息存储类型
134+
135+
### 本地消息
136+
- 除了 jssdk 外，OpenIM 的消息会根据需要进行拉取加载。对于客户端已拉取的消息，系统会将其存储在本地，统称为“本地消息” 。
137+
138+
### 多端同步消息
139+
- 用户通常会使用多种设备，当用户从设备 A 发送消息时，该消息会同步到设备 B，这类消息称为“多端同步消息” 。
140+
141+
### 离线消息
142+
- 用户在离线期间接收到的消息，系统会在用户重新登录后根据需要从服务器同步并加载，这些消息称为“离线消息” 。
143+
144+
### 漫游消息
145+
- 当用户更换设备或重新安装应用时，系统会拉取并同步这些历史消息，这些消息被称为“漫游消息” 。
146+
147+
---

‎docs/restapi/apis/authenticationManagement/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"position": 1,
2+
"position": 2,
33
"label": "认证管理",
44
"collapsible": true,
55
"collapsed": true

‎docs/restapi/apis/introduction.mdx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: API说明
3+
sidebar_position: 1
4+
---
5+
6+
# OpenIM Server APIs
7+
8+
## 🚀 REST API
9+
10+
OpenIM Server 提供了 **REST API**，允许您以超级权限直接从服务端发起请求操作 IM 系统，以增强业务功能。例如：
11+
12+
- 🛠 **创建群组**
13+
- 📬 **推送消息**
14+
15+
使用场景，例如，系统自动向新注册用户发送欢迎消息。
16+
17+
### 协议说明
18+
- **协议**：使用标准的 HTTP 协议
19+
- **数据格式**：请求和响应均为 JSON 格式
20+
### 重要说明
21+
22+
> **API 地址**：
23+
>
24+
> 请求 URL 中的 `{API_ADDRESS}` 为 OpenIM Server 对外服务的 API 地址，例如 `http://{your_im_server_ip}:10002`。
25+
26+
> **权限要求**：
27+
>
28+
> 调用 **REST API** 需要以 **APP 管理员** 身份进行，此用户具有超级权限。OpenIM Server 内置了一个 APP 管理员，其 `userID` 为 `imAdmin`。
29+
30+
> **参数限制**：
31+
>
32+
> API 请求参数中所有的 `array` 类型的最大长度限制为 `1000`。
33+
34+
### API调用过程
35+
36+
1. **获取APP管理员 Token**：
37+
38+
通过 [`user_token API`](./apis/authenticationManagement/getAdminToken) 获取管理员 Token。
39+
40+
2. **调用其他 API**：
41+
42+
将获取到的 APP 管理员 Token 添加到 HTTP 请求的 Header 中，然后调用其他 REST API。
43+
44+
### 使用指南
45+
46+
为安全起见，REST API 只能在服务端使用，客户端使用相应的客户端 SDK 进行操作。
47+
48+
49+

‎docs/restapi/introduction.mdx‎

Lines changed: 28 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,32 +7,41 @@ sidebar_position: 1
77

88
## 🚀 REST API
99

10-
OpenIM Server 提供了 **REST API** 供业务系统使用，以增强业务功能。如：
10+
OpenIM Server 提供了 **REST API**，允许您以超级权限直接从服务端发起请求操作 IM 系统，以增强业务功能。例如：
1111

12-
- 🛠 建立群组
13-
- 📬 推送消息
12+
- 🛠 **创建群组**
13+
- 📬 **推送消息**
1414

15-
更多功能参考后面的 API 文档
15+
### 协议说明
16+
- **协议**：使用标准的 HTTP 协议
17+
- **数据格式**：请求和响应均为 JSON 格式
18+
### 重要说明
1619

17-
> ⚠️ **注意**:
18-
> 请求 URL 中的 `{API_ADDRESS}` 为 OpenIM Server 部署的主机地址，如 `http://IP:10002`。
20+
> **API 地址**：
1921
>
20-
> 调用 **REST API** ，需要以 **APP 管理员** 身份进行，此服务由端口 `10002` 提供。所谓 **APP 管理员**，即有超级权限的用户。OpenIM Server 内置了一个 APP 管理员，它的 userID 为 imAdmin
21-
>
22-
> `API`请求参数中所有的`array`最大长度限制为`1000`。
23-
>
24-
> API 鉴权流程：
22+
> 请求 URL 中的 `{API_ADDRESS}` 为 OpenIM Server 对外服务的 API 地址，例如 `http://{your_im_server_ip}:10002`。
23+
24+
> **权限要求**：
2525
>
26-
> 1. 通过 [`user_token API`](./apis/authenticationManagement/getAdminToken) 获取管理员 token
27-
> 2. 使用管理员 token 调用其他 API
26+
> 调用 **REST API** 需要以 **APP 管理员** 身份进行，此用户具有超级权限。OpenIM Server 内置了一个 APP 管理员，其 `userID` 为 `imAdmin`。
27+
28+
> **参数限制**：
2829
>
29-
> `API`请求参数中所有的`array`最大长度限制为`1000`。
30+
> API 请求参数中所有的 `array` 类型的最大长度限制为 `1000`。
31+
32+
### API 鉴权流程
33+
34+
1. **获取管理员 Token**：
35+
36+
通过 [`user_token API`](./apis/authenticationManagement/getAdminToken) 获取管理员 Token。
37+
38+
2. **调用其他 API**：
39+
40+
使用获取到的管理员 Token 调用其他 REST API。
41+
42+
### 使用指南
3043

31-
## 🔗 Webhooks
44+
为安全起见，REST API 只能在服务端使用，客户端使用相应的客户端 SDK 进行操作。
3245

33-
OpenIM Server 还提供了强大的回调功能，以满足更多的业务需求。**回调** 的定义是，当某事件发生前或后，OpenIM Server 会向业务服务器发出请求。如：
3446

35-
- 📤 发送消息前的回调
36-
- 📥 发送消息后的回调
3747

38-
>请求 URL 中的 `{WEBHOOK_ADDRESS}` 为`webhook`部署的主机地址。

0 commit comments

Comments
 (0)