docs: refresh public readme and screenshots

2026-06-23 20:49:31 +08:00 · 2026-06-23 20:49:31 +08:00 · ea60bd6155
commit ea60bd6155
parent 4afc67fd23
8 changed files with 104 additions and 192 deletions
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@ -1,31 +1,28 @@
 # gramsrv

-`gramsrv` 是一个用 Go 编写的 Telegram-like MTProto server，以
-[`github.com/gotd/td`](https://github.com/gotd/td) v0.144.0 / Layer 225 作为
-TL 与 MTProto 基础，第一兼容目标是固定基线的 Telegram Desktop。
+`gramsrv` 是一个用 Go 编写的 Telegram-like MTProto server，重点放在真实客户端兼容、可复现协议研究和自建聊天服务实验。
+
+[官网](https://telesrv.net) · [讨论群组](https://t.me/telesrv_chat) · [频道](https://t.me/telesrv) · [English README](README.md)
+
+![gramsrv Desktop 与 Android 多设备预览](docs/assets/readme-hero.png)

 `gramsrv` 是独立的非官方项目，与 Telegram 官方及其团队没有关联，也未获得其背书或赞助。

-关键词：`MTProto`、`Telegram Desktop`、`gotd/td`、`Telegram-like server`、`Go`、
-`self-hosted chat server`。
+## 亮点

-[English README](README.md)
+- **多设备已实现。** Telegram Desktop 与 Android 客户端可以使用同一套服务端状态，支持 scoped session、在线 fan-out、当前 session 排除，以及通过 updates difference API 做离线恢复。
+- **Telegram Desktop 是第一兼容目标。** 当前公开版本围绕固定 TDesktop 基线推进，并把兼容性进展写入文档。
+- **Android 兼容正在推进。** 当前公开截图已经包含连接到同一服务端路径的 Android 客户端。
+- **核心聊天主路径可用。** 已覆盖登录、users、contacts、dialogs、私聊消息、超级群/频道、media/files、用户/频道头像、stickers、reactions、语言包与 presence。
+- **生产边界明确。** 大规模公开频道、多 DC / 文件 DC / CDN、Bot API、payments、stories、Premium 商业逻辑、生产风控和生产对象存储不属于当前公开版本范围。

-![Telegram Desktop Alice/Bob connected to gramsrv](docs/assets/tdesktop-dual-session.png)
+下载、公开说明和当前体验入口见 [telesrv.net](https://telesrv.net)。问题交流、兼容反馈和开发讨论可以加入 [t.me/telesrv_chat](https://t.me/telesrv_chat)。

-## 当前状态
+## 截图

-本项目适合本地协议研究、Telegram Desktop 兼容性验证和自建 MTProto server 实验。它不是生产级 Telegram 替代品。
-
-当前已覆盖的主路径包括 MTProto key exchange、开发验证码登录、users/contacts/dialogs、私聊消息、超级群/频道、updates difference 恢复、本地 media/files、用户/频道头像、stickers、reactions 和 presence。
-
-暂不默认覆盖大规模公开频道、多 DC / 文件 DC / CDN、Bot API、payments、stories、Premium 商业逻辑、生产风控、生产对象存储等能力。
-
-## 欢迎贡献
-
-欢迎大家参与贡献。现在最有价值的方向包括 Telegram Desktop 兼容性报告、可复现 RPC trace、聚焦的小 bug fix、在线/离线 updates 行为测试、已实现路径的性能优化，以及让本地启动更顺滑的文档改进。
-
-请尽量保持改动范围清晰，并围绕兼容性目标展开。如果改动会影响 Telegram Desktop 可见行为，请在 PR 或说明里写清客户端版本/commit、验证过的 RPC 路径，以及 server 日志是否没有新增 `NOT_IMPLEMENTED`、`Unhandled RPC`、`bad_msg`、panic 或 internal error。
+| Telegram Desktop | Android |
+|---|---|
+| <img src="docs/assets/tdesktop1.png" alt="Telegram Desktop connected to gramsrv" width="520"> | <img src="docs/assets/android1.png" alt="Android client connected to gramsrv" width="260"> |

 ## 仓库结构

@ -40,7 +37,7 @@ internal/store/           store interfaces 与 memory/postgres/redis 后端
 docs/                     兼容性记录与模块设计文档
 ```

-## 运行 gramsrv
+## 快速启动

 依赖：

@ -77,88 +74,33 @@ go build -o bin/gramsrv.exe ./cmd/telesrv

 如果 sticker seed 目录不存在，启动时会自动跳过。

-## 编译连接 gramsrv 的 Telegram Desktop
+## 客户端兼容

-官方 Telegram Desktop 二进制不能直接连接 `gramsrv`，因为它信任的是 Telegram 官方 DC 列表和 RSA keys。你需要编译一个最小 patch 过的客户端。
+官方 Telegram 客户端不能直接连接 `gramsrv`，因为它们信任的是 Telegram 官方 DC 列表和 RSA keys。你可以从 [官网](https://telesrv.net) 获取体验客户端，或者自己编译带最小协议 patch 的客户端。

-目标基线：
+当前 Telegram Desktop 基线：

 - Telegram Desktop commit：`9caf32dffc90ddd9bb08ad5777b865f729fa167b`
 - TL layer：225
 - 本地 DC：`127.0.0.1:2398`，DC id `2`

-克隆并固定 Telegram Desktop：
-
-```powershell
-git clone --recursive https://github.com/telegramdesktop/tdesktop.git
-cd tdesktop
-git checkout 9caf32dffc90ddd9bb08ad5777b865f729fa167b
-git submodule update --init --recursive
-```
-
-编译依赖和各平台完整说明以 Telegram Desktop 上游文档为准：
-
- Windows：`docs/building-win.md`
- macOS：`docs/building-mac.md`
- Linux：`docs/building-linux.md`
-
-Windows x64 下，固定基线的主要步骤是：
-
-```powershell
-Telegram\build\prepare\win.bat
-cd Telegram
-configure.bat x64 -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH
-```
-
-然后用 Visual Studio 打开 `out\Telegram.slnx`，构建 `Telegram` project。Debug 二进制会生成在 `out\Debug\Telegram.exe`。
-
-## Patch Telegram Desktop
-
 等 `gramsrv` 生成 `data/server_rsa.pem` 后，导出匹配的公钥：

 ```powershell
 openssl rsa -in data/server_rsa.pem -RSAPublicKey_out -out data/server_rsa.pub
 ```

-修改 Telegram Desktop 文件：
+修改 `Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp`：

-```text
-Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp
-```
+1. 把内置 production/test DC 列表替换为你的 `gramsrv` endpoint。
+2. 把 `kPublicRSAKeys` 和 `kTestPublicRSAKeys` 都替换为 `data/server_rsa.pub`。
+3. 给 built-in DC flags 加上 `Flag::f_tcpo_only`。

-1. 把内置 production/test DC 列表替换为本地 DC 2：
+客户端 patch 应保持最小：只改 endpoint、RSA key 和 TCP-only flags。

-```cpp
-const BuiltInDc kBuiltInDcs[] = {
-    { 2, "127.0.0.1", 2398 },
-};
+## 多设备冒烟验证

-const BuiltInDc kBuiltInDcsIPv6[] = {
-    { 2, "::1", 2398 },
-};
-
-const BuiltInDc kBuiltInDcsTest[] = {
-    { 2, "127.0.0.1", 2398 },
-};
-
-const BuiltInDc kBuiltInDcsIPv6Test[] = {
-    { 2, "::1", 2398 },
-};
-```
-
-2. 把 `kPublicRSAKeys` 和 `kTestPublicRSAKeys` 都替换为 `data/server_rsa.pub` 的内容。
-3. 在 `DcOptions::constructFromBuiltIn()` 中给 IPv4 与 IPv6 built-in DC flags 加上 `Flag::f_tcpo_only`。
-
-```cpp
-const auto flags = Flag::f_static | Flag::f_tcpo_only;
-const auto flags = Flag::f_static | Flag::f_ipv6 | Flag::f_tcpo_only;
-```
-
-客户端 patch 应保持最小：只改 DC endpoint、RSA public key 和 TCP-only flags，不要把 UI 改动混入协议兼容 patch。
-
-## 启动两个本地 Desktop 客户端
-
-用不同的 TDesktop working directory，避免 Alice 和 Bob 共用同一个 `tdata`：
+使用不同的客户端工作目录，避免多个 session 共用本地 `tdata`：

 ```powershell
 $tdesktop = "C:\path\to\tdesktop\out\Debug\Telegram.exe"
@ -166,14 +108,14 @@ Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-alice")
 Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-bob")
 ```

-用两个不同手机号登录。本地开发默认验证码是 `12345`，除非你修改了 `TELESRV_DEV_AUTH_CODE`。
+用不同手机号登录。本地开发默认验证码是 `12345`，除非你修改了 `TELESRV_DEV_AUTH_CODE`。

-如果客户端一直重连，优先检查：
+推荐检查：

- `gramsrv` 是否正在监听 `2398`。
- `data/server_rsa.pub` 是否同时复制到了 TDesktop 的两个 RSA key 数组。
- `TELESRV_ADVERTISE_IP` 是否是客户端可访问的地址。
- TDesktop 是否基于固定 Layer 225 基线构建，或者你已经重新审计了新 layer。
+- 在两个用户之间发送私聊消息、贴纸、媒体、回复、转发、编辑、删除和已读回执。
+- 保持一个设备在线，重启另一个设备，验证离线 `updates.getDifference` 恢复。
+- 同一账号打开多个 session，确认当前 session 不重复收到 echo，其它在线 session 能收到更新。
+- 检查 server 日志没有新增 `NOT_IMPLEMENTED`、`Unhandled RPC`、`bad_msg`、panic 或 internal error。

 ## 文档

@ -183,3 +125,9 @@ Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-bob")
 - [消息模块](docs/message-module.md)
 - [频道模块](docs/channel-module.md)
 - [性能审计](docs/performance-audit.md)
+
+## 参与贡献
+
+欢迎围绕兼容性目标参与贡献。现在最有价值的方向包括 Telegram Desktop / Android 兼容反馈、可复现 RPC trace、聚焦的小 bug fix、多设备 update 测试、已实现路径的性能优化，以及让本地启动更顺滑的文档改进。
+
+如果改动会影响客户端可见行为，请写清客户端版本/commit、验证过的 RPC 路径，以及 server 日志结果。