OpenIM 源码深度解析系列（十八）：附录二数据库结构

附录二数据库结构

📋 概述

OpenIM是一个完整的即时通讯解决方案，由三个核心项目组成，每个项目都有自己的数据存储系统：

• open-im-server: 服务端核心，使用MongoDB存储业务数据
• chat: 聊天管理系统，使用MongoDB存储管理和用户数据
• openim-sdk-core: 客户端SDK，使用SQLite存储本地数据

本文档详细描述了这三个项目的完整数据库架构，涵盖所有数据表的结构、字段定义、索引设计和业务功能。

🏗️ 整体架构

graph TB
    subgraph "Server端 (MongoDB)"
        A[open-im-server<br/>业务核心数据]
        B[chat<br/>管理和用户数据]
    end
    
    subgraph "Client端 (SQLite)"
        C[openim-sdk-core<br/>本地缓存数据]
    end
    
    A <--> C
    B <--> C
    
    A -.->|消息推送| D[消息网关]
    B -.->|用户管理| D
    D --> C

📊 数据库分类

1. open-im-server (MongoDB)

• 用途: 即时通讯业务核心数据存储
• 数据类型: 消息、会话、用户关系、群组等
• 特点: 高并发读写、消息持久化、分片存储

2. chat (MongoDB)

• 用途: 聊天系统管理和扩展功能
• 数据类型: 用户账户、管理配置、机器人等
• 特点: 管理功能、用户认证、系统配置

3. openim-sdk-core (SQLite)

• 用途: 客户端本地数据缓存
• 数据类型: 本地消息、会话状态、离线数据等
• 特点: 本地存储、离线支持、快速查询

---

📚 数据库详细结构

🚀 open-im-server 项目数据库 (MongoDB)

📋 表结构概览

open-im-server使用MongoDB作为主数据库，包含16个核心集合，涵盖用户、消息、群组、好友关系等所有业务数据。

---

1. User - 用户基础信息表

功能描述: 存储系统中所有用户的基础信息，是用户体系的核心表。

集合名: user

字段名	类型	描述
user_id	string	用户唯一标识ID
nickname	string	用户昵称
face_url	string	用户头像URL地址
ex	string	扩展字段，存储额外信息
app_manger_level	int32	应用管理员等级(0-普通用户)
global_recv_msg_opt	int32	全局消息接收选项(0-接收,1-不接收,2-接收不提醒)
create_time	time.Time	用户创建时间

索引设计:

• user_id: 唯一索引，主键查询

业务场景:

• 用户注册信息存储
• 用户基础信息查询和更新
• 全局消息接收策略控制

---

2. Friend - 好友关系表

功能描述: 存储用户间的好友关系，支持双向好友关系和好友备注。

集合名: friend

字段名	类型	描述
_id	ObjectID	MongoDB自动生成的主键
owner_user_id	string	好友关系拥有者用户ID
friend_user_id	string	好友的用户ID
remark	string	好友备注名称
create_time	time.Time	好友关系建立时间
add_source	int32	添加好友的来源方式
operator_user_id	string	操作者用户ID
ex	string	扩展字段
is_pinned	bool	是否置顶好友

索引设计:

• owner_user_id + friend_user_id: 复合唯一索引，防重复添加
• owner_user_id: 普通索引，查询用户好友列表

业务场景:

• 好友关系管理
• 好友列表查询
• 好友备注设置

---

3. FriendRequest - 好友申请表

功能描述: 记录好友申请的发送、接收和处理状态，支持申请消息和处理结果。

集合名: friend_request

字段名	类型	描述
from_user_id	string	发送好友申请的用户ID
to_user_id	string	接收好友申请的用户ID
handle_result	int32	处理结果(0-未处理,1-同意,-1-拒绝)
req_msg	string	好友申请附带消息
create_time	time.Time	申请创建时间
handler_user_id	string	处理申请的用户ID
handle_msg	string	处理时的回复消息
handle_time	time.Time	申请处理时间
ex	string	扩展字段

索引设计:

• from_user_id + to_user_id: 复合唯一索引，防重复申请
• to_user_id: 普通索引，查询收到的申请
• from_user_id: 普通索引，查询发出的申请

业务场景:

• 好友申请发送和接收
• 申请状态管理
• 申请历史记录查询

---

4. Black - 黑名单表

功能描述: 存储用户的黑名单关系，被拉黑用户无法发送消息给对方。

集合名: black

字段名	类型	描述
owner_user_id	string	黑名单拥有者用户ID
block_user_id	string	被拉黑的用户ID
create_time	time.Time	拉黑时间
add_source	int32	拉黑来源
operator_user_id	string	操作者用户ID
ex	string	扩展字段

索引设计:

• owner_user_id + block_user_id: 复合唯一索引
• owner_user_id: 普通索引，查询黑名单列表

业务场景:

• 用户拉黑功能
• 黑名单管理
• 消息发送权限控制

---

5. Group - 群组信息表

功能描述: 存储群组的基础信息，包括群名称、公告、权限设置等。

集合名: group

字段名	类型	描述
group_id	string	群组唯一标识ID
group_name	string	群组名称
notification	string	群公告内容
introduction	string	群介绍
face_url	string	群头像URL
create_time	time.Time	群组创建时间
ex	string	扩展字段
status	int32	群状态(0-正常,1-禁言,2-解散)
creator_user_id	string	群创建者用户ID
group_type	int32	群类型(0-普通群,1-超级群,2-工作群)
need_verification	int32	入群验证(0-直接入群,1-需要验证,2-禁止入群)
look_member_info	int32	查看成员信息权限
apply_member_friend	int32	申请成员为好友权限
notification_update_time	time.Time	群公告更新时间
notification_user_id	string	群公告更新者ID

索引设计:

• group_id: 唯一索引
• creator_user_id: 普通索引，查询创建的群组

业务场景:

• 群组创建和管理
• 群信息查询和更新
• 群权限控制

---

