astra/owpengram-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: refresh public readme and screenshots

Browse source
This commit is contained in:
A 2026-06-23 20:49:31 +08:00
parent 4afc67fd23
commit ea60bd6155
8 changed files with 104 additions and 192 deletions
Download patch file Download diff file Expand all files Collapse all files

166
README.md
View file

@ -1,43 +1,43 @@
# gramsrv
`gramsrv` is a Telegram-like MTProto server written in Go. It uses
[`github.com/gotd/td`](https://github.com/gotd/td) v0.144.0 / Layer 225 as the TL
and MTProto base, and its first compatibility target is a pinned Telegram
Desktop build.
`gramsrv` is a Go implementation of a Telegram-like MTProto server, focused on
real client compatibility, repeatable protocol research, and self-hosted chat
experiments.
`gramsrv` is an independent, unofficial project. It is not affiliated with,
endorsed by, or sponsored by Telegram or the official Telegram team.
[Website](https://telesrv.net) · [Discussion group](https://t.me/telesrv_chat) · [Channel](https://t.me/telesrv) · [中文 README](README.zh-CN.md)
Keywords: `MTProto`, `Telegram Desktop`, `gotd/td`, `Telegram-like server`, `Go`,
`self-hosted chat server`.
![gramsrv multi-device Desktop and Android preview](docs/assets/readme-hero.png)
[中文 README](README.zh-CN.md)
`gramsrv` is independent and unofficial. It is not affiliated with, endorsed by,
or sponsored by Telegram or the official Telegram team.
![Telegram Desktop Alice/Bob connected to gramsrv](docs/assets/tdesktop-dual-session.png)
## Highlights
## Status
- **Multi-device is implemented.** Telegram Desktop and Android clients can use
the same server state, with scoped sessions, online fan-out, current-session
exclusion, and offline recovery through update difference APIs.
- **Telegram Desktop is the primary compatibility target.** The public build
tracks a pinned TDesktop baseline and keeps compatibility work documented.
- **Android compatibility is active.** The current public screenshots include a
patched Android client connected to the same server path.
- **Core chat paths work today.** Login, users, contacts, dialogs, private
messages, supergroups/channels, media/files, profile/channel photos,
stickers, reactions, language packs, and presence are covered on the main
path.
- **Production boundaries are explicit.** Large-scale public channels,
multi-DC/file-DC/CDN, Bot API, payments, stories, Premium business logic,
abuse controls, and production object storage are outside the current public
scope.
This project is useful for local protocol research and Telegram Desktop
compatibility work. It is not a production Telegram replacement.
For downloads, public information, and the current hosted experience entry,
visit [telesrv.net](https://telesrv.net). For questions, compatibility reports,
and development discussion, join [t.me/telesrv_chat](https://t.me/telesrv_chat).
Implemented main paths include MTProto key exchange, login with a development
code, users/contacts/dialogs, private messages, supergroups/channels, update
difference recovery, local media/files, profile/channel photos, stickers,
reactions, and presence. Large-scale public channels, multi-DC/file-DC/CDN,
Bot API, payments, stories, Premium business logic, production abuse controls,
and production object storage are intentionally out of scope for now.
## Screenshots
## Contributing
Contributions are very welcome. The most helpful areas right now are Telegram
Desktop compatibility reports, reproducible RPC traces, focused bug fixes,
tests for online/offline update behavior, performance work on already
implemented paths, and documentation that makes local setup easier.
Please keep changes scoped and compatibility-driven. If a change affects
Telegram Desktop behavior, include the client version/commit, the RPC path you
tested, and whether server logs stayed free of `NOT_IMPLEMENTED`, `Unhandled
RPC`, `bad_msg`, panic, or internal errors.
| 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"> |
## Repository Layout
@ -52,7 +52,7 @@ internal/store/ store interfaces and memory/postgres/redis backends
docs/ compatibility notes and module design docs
```
## Run gramsrv
## Quick Start
Requirements:
@ -90,86 +90,37 @@ Useful development environment variables:
The optional sticker seed directory is skipped when it does not exist.
## Build Telegram Desktop For gramsrv
## Client Compatibility
The stock Telegram Desktop binary will not connect to `gramsrv`: it trusts
Telegram's production DC list and RSA keys. Build your own patched client.
Stock Telegram clients will not connect to `gramsrv` because they trust
Telegram's production DC list and RSA keys. Use a patched experience client from
the [official website](https://telesrv.net), or build your own client with a
minimal protocol patch.
Target baseline:
Current Telegram Desktop baseline:
- Telegram Desktop commit: `9caf32dffc90ddd9bb08ad5777b865f729fa167b`
- TL layer: 225
- Local DC: `127.0.0.1:2398`, DC id `2`
Clone and pin Telegram Desktop:
```powershell
git clone --recursive https://github.com/telegramdesktop/tdesktop.git
cd tdesktop
git checkout 9caf32dffc90ddd9bb08ad5777b865f729fa167b
git submodule update --init --recursive
```
Build prerequisites and exact platform instructions are maintained upstream:
- Windows: `docs/building-win.md`
- macOS: `docs/building-mac.md`
- Linux: `docs/building-linux.md`
For Windows x64, the pinned upstream instructions currently boil down to:
```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
```
Then open `out\Telegram.slnx` in Visual Studio and build the `Telegram`
project. The debug binary is written to `out\Debug\Telegram.exe`.
## Patch Telegram Desktop
After `gramsrv` has generated `data/server_rsa.pem`, export the matching public
key:
After `gramsrv` generates `data/server_rsa.pem`, export the matching public key:
```powershell
openssl rsa -in data/server_rsa.pem -RSAPublicKey_out -out data/server_rsa.pub
```
Patch Telegram Desktop file
`Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp`:
Patch `Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp`:
1. Replace built-in production and test DC lists with local DC 2:
```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. Replace both `kPublicRSAKeys` and `kTestPublicRSAKeys` with the contents of
1. Replace the built-in production/test DC lists with your `gramsrv` endpoint.
2. Replace both `kPublicRSAKeys` and `kTestPublicRSAKeys` with
`data/server_rsa.pub`.
3. In `DcOptions::constructFromBuiltIn()`, add `Flag::f_tcpo_only` to the IPv4
and IPv6 built-in DC flags.
3. Add `Flag::f_tcpo_only` to the built-in DC flags.
Keep this client patch minimal: DC endpoints, RSA key, and TCP-only flags only.
Do not mix UI changes into the protocol patch.
Keep the client patch minimal: endpoint, RSA key, and TCP-only flags only.
## Run Two Local Desktop Clients
## Multi-Device Smoke Test
Use separate TDesktop working directories so Alice and Bob do not share `tdata`:
Use separate client working directories so sessions do not share local `tdata`:
```powershell
$tdesktop = "C:\path\to\tdesktop\out\Debug\Telegram.exe"
@ -177,16 +128,19 @@ Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-alice")
Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-bob")
```
Log in with two different phone numbers. In local development, the login code is
Log in with different phone numbers. In local development, the login code is
`12345` unless you changed `TELESRV_DEV_AUTH_CODE`.
If the client keeps reconnecting, check these first:
Recommended checks:
- `gramsrv` is listening on port `2398`.
- `data/server_rsa.pub` was copied into both RSA key arrays in TDesktop.
- `TELESRV_ADVERTISE_IP` matches the address reachable from the client.
- TDesktop was built from the pinned Layer 225 baseline or re-audited for a new
layer.
- Send private messages, stickers, media, replies, forwards, edits, deletes,
and read receipts between two users.
- Keep one device online and restart another device to verify offline
`updates.getDifference` recovery.
- Open the same account from multiple sessions and confirm current-session
echoes are not duplicated while other online sessions receive updates.
- Check server logs for no new `NOT_IMPLEMENTED`, `Unhandled RPC`, `bad_msg`,
panic, or internal errors.
## Documentation
@ -196,3 +150,13 @@ If the client keeps reconnecting, check these first:
- [Message module](docs/message-module.md)
- [Channel module](docs/channel-module.md)
- [Performance audit](docs/performance-audit.md)
## Contributing
Compatibility-driven contributions are welcome. Useful areas include Telegram
Desktop and Android reports, reproducible RPC traces, focused bug fixes,
multi-device update tests, performance work on already implemented paths, and
documentation that makes local setup easier.
If a change affects visible client behavior, include the client version/commit,
the RPC path you tested, and the server log result.

130
README.zh-CN.md
View file

@ -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 日志结果。

BIN
docs/assets/android1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 143 KiB

BIN
docs/assets/readme-hero.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 439 KiB

BIN
docs/assets/tdesktop-alice.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 609 KiB

BIN
docs/assets/tdesktop-bob.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 583 KiB

BIN
docs/assets/tdesktop-dual-session.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 1 MiB

BIN
docs/assets/tdesktop1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 666 KiB