{"skill":{"slug":"teamgram-architecture","displayName":"Teamgram Architecture","summary":"Overview of Teamgram Server's 6-layer microservice architecture with 11 services, gRPC/Kafka communication, and etcd service discovery for Telegram-compatibl...","description":"---\nname: teamgram-architecture\ndescription: Overview of Teamgram Server's 6-layer microservice architecture with 11 services, gRPC/Kafka communication, and etcd service discovery for Telegram-compatible messaging backends.\ncompatibility: Documentation/knowledge skill only. No executable code. Reference material for Teamgram Server developers.\nmetadata:\n  author: zhihang9978\n  version: \"1.0.1\"\n  source: https://github.com/teamgram/teamgram-server\n  homepage: https://github.com/teamgram/teamgram-server\n  openclaw:\n    requires:\n      env: []\n      bins: []\n    securityNotes: |\n      Documentation-only skill. Contains no executable code, no network calls, no credential handling.\n      All content references the open-source teamgram-server project (Apache-2.0).\n---\n\n# Teamgram Server 总体架构概览\n\n## 系统定位\n\nTeamgram Server 是一个 Telegram/MTProto 兼容的微服务系统，配合 KHF Android 客户端使用。\n\n## 分层架构\n\n```text\n[KHF Android Client]\n    |\n    |  MTProto (obfuscated2 / tcp / websocket)\n    v\n[gnetway: interface.gateway]\n    |\n    |  gRPC (go-zero zrpc, etcd discovery: interface.session)\n    v\n[session: interface.session]\n    |\n    |  gRPC proxy by IDMap (mtproto.RPC* -> bff.bff)\n    v\n[bff: bff.bff]\n    |\n    |  gRPC calls (etcd): service.biz_service / service.authsession / service.status / messenger.msg / service.dfs / service.media / service.idgen\n    v\n[biz_service + others]\n    |\n    |  Kafka topics:\n    |    - Inbox-T (write path)\n    |    - Sync-T  (fanout/push path)\n    v\n[messenger.msg] -> [Kafka Inbox-T] -> [inbox helper]\n                         |\n                         v\n                      [Kafka Sync-T] -> [messenger.sync] -> [session] -> [gnetway] -> [client]\n```\n\n## 6 层职责\n\n| 层 | 服务 | 职责 |\n|---|---|---|\n| **入口层** | gnetway | TCP/WebSocket/HTTP MTProto 网关 |\n| **会话路由层** | session | 按 auth_key / session_id 聚合与路由，作为 gnetway 与 BFF 的桥 |\n| **BFF 聚合层** | bff.bff | 实现 Telegram RPC 接口的 27 个模块 |\n| **核心业务层** | biz_service | 6 个 helper（user/chat/dialog/message/updates/code） |\n| **消息投递层** | messenger.msg + inbox | Kafka Inbox-T 写入 inbox/outbox/未读等状态 |\n| **同步分发层** | messenger.sync | Kafka Sync-T → 推送 updates/rpcResult 回 session |\n\n## 11 个核心微服务清单\n\n| 服务名 | etcd Key | 端口 | 职责 |\n|---|---|---|---|\n| **gnetway** | interface.gateway | 10443/5222/11443 | MTProto 网关（TCP/WS/HTTP） |\n| **session** | interface.session | 20120 | 会话聚合与 RPC 路由 |\n| **authsession** | service.authsession | 20450 | auth_key 管理 |\n| **bff** | bff.bff | 20010 | 27个RPC模块聚合层 |\n| **biz_service** | service.biz_service | 20500 | 6个helper（user/chat/dialog/message/updates/code） |\n| **msg** | messenger.msg | 20030 | 消息投递 + Kafka生产 |\n| **inbox** | (Kafka consumer) | - | Inbox-T 消费者（写入 inbox/outbox/未读等状态） |\n| **sync** | messenger.sync | 20420 | 同步分发（Kafka→session） |\n| **idgen** | service.idgen | 20660 | Snowflake/Seq ID生成 |\n| **status** | service.status | 20670 | 在线状态/会话TTL |\n| **dfs** | service.dfs | 20640 + 11701 | Minio 文件存储 + HTTP 网关 |\n| **media** | service.media | 20650 | 媒体元数据/缩略图处理 |\n\n> 注：msg/inbox/sync 属于 messenger 域的不同子服务/角色。\n\n## 服务间通信方式\n\n1. **gRPC (go-zero zrpc)**：所有微服务间同步调用均使用 gRPC，通过 etcd 服务发现\n2. **Kafka 异步消息**：消息投递（Inbox-T）和同步分发（Sync-T）使用 Kafka 解耦\n3. **MTProto 二进制协议**：客户端与 gnetway 之间的通信协议\n\n## 配置与服务发现\n\n- 所有服务通过 YAML 声明 `Etcd.Hosts` + `Etcd.Key` 注册到 etcd\n- 调用端用同 Key 发现目标服务\n- 关键 etcd Key 列表：interface.gateway, interface.session, bff.bff, service.biz_service, service.authsession, service.idgen, service.status, service.dfs, service.media, messenger.msg, messenger.sync\n\n\n## Source Code References\n\n- Repository: https://github.com/teamgram/teamgram-server (Apache-2.0)\n","topics":["Telegram"],"tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":571,"installsAllTime":21,"installsCurrent":1,"stars":0,"versions":2},"createdAt":1773545359994,"updatedAt":1778491917527},"latestVersion":{"version":"1.0.1","createdAt":1773546132381,"changelog":"Added security metadata, source references, and credential declarations","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"zhihang9978","userId":"s172je8v58fh44rr2hyzjrejen84qsq9","displayName":"zhihang9978","image":"https://avatars.githubusercontent.com/u/217701803?v=4"},"moderation":null}