6. GroupMember - 群成员表

功能描述: 存储群组成员信息，包括角色权限、加入时间、禁言状态等。

集合名: group_member

字段名	类型	描述
group_id	string	群组ID
user_id	string	成员用户ID
nickname	string	群内昵称
face_url	string	用户头像URL
role_level	int32	角色等级(20-普通成员,60-管理员,100-群主)
join_time	time.Time	加入群组时间
join_source	int32	加入来源
inviter_user_id	string	邀请者用户ID
operator_user_id	string	操作者用户ID
mute_end_time	time.Time	禁言结束时间
ex	string	扩展字段

索引设计:

• group_id + user_id: 复合唯一索引
• group_id: 普通索引，查询群成员
• user_id: 普通索引，查询用户加入的群

业务场景:

• 群成员管理
• 权限控制
• 禁言管理

---

7. GroupRequest - 群组申请表

功能描述: 记录用户加入群组的申请请求和处理状态。

集合名: group_request

字段名	类型	描述
user_id	string	申请用户ID
group_id	string	申请加入的群组ID
handle_result	int32	处理结果(0-未处理,1-同意,-1-拒绝)
req_msg	string	申请消息
handled_msg	string	处理回复消息
req_time	time.Time	申请时间
handle_user_id	string	处理者用户ID
handled_time	time.Time	处理时间
join_source	int32	加入来源
inviter_user_id	string	邀请者用户ID
ex	string	扩展字段

索引设计:

• user_id + group_id: 复合唯一索引
• group_id: 普通索引，查询群申请
• user_id: 普通索引，查询用户申请

业务场景:

• 入群申请管理
• 申请审核流程
• 申请历史记录

---

8. Conversation - 会话表

功能描述: 存储用户的会话信息，包括单聊和群聊会话的配置和状态。

集合名: conversation

字段名	类型	描述
owner_user_id	string	会话拥有者用户ID
conversation_id	string	会话唯一标识ID
conversation_type	int32	会话类型(1-单聊,2-群聊)
user_id	string	单聊对方用户ID
group_id	string	群聊群组ID
recv_msg_opt	int32	消息接收选项
is_pinned	bool	是否置顶会话
is_private_chat	bool	是否私密聊天
burn_duration	int32	阅后即焚时长
group_at_type	int32	群@类型
attached_info	string	附加信息
ex	string	扩展字段
max_seq	int64	最大消息序列号
min_seq	int64	最小消息序列号
create_time	time.Time	创建时间
is_msg_destruct	bool	是否开启消息销毁
msg_destruct_time	int64	消息销毁时间
latest_msg_destruct_time	time.Time	最新消息销毁时间

索引设计:

• owner_user_id + conversation_id: 复合唯一索引
• owner_user_id: 普通索引，查询用户会话列表

业务场景:

• 会话管理
• 消息接收设置
• 阅后即焚功能

---

9. MsgDocModel - 消息文档表

功能描述: 存储聊天消息的主要数据结构，采用分片存储策略提高查询性能。

集合名: msg

字段名	类型	描述
doc_id	string	文档ID，格式：会话ID:分片索引
msgs	[]MsgInfoModel	消息数组，每个文档存储100条消息

MsgInfoModel结构:

字段名	类型	描述
msg	MsgDataModel	消息数据
revoke	RevokeModel	撤回信息
del_list	[]string	删除列表
is_read	bool	是否已读

MsgDataModel结构:

字段名	类型	描述
send_id	string	发送者用户ID
recv_id	string	接收者ID
group_id	string	群组ID
client_msg_id	string	客户端消息ID
server_msg_id	string	服务端消息ID
sender_platform_id	int32	发送者平台ID
sender_nickname	string	发送者昵称
sender_face_url	string	发送者头像
session_type	int32	会话类型
msg_from	int32	消息来源
content_type	int32	内容类型
content	string	消息内容
seq	int64	消息序列号
send_time	int64	发送时间
create_time	int64	创建时间
status	int32	消息状态
is_read	bool	是否已读
options	map[string]bool	消息选项
offline_push	OfflinePushModel	离线推送信息
at_user_id_list	[]string	@用户列表
attached_info	string	附加信息
ex	string	扩展字段

索引设计:

• doc_id: 唯一索引
• 按会话ID分片存储，每100条消息一个文档

业务场景:

• 消息存储和查询
• 消息分页拉取
• 消息状态管理

---

10. SeqUser - 用户序列号表

功能描述: 记录用户在每个会话中的消息序列号信息，用于消息同步。

集合名: seq_user

字段名	类型	描述
user_id	string	用户ID
conversation_id	string	会话ID
min_seq	int64	最小序列号
max_seq	int64	最大序列号
read_seq	int64	已读序列号

索引设计:

• user_id + conversation_id: 复合唯一索引

业务场景:

• 消息同步控制
• 已读状态管理
• 未读消息计算

---

11. SeqConversation - 会话序列号表

功能描述: 记录会话的全局消息序列号，用于消息排序和同步。

集合名: seq_conversation

字段名	类型	描述
conversation_id	string	会话ID
max_seq	int64	最大序列号
min_seq	int64	最小序列号

索引设计:

• conversation_id: 唯一索引

业务场景:

• 消息序列号分配
• 会话消息计数
• 消息同步基准

---

12. Object - 对象存储表

功能描述: 记录上传文件的元数据信息，包括文件哈希、大小、类型等。

集合名: object

字段名	类型	描述
name	string	文件名称
user_id	string	上传用户ID
hash	string	文件哈希值
engine	string	存储引擎
key	string	存储键值
size	int64	文件大小
content_type	string	文件MIME类型
group	string	文件分组
create_time	time.Time	创建时间

索引设计:

• hash: 唯一索引，文件去重
• user_id: 普通索引，查询用户文件

业务场景:

• 文件上传管理
• 文件去重处理
• 存储空间统计

---

13. Log - 系统日志表

功能描述: 记录系统操作日志和用户行为日志，用于问题排查和数据分析。

