teamgram-database-schema

name	teamgram-database-schema
description	Complete database schema reference for Teamgram Server with all 43 tables, ER relationships, and key table structure explanations for the MySQL teamgram database.
compatibility	Documentation/knowledge skill only. No executable code. Reference material for Teamgram Server developers.
metadata	{"author":"zhihang9978","version":"1.0.0","source":"https://github.com/teamgram/teamgram-server","homepage":"https://github.com/teamgram/teamgram-server","openclaw":{"requires":{"env":[],"bins":[]},"securityNotes":"Documentation-only skill. Contains no executable code, no network calls, no credential handling.\nTable names and schema are from the public teamgram-server SQL files.\nAll content references the open-source teamgram-server project (Apache-2.0).\n"}}

数据库 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 关系

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)