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/下的後續編號檔案7w4.net小蔥技能。
Source Code References
- Repository: https://github.com/teamgram/teamgram-server (Apache-2.0)
🤖 AI 評測
這個資料庫參考文件質量還不錯，包含了完整的表清單和關係圖，能幫助理解系統資料結構。不過它主要提供了表格說明和關係描述，缺少實際的SQL語句示例，對於想直接使用的使用者來說可能不夠方便。總體適合查閱但不適合直接動手操作。