集合名: log

字段名	类型	描述
log_id	string	日志唯一ID
platform	string	平台信息
user_id	string	用户ID
create_time	time.Time	创建时间
url	string	日志文件URL
file_name	string	日志文件名
system_type	string	系统类型
app_framework	string	应用框架
version	string	版本号
ex	string	扩展字段

索引设计:

• log_id: 唯一索引
• user_id: 普通索引
• create_time: 时间索引

业务场景:

• 系统日志记录
• 问题排查分析
• 用户行为统计

---

14. SubscribeUser - 用户订阅表

功能描述: 管理用户间的在线状态订阅关系，用于实时状态推送。

集合名: subscribe_user

字段名	类型	描述
user_id	string	订阅者用户ID
user_id_list	[]string	被订阅用户ID列表

索引设计:

• user_id: 唯一索引

业务场景:

• 在线状态订阅
• 状态变化通知
• 好友在线提醒

---

15. Application - 应用版本表

功能描述: 管理客户端应用的版本信息，支持版本控制和强制更新。

集合名: application

字段名	类型	描述
_id	ObjectID	MongoDB主键
platform	string	平台(iOS/Android/Web)
hot	bool	是否热更新
version	string	版本号
url	string	下载地址
text	string	更新说明
force	bool	是否强制更新
latest	bool	是否最新版本
create_time	time.Time	创建时间

索引设计:

• platform + version: 复合索引
• latest: 布尔索引

业务场景:

• 版本发布管理
• 客户端更新控制
• 平台版本查询

---

16. VersionLog - 版本日志表

功能描述: 记录数据变更的版本信息，支持增量同步和数据回滚。

集合名: version_log

字段名	类型	描述
_id	ObjectID	MongoDB主键
d_id	string	数据ID
logs	[]VersionLogElem	版本日志元素数组
version	uint	当前版本号
deleted	uint	删除版本号
last_update	time.Time	最后更新时间

VersionLogElem结构:

字段名	类型	描述
e_id	string	元素ID
state	int32	状态(1-插入,2-删除,3-更新)
version	uint	版本号
last_update	time.Time	更新时间

索引设计:

• d_id: 普通索引
• version: 普通索引

业务场景:

• 数据版本控制
• 增量同步支持
• 数据变更追踪

---

💬 chat 项目数据库 (MongoDB)

📋 表结构概览

chat项目使用MongoDB作为数据库，按功能模块分为三大类：Admin模块(管理系统)、Bot模块(智能机器人)、Chat模块(聊天系统)，共包含18个集合。

---

🔧 Admin模块 - 管理系统数据表

1. admin - 管理员表

功能描述: 存储系统管理员账户信息，支持分级权限管理。

集合名: admin

字段名	类型	描述
account	string	管理员账号(唯一标识)
password	string	登录密码(加密存储)
face_url	string	管理员头像URL
nickname	string	管理员昵称
user_id	string	关联的用户ID
level	int32	管理员权限等级
create_time	time.Time	账户创建时间

索引设计:

• account: 唯一索引，用于登录验证

业务场景:

• 管理员登录认证
• 权限等级控制
• 管理员账户管理

---

2. applet - 小程序管理表

功能描述: 管理系统中的小程序应用，支持版本控制和上下架管理。

集合名: applet

字段名	类型	描述
id	string	小程序唯一标识ID
name	string	小程序显示名称
app_id	string	小程序应用ID
icon	string	小程序图标URL
url	string	小程序访问地址
md5	string	程序包MD5校验值
size	int64	程序包文件大小
version	string	小程序版本号
priority	uint32	显示优先级
status	int32	状态(1-上架,2-下架)
create_time	time.Time	创建时间

索引设计:

• id: 唯一索引
• status: 普通索引，筛选上架应用

业务场景:

• 小程序应用管理
• 版本发布控制
• 应用商店展示

---

3. application - 应用程序版本表

功能描述: 管理移动端应用的版本信息，支持强制更新和热更新策略。

集合名: application

字段名	类型	描述
_id	ObjectID	MongoDB主键
platform	string	目标平台(iOS/Android/Web)
version	string	应用版本号
url	string	安装包下载地址
text	string	版本更新说明
force_update	bool	是否强制更新
latest	bool	是否为最新版本
hot_update	bool	是否支持热更新
create_time	time.Time	版本发布时间

索引设计:

• platform + version: 复合唯一索引
• latest: 布尔索引，快速查询最新版本

业务场景:

• 应用版本发布
• 客户端更新策略
• 平台版本管理

---

4. client_config - 客户端配置表

功能描述: 存储客户端的动态配置参数，支持热配置更新。

集合名: client_config

字段名	类型	描述
key	string	配置项键名(唯一)
value	string	配置项值

索引设计:

• key: 唯一索引

业务场景:

• 客户端功能开关
• 动态参数配置
• 运营活动配置

---

5. forbidden_account - 封禁账户表

功能描述: 管理被封禁的用户账户，记录封禁原因和操作记录。

集合名: forbidden_account

字段名	类型	描述
user_id	string	被封禁用户ID(唯一)
reason	string	封禁原因说明
operator_user_id	string	执行封禁的管理员ID
create_time	time.Time	封禁执行时间
ex	string	附加信息

索引设计:

• user_id: 唯一索引

业务场景:

• 用户账户封禁
• 违规行为处理
• 封禁记录追踪

---

6. invitation_register - 邀请码注册表

功能描述: 管理邀请码系统，跟踪邀请关系和使用状态。

集合名: invitation_register

字段名	类型	描述
invitation_code	string	邀请码(唯一)
user_id	string	邀请码创建者用户ID
used_by_user_id	string	使用邀请码的用户ID
create_time	time.Time	邀请码创建时间
used_time	time.Time	邀请码使用时间

索引设计:

• invitation_code: 唯一索引

业务场景:

• 邀请码生成分发
• 注册邀请关系
• 推广效果统计

---

