Teamgram Database Schema

Complete database schema reference for Teamgram Server with all 43 tables, ER relationships, and key table structure explanations for the MySQL teamgram database.

数据库 Schema（43 张表）与核心关系

概述

数据库位于 teamgramd/deploy/sql/，基础 schema 在 1_teamgram.sql（38 表），迁移补齐到 43 表。

所有服务共用同一个 MySQL 数据库 teamgram，字符集 utf8mb4。

43 张表完整列表

表名	核心用途
auth_key_infos	auth_key 元信息
auth_keys	auth_key 存储（加密密钥）
auth_seq_updates	每个 auth_key 的 updates 序列号
auth_users	auth_key ↔ user 绑定关系
auths	授权记录
bot_commands	Bot 命令列表
bots	Bot 信息
chat_invite_participants	通过邀请链接加入的成员
chat_invites	聊天邀请链接
chat_participants	群成员关系
chats	群组信息
default_history_ttl	默认历史消息 TTL
devices	推送设备/token
dialog_filters	对话文件夹
dialogs	对话列表（每用户每对等方一行）
documents	文件/文档元数据
drafts	消息草稿
encrypted_files	加密文件
hash_tags	消息 hashtag 索引
imported_contacts	导入的联系人
message_read_outbox	消息已读状态（outbox 侧）
messages	消息存储（核心表）
phone_books	通讯录
photo_sizes	照片尺寸变体
photos	照片元数据
popular_contacts	热门联系人
predefined_users	预定义用户
saved_dialogs	保存的消息对话
unregistered_contacts	未注册联系人
user_contacts	用户联系人关系
user_global_privacy_settings	全局隐私设置
user_notify_settings	通知设置
user_peer_blocks	屏蔽关系
user_peer_settings	对等方设置
user_presences	用户最后上线时间
user_privacies	隐私规则
user_profile_photos	用户头像
user_pts_updates	每用户 pts 更新序列
user_saved_music	保存的音乐
user_settings	用户设置
username	用户名
users	用户信息（核心表）
video_sizes	视频尺寸变体

核心 ER 关系

text

users (user_id)
  |\
  | \-- auth_users (auth_key_id -> user_id)      # 登录设备/授权关系
  | \-- devices (auth_key_id, user_id)           # push token / device
  | \-- user_presences (user_id)                 # last seen
  | \-- user_profile_photos (user_id -> photo_id)
  | \-- user_settings / user_privacies / user_notify_settings
  |
  \-- dialogs (user_id, peer_type, peer_id)      # 会话列表
        |
        \-- messages (user_id, peer_type, peer_id, dialog_id1/2, dialog_message_id)
              |
              \-- documents/photos/encrypted_files (+ photo_sizes/video_sizes)

chats (chat_id)
  \-- chat_participants (chat_id, user_id)
  \-- chat_invites / chat_invite_participants

关键表结构说明

users 表

• 核心用户信息表
• user_id 为主键（Snowflake ID）
• 包含 phone、first_name、last_name、username 等字段
• deleted 字段标记软删除

messages 表

• 消息存储核心表
• 按 user_id + peer 维度存储（inbox/outbox 双写）
• dialog_id1/dialog_id2 用于双向对话定位
• dialog_message_id 为对话内消息序号（递增）
• message_type 区分文本/媒体/服务消息等

dialogs 表

• 每个用户与每个对等方（私聊/群聊）一行
• peer_type: 1=user, 2=chat, 3=channel
• 包含 unread_count、read_inbox_max_id、read_outbox_max_id
• pinned 字段控制置顶排序

auth_keys / auth_users 表

• auth_keys 存储 MTProto 授权密钥（256字节 auth_key）
• auth_users 维护 auth_key_id → user_id 的绑定
• 一个用户可以有多个 auth_key（多设备登录）
• auth_key_id 是 auth_key 的 SHA1 后 8 字节

chat_participants 表

• chat_id + user_id 复合主键
• participant_type 区分普通成员/管理员/创建者
• inviter_user_id 记录邀请人
• joined_at 记录加入时间

SQL 文件路径

• 基础 schema：teamgramd/deploy/sql/1_teamgram.sql
• 迁移脚本：teamgramd/deploy/sql/ 下的后续编号文件

Source Code References

• Repository: https://github.com/teamgram/teamgram-server (Apache-2.0)