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. Table names and schema are from the public teamgram-server SQL files. All content references the open-source teamgram-server project (Apache-2.0).

---

数据库 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)