7. ip_forbidden - IP封禁表

功能描述: 管理IP地址的访问控制策略，支持细粒度的限制规则。

集合名: ip_forbidden

字段名	类型	描述
ip	string	IP地址(唯一)
limit_register	int32	限制注册(0-允许,1-禁止)
limit_login	int32	限制登录(0-允许,1-禁止)
create_time	time.Time	规则创建时间
ex	string	扩展信息

索引设计:

• ip: 唯一索引

业务场景:

• IP黑名单管理
• 恶意访问防护
• 地域访问控制

---

8. limit_user_login_ip - 用户登录IP限制表

功能描述: 限制特定用户只能从指定IP地址登录，增强账户安全。

集合名: limit_user_login_ip

字段名	类型	描述
user_id	string	受限用户ID
ip	string	允许登录的IP地址
create_time	time.Time	限制规则创建时间
ex	string	扩展信息

索引设计:

• user_id + ip: 复合唯一索引

业务场景:

• 用户IP白名单
• 高级账户安全
• 企业用户管理

---

9. register_add_friend - 注册默认好友表

功能描述: 配置新用户注册时自动添加的默认好友列表。

集合名: register_add_friend

字段名	类型	描述
user_id	string	默认好友用户ID(唯一)
create_time	time.Time	配置创建时间
ex	string	扩展信息

索引设计:

• user_id: 唯一索引

业务场景:

• 新用户引导
• 默认好友配置
• 运营活动支持

---

10. register_add_group - 注册默认群组表

功能描述: 配置新用户注册时自动加入的默认群组列表。

集合名: register_add_group

字段名	类型	描述
group_id	string	默认群组ID(唯一)
create_time	time.Time	配置创建时间
ex	string	扩展信息

索引设计:

• group_id: 唯一索引

业务场景:

• 新用户群组引导
• 官方群组推广
• 社区建设支持

---

🤖 Bot模块 - 智能机器人数据表

11. agent - 智能代理表

功能描述: 存储AI智能代理的配置信息和服务状态。

集合名: agent

字段名	类型	描述
user_id	string	代理关联用户ID(唯一)
nickname	string	代理显示昵称
face_url	string	代理头像URL
description	string	代理功能描述
key	string	API访问密钥
status	int32	服务状态(1-启用,0-禁用)
create_time	time.Time	代理创建时间
ex	string	扩展配置参数

索引设计:

• user_id: 唯一索引

业务场景:

• AI代理服务管理
• 智能客服配置
• 机器人功能开关

---

12. conversation_resp_id - 对话响应ID表

功能描述: 记录AI代理在不同会话中的响应状态，维护对话上下文。

集合名: conversation_resp_id

字段名	类型	描述
conversation_id	string	会话ID
agent_id	string	代理ID
last_resp_id	string	最后响应消息ID
create_time	time.Time	记录创建时间

索引设计:

• conversation_id + agent_id: 复合唯一索引

业务场景:

• AI对话上下文管理
• 响应状态跟踪
• 会话连续性保证

---

💬 Chat模块 - 聊天系统数据表

13. account - 用户账户表

功能描述: 存储用户的登录凭证信息，支持密码验证和安全管理。

集合名: account

字段名	类型	描述
user_id	string	用户ID(唯一标识)
password	string	登录密码(加密存储)
change_time	time.Time	密码最后修改时间
create_time	time.Time	账户创建时间

索引设计:

• user_id: 唯一索引

业务场景:

• 用户密码验证
• 账户安全管理
• 登录凭证存储

---

14. attribute - 用户属性表

功能描述: 存储用户的详细个人信息和偏好设置，支持多维度用户画像。

集合名: attribute

字段名	类型	描述
user_id	string	用户ID(唯一)
account	string	用户账号
phone_number	string	手机号码
area_code	string	国家/地区码
email	string	邮箱地址
nickname	string	用户昵称
face_url	string	用户头像URL
gender	int32	性别(0-未知,1-男,2-女)
birth	time.Time	出生日期
level	int32	用户等级
allow_add_friend	int32	允许添加好友
allow_beep	int32	允许提示音
allow_vibration	int32	允许震动
global_recv_msg_opt	int32	全局消息接收选项
register_type	int32	注册方式类型

索引设计:

• user_id: 唯一索引
• account: 普通索引
• email: 普通索引
• area_code + phone_number: 复合索引

业务场景:

• 用户个人信息管理
• 多维度用户搜索
• 隐私设置控制

---

15. credential - 登录凭证表

功能描述: 统一管理用户的多种登录凭证(手机、邮箱、账号)，支持多渠道登录。

集合名: credential

字段名	类型	描述
user_id	string	用户ID
account	string	凭证账号(唯一)
type	int32	凭证类型(1-手机,2-邮箱,3-账号)
allow_change	bool	是否允许修改

索引设计:

• user_id + type: 复合唯一索引
• account: 唯一索引

业务场景:

• 多渠道登录支持
• 凭证唯一性保证
• 登录方式管理

---

16. register - 用户注册表

功能描述: 记录用户的注册信息和设备信息，用于安全审计和数据分析。

集合名: register

字段名	类型	描述
user_id	string	用户ID(唯一)
device_id	string	注册设备ID
ip	string	注册IP地址
platform	string	注册平台
account_type	string	账户类型
mode	int32	注册方式
create_time	time.Time	注册时间

索引设计:

• user_id: 唯一索引

业务场景:

• 用户注册记录
• 设备信息统计
• 注册来源分析

---

17. user_login_record - 用户登录记录表

功能描述: 记录用户的登录历史，支持安全监控和行为分析。

集合名: user_login_record

字段名	类型	描述
user_id	string	用户ID
login_time	time.Time	登录时间
ip	string	登录IP地址
device_id	string	登录设备ID
platform	string	登录平台

索引设计:

• user_id: 普通索引
• login_time: 时间索引，支持时间范围查询

业务场景:

• 登录行为分析
• 异常登录检测
• 用户活跃度统计

