复制项目

2026-01-14 22:16:44 +08:00
parent e2577b8cee
commit e50142a3b9
691 changed files with 97009 additions and 1 deletions
--- a/docs/webhook-config.md
+++ b/docs/webhook-config.md
@@ -0,0 +1,587 @@
+# Webhook 配置说明文档
+
+## 概述
+
+Webhook 配置用于设置 OpenIM 服务器在特定事件发生时的回调通知。配置支持从数据库动态读取，每小时自动刷新一次。如果数据库中没有配置或配置无效，将使用 `config/webhooks.yml` 中的默认配置。
+
+## 配置结构
+
+### 基础字段
+
+- **url** (string, 必填): Webhook 回调服务器的地址，所有回调请求都会发送到这个地址
+
+### BeforeConfig（前置回调配置）
+
+前置回调在操作执行前触发，可以阻止或修改操作。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| enable | boolean | 是 | 是否启用该回调 |
+| timeout | integer | 是 | 超时时间（秒） |
+| failedContinue | boolean | 是 | 回调失败时是否继续执行原操作（true=继续，false=停止） |
+| deniedTypes | array[int32] | 否 | 不触发回调的消息类型列表，空数组表示所有类型都触发 |
+
+### AfterConfig（后置回调配置）
+
+后置回调在操作执行后触发，用于通知和记录。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| enable | boolean | 是 | 是否启用该回调 |
+| timeout | integer | 是 | 超时时间（秒） |
+| attentionIds | array[string] | 否 | 仅对指定用户ID或群组ID触发回调，空数组表示所有都触发 |
+| deniedTypes | array[int32] | 否 | 不触发回调的消息类型列表，空数组表示所有类型都触发 |
+
+## 支持的回调事件
+
+### 消息相关
+
+| 事件名称 | 类型 | 说明 |
+|---------|------|------|
+| beforeSendSingleMsg | BeforeConfig | 发送单聊消息前 |
+| afterSendSingleMsg | AfterConfig | 发送单聊消息后 |
+| beforeSendGroupMsg | BeforeConfig | 发送群聊消息前 |
+| afterSendGroupMsg | AfterConfig | 发送群聊消息后 |
+| beforeMsgModify | BeforeConfig | 修改消息前（可用于消息过滤） |
+| afterMsgSaveDB | AfterConfig | 消息保存到数据库后 |
+| afterRevokeMsg | AfterConfig | 撤回消息后 |
+| afterGroupMsgRevoke | AfterConfig | 撤回群消息后 |
+| afterGroupMsgRead | AfterConfig | 群消息已读后 |
+| afterSingleMsgRead | AfterConfig | 单聊消息已读后 |
+
+### 用户相关
+
+| 事件名称 | 类型 | 说明 |
+|---------|------|------|
+| beforeUserRegister | BeforeConfig | 用户注册前 |
+| afterUserRegister | AfterConfig | 用户注册后 |
+| beforeUpdateUserInfo | BeforeConfig | 更新用户信息前 |
+| afterUpdateUserInfo | AfterConfig | 更新用户信息后 |
+| beforeUpdateUserInfoEx | BeforeConfig | 更新用户扩展信息前 |
+| afterUpdateUserInfoEx | AfterConfig | 更新用户扩展信息后 |
+| afterUserOnline | AfterConfig | 用户上线后 |
+| afterUserOffline | AfterConfig | 用户下线后 |
+| afterUserKickOff | AfterConfig | 用户被踢下线后 |
+
+### 群组相关
+
+| 事件名称 | 类型 | 说明 |
+|---------|------|------|
+| beforeCreateGroup | BeforeConfig | 创建群组前 |
+| afterCreateGroup | AfterConfig | 创建群组后 |
+| beforeSetGroupInfo | BeforeConfig | 设置群组信息前 |
+| afterSetGroupInfo | AfterConfig | 设置群组信息后 |
+| beforeSetGroupInfoEx | BeforeConfig | 设置群组扩展信息前 |
+| afterSetGroupInfoEx | AfterConfig | 设置群组扩展信息后 |
+| beforeMemberJoinGroup | BeforeConfig | 成员加入群组前 |
+| afterJoinGroup | AfterConfig | 成员加入群组后 |
+| beforeApplyJoinGroup | BeforeConfig | 申请加入群组前 |
+| beforeInviteUserToGroup | BeforeConfig | 邀请用户加入群组前 |
+| afterQuitGroup | AfterConfig | 退出群组后 |
+| afterKickGroupMember | AfterConfig | 踢出群成员后 |
+| afterDismissGroup | AfterConfig | 解散群组后 |
+| afterTransferGroupOwner | AfterConfig | 转移群主后 |
+| beforeSetGroupMemberInfo | BeforeConfig | 设置群成员信息前 |
+| afterSetGroupMemberInfo | AfterConfig | 设置群成员信息后 |
+
+### 好友相关
+
+| 事件名称 | 类型 | 说明 |
+|---------|------|------|
+| beforeAddFriend | BeforeConfig | 添加好友前 |
+| afterAddFriend | AfterConfig | 添加好友后 |
+| beforeAddFriendAgree | BeforeConfig | 同意好友申请前 |
+| afterAddFriendAgree | AfterConfig | 同意好友申请后 |
+| afterDeleteFriend | AfterConfig | 删除好友后 |
+| beforeSetFriendRemark | BeforeConfig | 设置好友备注前 |
+| afterSetFriendRemark | AfterConfig | 设置好友备注后 |
+| beforeImportFriends | BeforeConfig | 导入好友前 |
+| afterImportFriends | AfterConfig | 导入好友后 |
+| beforeAddBlack | BeforeConfig | 加入黑名单前 |
+| afterRemoveBlack | AfterConfig | 移除黑名单后 |
+
+### 推送相关
+
+| 事件名称 | 类型 | 说明 |
+|---------|------|------|
+| beforeOfflinePush | BeforeConfig | 离线推送前 |
+| beforeOnlinePush | BeforeConfig | 在线推送前 |
+| beforeGroupOnlinePush | BeforeConfig | 群组在线推送前 |
+
+### 会话相关
+
+| 事件名称 | 类型 | 说明 |
+|---------|------|------|
+| beforeCreateSingleChatConversations | BeforeConfig | 创建单聊会话前 |
+| afterCreateSingleChatConversations | AfterConfig | 创建单聊会话后 |
+| beforeCreateGroupChatConversations | BeforeConfig | 创建群聊会话前 |
+| afterCreateGroupChatConversations | AfterConfig | 创建群聊会话后 |
+
+## JSON 配置示例
+
+### 完整配置示例
+
+```json
+{
+  "url": "http://your-webhook-server:8080/callback",
+  "beforeSendSingleMsg": {
+    "enable": true,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterSendSingleMsg": {
+    "enable": true,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeSendGroupMsg": {
+    "enable": true,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterSendGroupMsg": {
+    "enable": true,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeMsgModify": {
+    "enable": true,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterMsgSaveDB": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterUserOnline": {
+    "enable": true,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterUserOffline": {
+    "enable": true,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterUserKickOff": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeOfflinePush": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "beforeOnlinePush": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "beforeGroupOnlinePush": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "beforeAddFriend": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "beforeUpdateUserInfo": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterUpdateUserInfo": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeCreateGroup": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterCreateGroup": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeMemberJoinGroup": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "beforeSetGroupMemberInfo": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterSetGroupMemberInfo": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterQuitGroup": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterKickGroupMember": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterDismissGroup": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeApplyJoinGroup": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterGroupMsgRead": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterSingleMsgRead": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeUserRegister": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterUserRegister": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterTransferGroupOwner": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeSetFriendRemark": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterSetFriendRemark": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterGroupMsgRevoke": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterJoinGroup": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeInviteUserToGroup": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterSetGroupInfo": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeSetGroupInfo": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterSetGroupInfoEx": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeSetGroupInfoEx": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterRevokeMsg": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeAddBlack": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterAddFriend": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeAddFriendAgree": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterAddFriendAgree": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterDeleteFriend": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeImportFriends": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterImportFriends": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "afterRemoveBlack": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeCreateSingleChatConversations": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": false,
+    "deniedTypes": []
+  },
+  "afterCreateSingleChatConversations": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeCreateGroupChatConversations": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": false,
+    "deniedTypes": []
+  },
+  "afterCreateGroupChatConversations": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeUpdateUserInfoEx": {
+    "enable": false,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterUpdateUserInfoEx": {
+    "enable": false,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  }
+}
+```
+
+### 最小配置示例（仅启用消息回调）
+
+```json
+{
+  "url": "http://your-webhook-server:8080/callback",
+  "beforeSendSingleMsg": {
+    "enable": true,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterSendSingleMsg": {
+    "enable": true,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  },
+  "beforeSendGroupMsg": {
+    "enable": true,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": []
+  },
+  "afterSendGroupMsg": {
+    "enable": true,
+    "timeout": 5,
+    "attentionIds": [],
+    "deniedTypes": []
+  }
+}
+```
+
+### 过滤特定消息类型示例
+
+```json
+{
+  "url": "http://your-webhook-server:8080/callback",
+  "beforeSendSingleMsg": {
+    "enable": true,
+    "timeout": 5,
+    "failedContinue": true,
+    "deniedTypes": [101, 102]
+  }
+}
+```
+
+### 仅关注特定用户/群组示例
+
+```json
+{
+  "url": "http://your-webhook-server:8080/callback",
+  "afterSendSingleMsg": {
+    "enable": true,
+    "timeout": 5,
+    "attentionIds": ["user001", "user002"],
+    "deniedTypes": []
+  },
+  "afterSendGroupMsg": {
+    "enable": true,
+    "timeout": 5,
+    "attentionIds": ["group001", "group002"],
+    "deniedTypes": []
+  }
+}
+```
+
+## 配置说明
+
+### URL 配置
+
+- **格式**: `http://host:port/path` 或 `https://host:port/path`
+- **示例**: 
+  - `http://127.0.0.1:8080/callback`
+  - `http://webhook.example.com:8080/callback`
+  - `https://webhook.example.com/callback`
+
+### timeout（超时时间）
+
+- **单位**: 秒
+- **建议值**: 5-30 秒
+- **说明**: 如果回调服务器在超时时间内没有响应，将根据 `failedContinue` 决定是否继续执行
+
+### failedContinue（失败是否继续）
+
+- **仅适用于**: BeforeConfig 类型的事件
+- **true**: 回调失败时继续执行原操作
+- **false**: 回调失败时停止执行原操作
+
+### deniedTypes（拒绝的消息类型）
+
+- **类型**: 整数数组
+- **说明**: 列表中的消息类型不会触发回调
+- **空数组**: 表示所有消息类型都触发回调
+- **常用消息类型**:
+  - 101: 文本消息
+  - 102: 图片消息
+  - 103: 语音消息
+  - 104: 视频消息
+  - 105: 文件消息
+
+### attentionIds（关注ID列表）
+
+- **仅适用于**: AfterConfig 类型的事件
+- **类型**: 字符串数组
+- **说明**: 
+  - 对于消息回调：仅对指定的用户ID或群组ID触发回调
+  - 空数组表示所有用户/群组都触发回调
+- **示例**: `["user001", "user002", "group001"]`
+
+## 配置存储
+
+### 数据库存储
+
+配置可以存储在 MongoDB 的 `system_configs` 表中：
+
+- **表名**: `system_configs`
+- **配置键**: `webhook_config`
+- **值类型**: JSON (ValueType = 4)
+
+### 配置优先级
+
+1. **数据库配置**（如果存在且有效）
+2. **文件配置**（`config/webhooks.yml`）
+
+如果数据库中没有配置或配置无效（为空、禁用、格式错误等），将自动使用文件配置。
+
+## 配置刷新
+
+- **刷新间隔**: 30 秒（调试模式，生产环境建议改为1小时）
+- **自动刷新**: 服务启动后自动开始定时刷新
+- **立即生效**: 配置更新后，最多30秒内自动生效（无需重启服务）
+
+## 注意事项
+
+1. **URL 必须有效**: 配置的 URL 必须可访问，否则回调会失败
+2. **超时设置**: 建议根据回调服务器的响应时间合理设置超时时间
+3. **失败处理**: BeforeConfig 类型的回调建议设置 `failedContinue: true`，避免因回调失败影响正常业务
+4. **性能考虑**: 启用过多回调可能影响系统性能，建议按需启用
+5. **安全性**: 确保回调服务器有适当的认证机制
+