Teamgram 服务器架构

基于官方 teamgram/teamgram-server 仓库的完整架构指南。

⚠️ 免责声明与安全提示

本技能基于对开源项目 teamgram/teamgram-server 的分析整理，仅供学习参考。

重要提示:

• - 内容可能随官方仓库更新而过时，请以官方最新版本为准
• 生产环境使用前请自行验证所有配置和代码
• 部署配置中的密码、密钥等必须使用强密码并通过安全方式注入
• 建议直接参考官方文档: https://github.com/teamgram/teamgram-server
• 生产环境部署前请进行安全审计和渗透测试

概述

Teamgram 服务器是一个非官方的开源 Go 语言 MTProto 服务器实现，兼容 Telegram 客户端并支持自托管部署。

API 层: 223（截至技能创建时，请以官方仓库最新版本为准）
MTProto 版本: Abridged、Intermediate、Padded intermediate、Full

核心功能

• - ✅ 私聊 - 端到端加密消息
• ✅ 基础群组 - 小型群聊（最多 200 名成员）
• ⚠️ 超级群组 - 大型群组（需要额外实现）
• ✅ 联系人 - 联系人管理与同步
• ✅ Web - Web 客户端支持

服务架构

高层拓扑

┌─────────────────┐
│ 负载均衡器 │
│ (Nginx/HA) │
└────────┬────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
┌───────▼───────┐ ┌────────▼────────┐ ┌──────▼──────┐
│ gnetway │ │ httpserver │ │ session │
│ (TCP/MTProto)│ │ (HTTP API) │ │ (WebSocket) │
└───────┬───────┘ └────────┬────────┘ └──────┬──────┘
│ │ │
└────────────────────┼────────────────────┘
│
┌────────▼────────┐
│ BFF 层 │
│ (业务逻辑) │
└────────┬────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
┌───────▼───────┐ ┌────────▼────────┐ ┌──────▼──────┐
│ 服务层 │ │ 服务层 │ │ 服务层 │
└───────────────┘ └─────────────────┘ └─────────────┘

接口层 (app/interface)

BFF 层 (app/bff)

后端对前端聚合层：

• - 聚合多个服务调用
• 处理客户端特定逻辑
• 降低客户端复杂度

服务层 (app/service)

消息层 (app/messenger)

Biz 服务分解

biz 服务是一个单体业务逻辑容器：

app/service/biz/
├── biz/ # 核心业务操作
├── chat/ # 群组/频道管理
├── code/ # 验证码（短信/邮件）
├── dialog/ # 会话管理
├── message/ # 消息存储与检索
├── updates/ # 实时更新推送
└── user/ # 用户资料与设置

推荐重构方案

对于大规模部署，将 biz 拆分为：

chat-service/ - 群组与频道管理
message-service/ - 消息 CRUD 与搜索
user-service/ - 用户资料与联系人
notification-service/ - 推送通知

数据流

消息发送流程

客户端 → gnetway → session → msg → message (biz)
↓
MySQL (持久化)
↓
Kafka (广播)
↓
sync → updates → 客户端

认证流程

客户端 → gnetway → authsession
↓
MySQL (auth_keys)
↓
Redis (会话)

文件上传流程

客户端 → gnetway → dfs → MinIO
↓
MySQL (file_metadata)

基础设施依赖

项目结构

teamgram-server/
├── app/
│ ├── bff/ # 后端对前端
│ ├── interface/ # 网关层
│ │ ├── gnetway/ # MTProto 网关
│ │ ├── httpserver/ # HTTP API
│ │ └── session/ # WebSocket 会话
│ ├── messenger/ # 消息路由
│ │ ├── msg/ # 消息服务
│ │ └── sync/ # 同步服务
│ └── service/ # 核心服务
│ ├── authsession/ # 认证与会话
│ ├── biz/ # 业务逻辑
│ ├── dfs/ # 文件存储
│ ├── geoip/ # 地理位置
│ ├── idgen/ # ID 生成器
│ ├── media/ # 媒体处理
│ └── status/ # 在线状态
├── pkg/ # 共享包
│ ├── code/ # 错误码
│ ├── conf/ # 配置
│ ├── net2/ # 网络工具
│ └── ...
├── clients/ # 客户端 SDK
├── data/ # SQL 模式
├── docs/ # 文档
└── specs/ # 架构规范

开发工作流

1. 代码生成

Teamgram 使用 TL（类型语言）模式：

bash

从 TL 模式生成 Go 代码

或

2. 数据库迁移

bash

初始化数据库

运行迁移

3. 服务开发模式

每个服务遵循以下结构：

app/service//
├── cmd/ # 入口点
├── etc/ # 配置
├── internal/
│ ├── config/ # 配置结构
│ ├── core/ # 业务逻辑
│ ├── dao/ # 数据访问
│ ├── server/ # gRPC/HTTP 处理器
│ └── svc/ # 服务上下文
└── .go # 主服务文件

4. 添加新 RPC

1. 1. 在 TL 模式中定义 (specs/mtproto.tl)
2. 运行代码生成
3. 在 internal/core/ 中实现处理器
4. 在 internal/server/ 中注册
5. 更新客户端 SDK

配置

服务配置 (YAML)

yaml

app/service