---

18. verify_code - 验证码表

功能描述: 管理短信和邮箱验证码，支持防刷机制和使用控制。

集合名: verify_code

字段名	类型	描述
_id	ObjectID	MongoDB主键
account	string	验证目标(手机号/邮箱)
platform	string	请求平台
code	string	验证码内容
duration	uint	有效期(秒)
count	int	验证尝试次数
used	bool	是否已使用
create_time	time.Time	创建时间

索引设计:

• account: 普通索引
• create_time: TTL索引，自动清理过期数据

业务场景:

• 短信/邮箱验证
• 防刷验证机制
• 验证码生命周期管理

---

📱 openim-sdk-core 项目数据库 (SQLite)

📋 表结构概览

openim-sdk-core使用SQLite作为客户端本地数据库，包含21个核心表，涵盖本地消息存储、会话管理、用户关系、离线数据等所有客户端功能。

---

👥 用户关系相关表

1. local_friends - 本地好友信息表

功能描述: 存储用户的好友关系和好友基本信息，支持离线查看好友列表。

表名: local_friends

字段名	类型	描述
owner_user_id	varchar(64)	好友关系拥有者用户ID(主键)
friend_user_id	varchar(64)	好友的用户ID(主键)
remark	varchar(255)	好友备注名
create_time	int64	创建时间戳
add_source	int32	添加好友的来源方式
operator_user_id	varchar(64)	操作者用户ID
nickname	varchar(255)	好友昵称
face_url	varchar(255)	好友头像URL
ex	varchar(1024)	扩展字段
attached_info	varchar(1024)	附加信息
is_pinned	bool	是否置顶好友

索引设计:

• 主键：owner_user_id + friend_user_id
• owner_user_id: 查询用户好友列表

业务场景:

• 离线好友列表展示
• 好友信息快速查询
• 好友备注管理

---

2. local_friend_requests - 本地好友申请记录表

功能描述: 存储发送和接收的好友申请记录，支持离线查看申请状态。

表名: local_friend_requests

字段名	类型	描述
from_user_id	varchar(64)	发送申请的用户ID(主键)
from_nickname	varchar(255)	发送者昵称
from_face_url	varchar(255)	发送者头像URL
to_user_id	varchar(64)	接收申请的用户ID(主键)
to_nickname	varchar(255)	接收者昵称
to_face_url	varchar(255)	接收者头像URL
handle_result	int32	处理结果(0-未处理,1-同意,-1-拒绝)
req_msg	varchar(255)	申请消息
create_time	int64	创建时间戳
handler_user_id	varchar(64)	处理者用户ID
handle_msg	varchar(255)	处理消息
handle_time	int64	处理时间戳
ex	varchar(1024)	扩展字段
attached_info	varchar(1024)	附加信息

索引设计:

• 主键：from_user_id + to_user_id

业务场景:

• 好友申请记录管理
• 申请状态跟踪
• 离线申请处理

---

3. local_blacks - 本地黑名单表

功能描述: 存储用户的黑名单信息，支持离线黑名单管理。

表名: local_blacks

字段名	类型	描述
owner_user_id	varchar(64)	黑名单拥有者用户ID(主键)
block_user_id	varchar(64)	被拉黑的用户ID(主键)
nickname	varchar(255)	被拉黑用户昵称
face_url	varchar(255)	被拉黑用户头像URL
create_time	int64	创建时间戳
add_source	int32	添加来源
operator_user_id	varchar(64)	操作者用户ID
ex	varchar(1024)	扩展字段
attached_info	varchar(1024)	附加信息

索引设计:

• 主键：owner_user_id + block_user_id

业务场景:

• 黑名单管理
• 消息发送权限检查
• 离线黑名单查询

---

👨‍👩‍👧‍👦 群组相关表

4. local_groups - 本地群组信息表

功能描述: 存储用户所在群组的基本信息，支持离线群组管理。

表名: local_groups

字段名	类型	描述
group_id	varchar(64)	群组ID(主键)
group_name	varchar(255)	群组名称
notification	varchar(255)	群公告
introduction	varchar(255)	群介绍
face_url	varchar(255)	群头像URL
create_time	int64	创建时间戳
status	int32	群状态
creator_user_id	varchar(64)	创建者用户ID
group_type	int32	群类型
owner_user_id	varchar(64)	群主用户ID
member_count	int32	群成员数量
ex	varchar(1024)	扩展字段
attached_info	varchar(1024)	附加信息
need_verification	int32	是否需要验证入群
look_member_info	int32	是否可以查看成员信息
apply_member_friend	int32	是否可以申请成员为好友
notification_update_time	int64	群公告更新时间
notification_user_id	varchar(64)	群公告更新者ID

索引设计:

• 主键：group_id

业务场景:

• 群组信息展示
• 群组列表管理
• 离线群组查询

---

5. local_group_members - 本地群成员信息表

功能描述: 存储群组成员的详细信息和权限，支持离线成员列表查看。

表名: local_group_members

字段名	类型	描述
group_id	varchar(64)	群组ID(主键)
user_id	varchar(64)	成员用户ID(主键)
nickname	varchar(255)	成员昵称
face_url	varchar(255)	成员头像URL
role_level	int32	角色等级(1-普通成员,2-管理员,3-群主)
join_time	int64	加入群组时间戳
join_source	int32	加入来源
inviter_user_id	varchar(64)	邀请者用户ID
mute_end_time	int64	禁言结束时间戳
operator_user_id	varchar(64)	操作者用户ID
ex	varchar(1024)	扩展字段
attached_info	varchar(1024)	附加信息

索引设计:

• 主键：group_id + user_id
• role_level: 按角色查询
• join_time: 按加入时间排序

业务场景:

• 群成员列表展示
• 成员权限管理
• 离线成员信息查询

---

6. local_group_requests - 本地群组申请记录表

功能描述: 存储群组加入申请的记录信息，支持离线申请管理。

表名: local_group_requests

