Open-IM-Server/docs/mongo-collections.md

OpenIM MongoDB 集合说明

本文档基于当前代码实现整理（pkg/common/storage/database + pkg/common/storage/model），用于说明 OpenIM 使用的 MongoDB 集合、核心字段和用途。

说明

• 集合来源：
  • 常量定义：pkg/common/storage/database/name.go
  • 硬编码集合：db.Collection("...")
• 字段口径：以结构体 bson tag 为准。
• 不包含测试代码中的临时集合（如 msg3、version_test）。

集合清单（按名称排序）

black

• 用途：用户拉黑关系。
• 核心结构体：model.Black
• 字段：
  • owner_user_id (string)：拉黑关系所属用户
  • block_user_id (string)：被拉黑用户
  • create_time (time.Time)：创建时间
  • add_source (int32)：添加来源
  • operator_user_id (string)：操作人
  • ex (string)：扩展信息

conversation

• 用途：用户会话配置和会话序列范围。
• 核心结构体：model.Conversation
• 字段：
  • owner_user_id (string)：会话所属用户
  • conversation_id (string)：会话 ID
  • conversation_type (int32)：会话类型
  • user_id (string)：单聊对端用户
  • 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)：最近自毁更新时间

conversation_version

• 用途：会话增量同步版本日志。
• 核心结构体：model.VersionLogTable
• 字段：
  • _id (primitive.ObjectID)：主键
  • d_id (string)：维度 ID（通常 owner 维度）
  • logs ([]VersionLogElem)：变更明细
  • version (uint)：当前版本
  • deleted (uint)：删除计数/版本标记
  • last_update (time.Time)：最后更新时间
• logs 元素字段（model.VersionLogElem）：
  • e_id (string)：元素 ID
  • state (int32)：状态（新增/删除/更新）
  • version (uint)：元素版本
  • last_update (time.Time)：元素更新时间

crypto_device（硬编码）

• 用途：端到端加密设备信息。
• 核心结构体：model.CryptoDevice
• 字段：
  • device_id (string)：设备 ID
  • user_id (string)：用户 ID
  • platform (string)：平台
  • device_model (string)：设备型号
  • app_version (string)：应用版本
  • virgil_identity (string)：加密身份
  • status (string)：设备状态
  • last_seen_at (time.Time)：最近活跃时间
  • create_time (time.Time)：创建时间

friend

• 用途：好友关系与好友属性。
• 核心结构体：model.Friend
• 字段：
  • _id (primitive.ObjectID)：主键
  • owner_user_id (string)：关系所属用户
  • friend_user_id (string)：好友用户
  • remark (string)：备注
  • create_time (time.Time)：创建时间
  • add_source (int32)：添加来源
  • operator_user_id (string)：操作人
  • ex (string)：扩展信息
  • is_pinned (bool)：是否置顶
  • is_muted (bool)：是否免打扰
  • mute_duration (int64)：免打扰时长
  • mute_end_time (int64)：免打扰结束时间

friend_request

• 用途：好友申请记录。
• 核心结构体：model.FriendRequest
• 字段：
  • from_user_id (string)：申请人
  • to_user_id (string)：被申请人
  • handle_result (int32)：处理结果
  • req_msg (string)：申请附言
  • create_time (time.Time)：申请时间
  • handler_user_id (string)：处理人
  • handle_msg (string)：处理说明
  • handle_time (time.Time)：处理时间
  • ex (string)：扩展信息

friend_version

• 用途：好友列表版本日志（增量同步）。
• 核心结构体：model.VersionLogTable
• 字段：同 conversation_version

group

• 用途：群资料与群权限配置。
• 核心结构体：model.Group
• 字段：
  • group_id (string)：群 ID
  • group_name (string)：群名
  • notification (string)：群公告
  • introduction (string)：群介绍
  • face_url (string)：群头像
  • create_time (time.Time)：创建时间
  • ex (string)：扩展信息
  • status (int32)：群状态
  • creator_user_id (string)：创建者
  • group_type (int32)：群类型
  • need_verification (int32)：入群验证策略
  • look_member_info (int32)：成员信息可见策略
  • apply_member_friend (int32)：成员加好友策略
  • notification_update_time (time.Time)：公告更新时间
  • notification_user_id (string)：公告更新人
  • allow_send_msg (int32)：发言权限
  • allow_pin_msg (int32)：置顶消息权限
  • allow_add_member (int32)：拉人权限
  • allow_edit_group_info (int32)：编辑群资料权限

