KHF Android 客户端架构与端到端数据流

KHF 客户端关键常量

从 KHF 源码提取（必须与服务端兼容）：

• - TLRPC.LAYER = 222
• BuildVars.APPID = 4
• BuildVars.APPHASH = 014b35b6184100b085b0d0572f9b5103

tgnet/ConnectionsManager：Java → JNI → Native MTProto

ConnectionsManager 负责：

• - nativeinit(...) 初始化 MTProto（layer/apiid/设备信息）
• native_sendRequest(...) 发送 RPC
• DC/网络状态管理

客户端通过 JNI 调用 Native C++ 层实现 MTProto 协议，包括：

• - 加密/解密（AES-IGE）
• 握手（DH 密钥交换生成 auth_key）
• 消息序列化/反序列化（TL 二进制格式）
• 网络连接管理（TCP/WebSocket）
• 重连与退避策略

MessagesController：业务层

MessagesController 负责 dialogs/messages/users/chats 的本地模型与网络请求，典型方法：

• - loadAppConfig — 加载应用配置
• loadDialogs — 加载对话列表
• loadMessages — 加载消息
• loadFullChat — 加载群组完整信息
• loadFullUser — 加载用户完整信息

端到端数据流示例

登录流程：auth.sendCode → auth.signIn

text
客户端（KHF）
-> TL: auth.sendCode(phonenumber, apiid, api_hash, settings)
-> MTProto 加密消息
-> gnetway 解密 + QuickAck + SendDataToSession
-> session 解码 TLMessage2 -> 通过 IDMap 路由到 /mtproto.RPCAuthorization
-> bff.authorization.AuthSendCode
-> biz.user（检查手机号是否注册）
-> status（在线会话）
-> verify-code 插件（短信）或应用验证码
<- bff 返回 auth.SentCode 或错误
<- session 封装 rpc_result
<- gnetway 加密并回传
<- 客户端解析 auth.SentCode

消息发送流程：messages.sendMessage

text
客户端
-> TL: messages.sendMessage / messages.sendMedia / ...
-> gnetway -> session -> bff.messages
-> bff.messages
-> biz_service（dialog/message/chat/user）
-> msg service（异步投递 + Kafka）
-> messenger.msg 生产消息到 Kafka Inbox-T
-> inbox 消费 Inbox-T，写入 inbox/outbox 状态
-> 生产更新到 Kafka Sync-T
-> sync 消费 Sync-T，决定 UpdatesMe/NotMe/PushRpcResult
-> sync 调用 session（gRPC）推送更新/rpc_result
-> session 路由到正确的 sessionId
-> gnetway 加密 -> 客户端

文件上传下载流程

text
客户端
-> files.upload* / upload.getFile
-> bff.files
-> dfs 保存/获取文件分片
-> media 生成缩略图/元数据
-> db 写入 documents/photos/photo_sizes/...
<- 返回 inputFile / fileLocation / document/photo

DFS
- Minio 存储桶：documents/photos/videos/encryptedfiles
- MiniHttp 0.0.0.0:11701 提供 HTTP 下载入口

客户端与服务端兼容性要点

1. 1. LAYER 版本：客户端 LAYER=222 必须与服务端 session.yaml 中的 layer 配置一致
2. APPID/APPHASH：必须与服务端 BFF 配置中的 ApiId/ApiHash 匹配
3. MTProto 握手：客户端使用 obfuscated2 + AES-IGE 加密
4. TL 序列化：客户端和服务端必须使用相同的 TL Schema 版本

常见错误与排查

错误	含义	排查方向
PHONENUMBERINVALID	手机号格式不正确	检查国际格式（+86...）
PHONENUMBERBANNED

手机号被封禁 | 检查 predefined_users 表 | | SESSIONPASSWORDNEEDED | 需要两步验证 | 用户设置了密码 | | AUTHKEYUNREGISTERED | auth_key 未注册 | 清除客户端数据重新握手 | | CONNECTIONNOTINITED | 未调用 initConnection | 客户端需先发 initConnection | | ERRENTERPRISEISBLOCKED | 企业版功能锁定 | 需要解除企业版拦截（修改 bizservice 中的企业版检查逻辑） | | METHODNOTIMPL | RPC 方法未实现 | 检查 BFF handler 和 session IDMap 路由是否配置 |

企业版锁定模式

Teamgram 社区版中部分功能被企业版锁定拦截，表现为：

• - ERRENTERPRISEISBLOCKED 错误
• 在 bizservice 层的 helper 中通过 checkEnterprise() 函数拦截

解锁方法：修改 biz_service 中对应 helper 的企业版检查逻辑，移除或绕过 checkEnterprise() 调用。

关键代码路径

客户端（KHF）

• - ConnectionsManager：TMessagesProj/jni/tgnet/ConnectionsManager.cpp
• MessagesController：TMessagesProj/src/main/java/org/telegram/messenger/MessagesController.java
• TLRPC 定义：TMessagesProj/src/main/java/org/telegram/tgnet/TLRPC.java
• BuildVars：TMessagesProj/src/main/java/org/telegram/messenger/BuildVars.java

服务端（HD/Teamgram）

• - gnetway 入口：app/interface/gnetway/
• session 路由：app/interface/session/
• BFF 模块：app/bff/
• biz_service：app/service/biz/
• messenger：app/messenger/
• 配置文件：teamgramd/etc/
• SQL schema：teamgramd/deploy/sql/

源代码参考

• - 仓库地址：https://github.com/teamgram/teamgram-server（Apache-2.0 许可证）