字段名	类型	描述
group_id	varchar(64)	群组ID(主键)
group_name	varchar(255)	群组名称
notification	varchar(255)	群公告
introduction	varchar(255)	群介绍
group_face_url	varchar(255)	群头像URL
create_time	int64	创建时间戳
status	int32	群状态
creator_user_id	varchar(64)	创建者用户ID
group_type	int32	群类型
owner_user_id	varchar(64)	群主用户ID
member_count	int32	群成员数量
user_id	varchar(64)	申请者用户ID(主键)
nickname	varchar(255)	申请者昵称
user_face_url	varchar(255)	申请者头像URL
handle_result	int32	处理结果(0-未处理,1-同意,-1-拒绝)
req_msg	varchar(255)	申请消息
handled_msg	varchar(255)	处理消息
req_time	int64	申请时间戳
handle_user_id	varchar(64)	处理者用户ID
handled_time	int64	处理时间戳
ex	varchar(1024)	扩展字段
attached_info	varchar(1024)	附加信息
join_source	int32	加入来源
inviter_user_id	varchar(64)	邀请者用户ID

索引设计:

• 主键：group_id + user_id

业务场景:

• 群组申请记录
• 申请状态管理
• 离线申请处理

---

💬 消息和会话相关表

7. local_chat_logs - 本地聊天记录表

功能描述: 存储所有的聊天消息记录，是消息存储的核心表，支持离线消息查看。

表名: local_chat_logs

字段名	类型	描述
client_msg_id	char(64)	客户端消息ID(主键)
server_msg_id	char(64)	服务端消息ID
send_id	char(64)	发送者用户ID
recv_id	char(64)	接收者ID(用户ID或群组ID)
sender_platform_id	int32	发送者平台ID
sender_nickname	varchar(255)	发送者昵称
sender_face_url	varchar(255)	发送者头像URL
session_type	int32	会话类型(1-单聊,2-群聊)
msg_from	int32	消息来源(100-用户发送,200-系统通知)
content_type	int32	消息内容类型(101-文本,102-图片等)
content	varchar(1000)	消息内容JSON字符串
is_read	bool	是否已读
status	int32	消息状态(1-发送中,2-发送成功,3-发送失败)
seq	int64	消息序列号
send_time	int64	发送时间戳
create_time	int64	创建时间戳
attached_info	varchar(1024)	附加信息
ex	varchar(1024)	扩展字段
local_ex	varchar(1024)	本地扩展字段

索引设计:

• 主键：client_msg_id
• recv_id: 查询会话消息
• content_type: 按消息类型筛选
• seq: 消息排序
• send_time: 按时间排序

业务场景:

• 消息历史记录查看
• 离线消息存储
• 消息搜索和筛选

---

8. local_conversations - 本地会话表

功能描述: 存储用户的所有会话信息，包括单聊和群聊会话的状态和配置。

表名: local_conversations

字段名	类型	描述
conversation_id	char(128)	会话ID(主键)
conversation_type	int32	会话类型(1-单聊,2-群聊)
user_id	char(64)	单聊对方用户ID
group_id	char(128)	群聊群组ID
show_name	varchar(255)	会话显示名称
face_url	varchar(255)	会话头像URL
recv_msg_opt	int32	接收消息选项(0-正常,1-不接收,2-接收不提醒)
unread_count	int32	未读消息数量
group_at_type	int32	群组@类型(0-无@,1-@所有人,2-@我)
latest_msg	varchar(1000)	最新消息内容JSON字符串
latest_msg_send_time	int64	最新消息发送时间戳
draft_text	text	草稿文本内容
draft_text_time	int64	草稿文本时间戳
is_pinned	bool	是否置顶会话
is_private_chat	bool	是否为私聊(阅后即焚)
burn_duration	int32	阅后即焚时长(秒)
is_not_in_group	bool	是否不在群组中(已退群但保留会话)
update_unread_count_time	int64	未读数更新时间戳
attached_info	varchar(1024)	附加信息
ex	varchar(1024)	扩展字段
max_seq	int64	会话最大消息序列号
min_seq	int64	会话最小消息序列号
msg_destruct_time	int64	消息销毁时间(秒)
is_msg_destruct	bool	是否开启消息销毁

索引设计:

• 主键：conversation_id
• latest_msg_send_time: 按最新消息时间排序

业务场景:

• 会话列表展示
• 未读消息统计
• 会话配置管理

---

9. local_conversation_unread_messages - 本地会话未读消息表

功能描述: 存储每个会话中的未读消息记录，用于未读消息管理和提醒。

表名: local_conversation_unread_messages

字段名	类型	描述
conversation_id	char(128)	会话ID(主键)
client_msg_id	char(64)	未读消息的客户端ID(主键)
send_time	int64	消息发送时间戳
ex	varchar(1024)	扩展字段

索引设计:

• 主键：conversation_id + client_msg_id

业务场景:

• 未读消息精确管理
• 未读消息快速定位
• 已读状态同步

---

👤 用户相关表

10. local_users - 本地用户信息表

功能描述: 存储当前登录用户的基本信息和设置。

表名: local_users

字段名	类型	描述
user_id	varchar(64)	用户ID(主键)
nickname	varchar(255)	用户昵称
face_url	varchar(255)	用户头像URL
create_time	int64	创建时间戳
app_manger_level	int32	应用管理员等级
ex	varchar(1024)	扩展字段
attached_info	varchar(1024)	附加信息
global_recv_msg_opt	int32	全局接收消息选项

索引设计:

• 主键：user_id

业务场景:

• 当前用户信息展示
• 用户设置管理
• 本地用户数据缓存

---

11. local_stranger - 本地陌生人信息表

功能描述: 存储与当前用户有过交互但非好友的用户信息，用于快速展示用户资料。

表名: local_stranger