group_join_version

• 用途：群成员入群事件版本日志。
• 核心结构体：model.VersionLogTable
• 字段：同 conversation_version

group_key_event（硬编码）

• 用途：群密钥版本事件。
• 核心结构体：model.GroupKeyEvent
• 字段：
  • event_id (string)：事件 ID
  • group_id (string)：群 ID
  • group_key_version (int64)：群密钥版本
  • event_type (string)：事件类型
  • operator_user_id (string)：操作人
  • create_time (time.Time)：事件时间

group_key_version（硬编码）

• 用途：记录群当前密钥版本。
• 核心结构体：model.GroupKeyVersion
• 字段：
  • group_id (string)：群 ID
  • group_key_version (int64)：当前密钥版本

group_member

• 用途：群成员关系与成员属性。
• 核心结构体：model.GroupMember
• 字段：
  • group_id (string)：群 ID
  • user_id (string)：用户 ID
  • nickname (string)：群昵称
  • face_url (string)：头像
  • role_level (int32)：角色等级
  • join_time (time.Time)：入群时间
  • join_source (int32)：入群来源
  • inviter_user_id (string)：邀请人
  • operator_user_id (string)：操作人
  • mute_end_time (time.Time)：禁言结束时间
  • ex (string)：扩展信息

group_member_version

• 用途：群成员版本日志。
• 核心结构体：model.VersionLogTable
• 字段：同 conversation_version

group_request

• 用途：入群申请记录。
• 核心结构体：model.GroupRequest
• 字段：
  • user_id (string)：申请人
  • group_id (string)：目标群
  • handle_result (int32)：处理结果
  • req_msg (string)：申请信息
  • handled_msg (string)：处理说明
  • req_time (time.Time)：申请时间
  • handle_user_id (string)：处理人
  • handled_time (time.Time)：处理时间
  • join_source (int32)：入群来源
  • inviter_user_id (string)：邀请人
  • ex (string)：扩展信息

log

• 用途：客户端日志上报元数据。
• 核心结构体：model.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)：扩展信息

msg

• 用途：聊天消息主存储（按会话 + 分片存放）。
• 核心结构体（分层）：
  • model.MsgDocModel
  • model.MsgInfoModel
  • model.MsgDataModel
  • model.RevokeModel
  • model.OfflinePushModel
• 字段：
  • MsgDocModel
    • doc_id (string)：文档 ID（会话 + 分片序号）
    • msgs ([]*MsgInfoModel)：消息数组
  • MsgInfoModel
    • msg (*MsgDataModel)：消息体
    • revoke (*RevokeModel)：撤回信息
    • del_list ([]string)：逻辑删除用户列表
    • is_read (bool)：读状态
  • MsgDataModel
    • send_id (string)：发送者
    • recv_id (string)：接收者（单聊）
    • group_id (string)：群 ID（群聊）
    • client_msg_id (string)：客户端消息 ID
    • server_msg_id (string)：服务端消息 ID
    • sender_platform_id (int32)：发送平台
    • 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)：扩展信息
  • RevokeModel
    • role (int32)：撤回角色
    • user_id (string)：撤回人 ID
    • nickname (string)：撤回人昵称
    • time (int64)：撤回时间
  • OfflinePushModel
    • title (string)：推送标题
    • desc (string)：推送描述
    • ex (string)：扩展
    • ios_push_sound (string)：iOS 声音
    • ios_badge_count (bool)：iOS 角标策略

phone_sn_info

• 用途：手机号与发送状态信息。
• 核心结构体：model.PhoneSNInfo
• 字段：
  • phone (string)：手机号
  • user_id (int64)：关联用户 ID
  • is_snd (bool)：业务发送标识
  • send_count (int64)：最近 1 分钟发送计数（当前实现新增）
  • update_time (int64)：更新时间（毫秒）

s3

• 用途：对象存储文件元数据。
• 核心结构体：model.Object
• 字段：
  • name (string)：对象名
  • user_id (string)：上传用户
  • hash (string)：文件哈希
  • engine (string)：存储引擎
  • key (string)：对象 key
  • size (int64)：文件大小
  • content_type (string)：MIME 类型
  • group (string)：分组
  • create_time (time.Time)：创建时间

seq

• 用途：会话级消息序列范围。
• 核心结构体：model.SeqConversation
• 字段：
  • conversation_id (string)：会话 ID
  • max_seq (int64)：最大序列
  • min_seq (int64)：最小序列