字段名	类型	描述
user_id	varchar(64)	陌生人用户ID(主键)
nickname	varchar(255)	陌生人昵称
face_url	varchar(255)	陌生人头像URL
create_time	int64	创建时间戳
app_manger_level	int32	应用管理员等级
ex	varchar(1024)	扩展字段
attached_info	varchar(1024)	附加信息
global_recv_msg_opt	int32	全局接收消息选项

索引设计:

• 主键：user_id

业务场景:

• 陌生人信息缓存
• 快速用户资料展示
• 减少网络请求

---

🔄 同步和序列号相关表

12. local_seq_data - 本地序列号数据表

功能描述: 存储用户消息序列号信息，用于消息同步和增量更新。

表名: local_seq_data

字段名	类型	描述
user_id	varchar(64)	用户ID(主键)
seq	uint32	消息序列号

索引设计:

• 主键：user_id

业务场景:

• 消息增量同步
• 断线重连恢复
• 消息去重处理

---

13. local_seqs - 本地序列号表

功能描述: 存储会话的最小序列号信息，用于消息范围管理。

表名: local_seqs

字段名	类型	描述
id	varchar(64)	会话ID(主键)
min_seq	uint32	最小序列号

索引设计:

• 主键：id

业务场景:

• 消息范围控制
• 历史消息清理
• 存储空间优化

---

14. local_notification_seqs - 通知序列号表

功能描述: 存储各会话的通知消息序列号，用于系统通知管理。

表名: local_notification_seqs

字段名	类型	描述
conversation_id	char(128)	会话ID(主键)
seq	int64	通知序列号

索引设计:

• 主键：conversation_id

业务场景:

• 系统通知管理
• 通知消息同步
• 通知状态跟踪

---

15. local_sync_version - 本地版本同步表

功能描述: 存储数据同步的版本信息，用于增量同步和冲突解决。

表名: local_sync_version

字段名	类型	描述
table_name	varchar(255)	表名(主键)
entity_id	varchar(255)	实体ID(主键)
version_id	varchar(255)	版本ID
version	uint64	版本号
create_time	int64	创建时间戳
uid_list	text	用户ID列表(JSON格式)

索引设计:

• 主键：table_name + entity_id

业务场景:

• 数据版本控制
• 增量同步优化
• 冲突检测和解决

---

📁 文件和上传相关表

16. local_uploads - 本地上传记录表

功能描述: 存储文件上传的临时信息，用于断点续传和上传管理。

表名: local_uploads

字段名	类型	描述
part_hash	varchar(255)	文件分片哈希值(主键)
upload_id	varchar(1000)	上传任务ID
upload_info	varchar(2000)	上传信息JSON字符串
expire_time	int64	过期时间戳
create_time	int64	创建时间戳

索引设计:

• 主键：part_hash

业务场景:

• 文件断点续传
• 上传进度管理
• 临时文件清理

---

🔧 扩展功能表

17. local_admin_group_requests - 本地管理员群组申请表

功能描述: 继承自群组申请表，用于管理员处理群组申请，支持管理功能扩展。

表名: local_admin_group_requests

说明: 结构同 local_group_requests，用于管理员视角的群组申请处理。

业务场景:

• 管理员群组审核
• 批量申请处理
• 管理权限控制

---

18. local_chat_log_reaction_extensions - 本地聊天记录反应扩展表

功能描述: 存储消息的表情回复、点赞等反应信息，支持丰富的消息交互。

表名: local_chat_log_reaction_extensions

字段名	类型	描述
client_msg_id	char(64)	消息客户端ID(主键)
local_reaction_extensions	blob	本地反应扩展数据(二进制存储)

索引设计:

• 主键：client_msg_id

业务场景:

• 消息表情回复
• 消息互动功能
• 反应数据管理

---

19. local_sending_messages - 本地发送中消息表

功能描述: 存储正在发送中的消息记录，用于重发和状态跟踪。

表名: local_sending_messages

字段名	类型	描述
conversation_id	char(128)	会话ID(主键)
client_msg_id	char(64)	客户端消息ID(主键)
ex	varchar(1024)	扩展字段

索引设计:

• 主键：conversation_id + client_msg_id

业务场景:

• 发送状态管理
• 消息重发机制
• 发送失败处理

---

📋 系统管理表

20. local_app_sdk_version - 本地应用SDK版本表

功能描述: 记录已安装的SDK版本信息，用于版本管理和升级控制。

表名: local_app_sdk_version

字段名	类型	描述
version	varchar(255)	SDK版本号(主键)
installed	bool	是否已安装标记

索引设计:

• 主键：version

业务场景:

• SDK版本管理
• 升级兼容性检查
• 版本回滚支持

---

21. local_table_master - 表管理器

功能描述: 管理本地数据库表的创建和版本信息，支持数据库结构升级。

表名: local_table_master

说明: 系统内部表，用于数据库结构管理和版本控制。

业务场景:

• 数据库结构管理
• 表版本控制
• 数据库升级支持

---

🔧 数据库设计总结

📊 架构特点分析

1. 分层存储架构

OpenIM采用了三层数据存储架构：

graph TB
    subgraph "服务端存储层"
        A[open-im-server<br/>MongoDB<br/>业务核心数据]
        B[chat<br/>MongoDB<br/>管理和用户数据]
    end
    
    subgraph "客户端存储层"
        C[openim-sdk-core<br/>SQLite<br/>本地缓存数据]
    end
    
    A -.->|数据同步| C
    B -.->|用户数据| C
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8

2. 数据分离设计

• open-im-server: 核心IM业务数据，高并发读写
• chat: 管理系统和扩展功能，低频管理操作
• openim-sdk-core: 客户端缓存，离线体验优化

3. 存储技术选型

项目	数据库	选型原因
open-im-server	MongoDB	文档型存储，适合消息数据；水平扩展能力强
chat	MongoDB	灵活的模式设计；快速开发迭代
openim-sdk-core	SQLite	轻量级；事务支持；离线可用

---

🚀 技术亮点

1. 消息分片存储

open-im-server的消息存储采用创新的分片策略：

文档ID格式: {会话ID}:{分片索引}
每个文档: 100条消息
分片计算: (seq - 1) / 100

优势:

• 查询性能优化：避免单个文档过大
• 并发写入支持：不同分片可并行写入
• 存储空间优化：按需加载历史消息

2. 序列号机制

三级序列号管理体系：

1. 全局序列号 (SeqConversation): 会话消息全局顺序
2. 用户序列号 (SeqUser): 用户视角的消息同步点
3. 本地序列号 (local_seq_data): 客户端同步状态

3. 版本控制系统

实现了完整的数据版本管理：

• VersionLog: 服务端数据变更追踪
• local_sync_version: 客户端版本状态
• 增量同步: 基于版本号的高效数据同步

4. 多渠道认证

chat项目实现了统一的多渠道登录：

credential表设计:
- type=1: 手机号登录
- type=2: 邮箱登录  
- type=3: 账号登录

5. 离线优先设计

openim-sdk-core实现完整的离线功能：

• 本地完整数据: 用户、好友、群组、消息全量缓存
• 离线操作: 支持离线查看、搜索、草稿保存
• 智能同步: 上线后自动增量同步

---

🔄 数据流向分析

用户注册流程

sequenceDiagram
    participant U as 用户
    participant C as Chat系统
    participant S as IM核心
    participant L as 本地存储
    
    U->>C: 注册请求
    C->>C: verify_code验证
    C->>C: 创建credential记录
    C->>C: 创建account+attribute
    C->>S: 同步用户信息到User表
    S->>L: 同步到local_users
    C->>C: 注册到register_add_friend/group

消息发送流程

sequenceDiagram
    participant A as 发送方
    participant L1 as 本地存储
    participant S as IM服务端
    participant L2 as 接收方本地
    participant B as 接收方
    
    A->>L1: 保存到local_chat_logs
    A->>S: 发送消息
    S->>S: 保存到MsgDocModel
    S->>S: 更新SeqUser/SeqConversation
    S->>L2: 推送到接收方
    L2->>L2: 保存到local_chat_logs
    L2->>B: 通知新消息

数据同步流程

graph LR
    A[客户端启动] --> B[检查版本号]
    B --> C{需要同步?}
    C -->|是| D[增量拉取]
    C -->|否| E[使用本地数据]
    D --> F[更新本地版本]
    F --> G[合并到本地数据库]
    G --> E

---

📈 性能优化策略

1. 索引设计优化

每个项目都精心设计了索引策略：

• 唯一性约束: 防止数据重复
• 复合索引: 优化多字段查询
• 时间索引: 支持时间范围查询
• TTL索引: 自动数据清理

2. 查询优化

• 分页查询: 避免大数据量一次性加载
• 字段投影: 只查询必要字段
• 索引覆盖: 查询完全使用索引
• 查询计划: 优化复杂查询逻辑

3. 存储优化

• 数据压缩: 消息内容JSON压缩
• 冗余设计: 适当冗余提升查询性能
• 分片策略: 数据水平拆分
• 缓存层: 多级缓存加速访问

---

🔒 数据安全设计

1. 访问控制

• IP黑白名单: ip_forbidden表实现IP级别控制
• 用户封禁: forbidden_account表管理违规用户
• 权限分级: admin表支持多级管理员权限

2. 数据加密

• 密码加密: BCrypt哈希存储
• 敏感信息: 关键字段加密存储
• 传输加密: TLS/SSL协议保护

3. 审计追踪

• 操作记录: 记录关键操作的操作者信息
• 登录日志: user_login_record完整记录登录行为
• 版本控制: VersionLog追踪数据变更历史

---

📊 数据统计能力

1. 用户行为分析

• 注册统计: register表支持注册来源分析
• 活跃统计: user_login_record支持活跃度分析
• 平台分布: 多平台使用情况统计

2. 消息统计

• 消息量统计: 基于seq序列号的精确计数
• 类型分布: content_type字段支持消息类型统计
• 时间分析: send_time支持时间维度分析

3. 系统监控

• 系统日志: log表记录系统运行状态
• 错误追踪: 基于日志的错误分析
• 性能监控: 查询性能和存储使用率监控

---

🎯 设计原则总结

1. 可扩展性

• 预留字段: 大部分表包含ex扩展字段
• 模块化: 功能模块独立设计
• 版本兼容: 向后兼容的版本升级机制

2. 高可用性

• 数据备份: MongoDB副本集支持
• 故障恢复: 基于序列号的断点续传
• 降级策略: 离线模式保证基本可用

3. 高性能

• 分片存储: 消息按会话和时间分片
• 索引优化: 针对查询模式的精确索引
• 缓存设计: 多级缓存减少数据库压力

4. 数据一致性

• 最终一致性: 分布式环境下的数据同步
• 版本控制: 冲突检测和自动合并
• 事务支持: 关键操作的事务保证

---

📚 总结

OpenIM的数据库架构展现了现代IM系统的完整设计思路：

架构优势

1. 分层清晰: 服务端业务数据与客户端缓存分离
2. 技术合理: 根据使用场景选择合适的存储引擎
3. 性能优秀: 消息分片、索引优化、缓存设计
4. 扩展性强: 模块化设计支持功能扩展
5. 安全可靠: 完整的安全策略和审计机制

创新特点

1. 消息分片存储: 创新的文档分片策略
2. 三级序列号: 完整的消息同步机制
3. 版本控制: 数据变更的精确追踪
4. 离线优先: 完整的离线使用体验
5. 多渠道认证: 统一的登录凭证管理

适用场景

• 企业级IM: 完整的管理功能和安全控制
• 社交应用: 丰富的用户关系和群组功能
• 客服系统: AI机器人和智能代理支持
• 移动应用: 离线优先的移动端体验

这套数据库架构既满足了当前的业务需求，又为未来的功能扩展和性能优化预留了充足的空间，是一个成熟、可靠的企业级即时通讯数据库解决方案。

---