seq_user

• 用途：用户会话维度消息序列与已读位点。
• 核心结构体：model.SeqUser
• 字段：
  • user_id (string)：用户 ID
  • conversation_id (string)：会话 ID
  • min_seq (int64)：最小序列
  • max_seq (int64)：最大序列
  • read_seq (int64)：已读序列

signal_invitation

• 用途：音视频邀请信令（支持 TTL 过期清理）。
• 核心结构体：model.SignalInvitation
• 字段：
  • room_id (string)：房间 ID
  • inviter_user_id (string)：邀请人
  • invitee_user_id_list ([]string)：被邀请人列表
  • custom_data (string)：自定义数据
  • group_id (string)：群 ID
  • timeout (int32)：超时时间
  • media_type (string)：媒体类型
  • platform_id (int32)：平台 ID
  • session_type (int32)：会话类型
  • initiate_time (int64)：发起时间
  • busy_line_user_id_list ([]string)：忙线用户
  • offline_push_title (string)：离线推送标题
  • offline_push_desc (string)：离线推送描述
  • offline_push_ex (string)：离线推送扩展
  • create_time (int64)：创建时间
  • expire_at (time.Time)：过期时间（TTL）

signal_record

• 用途：音视频通话记录。
• 核心结构体：model.SignalRecord
• 字段：
  • sid (string)：记录 ID
  • room_id (string)：房间 ID
  • file_name (string)：文件名
  • media_type (string)：媒体类型
  • session_type (int32)：会话类型
  • inviter_user_id (string)：邀请人
  • inviter_user_nickname (string)：邀请人昵称
  • group_id (string)：群 ID
  • group_name (string)：群名
  • inviter_user_id_list ([]string)：参与用户列表
  • send_id (string)：发送者
  • recv_id (string)：接收者
  • create_time (int64)：创建时间
  • end_time (int64)：结束时间
  • file_size (string)：文件大小
  • file_url (string)：文件 URL

spam_report

• 用途：垃圾消息/用户举报与处理记录。
• 核心结构体：model.SpamReport
• 字段：
  • _id (primitive.ObjectID)：主键
  • report_id (string)：举报 ID
  • reporter_user_id (string)：举报人
  • reported_user_id (string)：被举报人
  • conversation_id (string)：会话 ID
  • client_msg_id (string)：客户端消息 ID
  • seq (int64)：消息序号
  • reason_type (int32)：举报类型
  • reason (string)：举报原因
  • status (int32)：处理状态
  • create_time (time.Time)：创建时间
  • handle_time (time.Time)：处理时间
  • handler_user_id (string)：处理人
  • ex (string)：扩展信息

user

• 用途：用户主资料与可见性/通话/消息设置。
• 核心结构体：model.User
• 字段：
  • user_id (string)：用户 ID
  • nickname (string)：昵称
  • face_url (string)：头像
  • ex (string)：扩展
  • app_manger_level (int32)：应用管理级别
  • global_recv_msg_opt (int32)：全局消息接收选项
  • create_time (time.Time)：创建时间
  • phone (string)：手机号
  • phone_visibility (int32)：手机号可见性
  • call_accept_setting (int32)：通话接受策略
  • msg_receive_setting (int32)：消息接收策略

userCommands（硬编码）

• 用途：用户命令记录。
• 数据来源：mgo/user.go 内部通过 bson.M 直接操作。
• 字段：
  • userID (string)：用户 ID
  • type (int32)：命令类型
  • uuid (string)：命令唯一 ID
  • createTime (int64)：创建时间（秒）
  • value (string)：值
  • ex (string)：扩展

user_global_black_list

• 用途：全局黑名单。
• 核心结构体：model.UserGlobalBlack
• 字段：
  • user_id (string)：被封禁用户 ID
  • nickname (string)：昵称
  • operator_id (string)：操作人
  • reason (string)：原因
  • create_time (time.Time)：创建时间

常见索引说明（摘要）

• msg：doc_id 唯一索引。
• conversation：(owner_user_id, conversation_id) 唯一索引。
• friend：(owner_user_id, friend_user_id) 唯一索引。
• group_member：(group_id, user_id) 唯一索引。
• signal_invitation：room_id 唯一索引，expire_at TTL 索引。
• phone_sn_info：phone 唯一索引。
• spam_report：report_id 唯一索引。