From c1cec33536446db05bbb53d20f386ed48c213a21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=A6=E6=B8=8A?= <101690169+666666g@users.noreply.github.com> Date: Mon, 6 Jul 2026 19:53:28 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E5=88=9B=E5=BB=BA=20Fragment.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/Fragment.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/Fragment.md diff --git a/docs/Fragment.md b/docs/Fragment.md new file mode 100644 index 00000000..d364e029 --- /dev/null +++ b/docs/Fragment.md @@ -0,0 +1,58 @@ +Fragment collectibles +Telegram users can make it easy for others to contact them or find their public groups and channels via usernames: clients can also assign multiple Fragment » collectible usernames to accounts, supergroups and channels they own; Fragment » also allows purchasing phone number collectibles that can be used to register Telegram accounts. + +Collectible usernames +Schema: + +username#b4073647 flags:# editable:flags.0?true active:flags.1?true username:string = Username; + +updateUserName#a7848924 user_id:long first_name:string last_name:string usernames:Vector = Update; + +user#31774388 flags:# self:flags.10?true contact:flags.11?true mutual_contact:flags.12?true deleted:flags.13?true bot:flags.14?true bot_chat_history:flags.15?true bot_nochats:flags.16?true verified:flags.17?true restricted:flags.18?true min:flags.20?true bot_inline_geo:flags.21?true support:flags.23?true scam:flags.24?true apply_min_photo:flags.25?true fake:flags.26?true bot_attach_menu:flags.27?true premium:flags.28?true attach_menu_enabled:flags.29?true flags2:# bot_can_edit:flags2.1?true close_friend:flags2.2?true stories_hidden:flags2.3?true stories_unavailable:flags2.4?true contact_require_premium:flags2.10?true bot_business:flags2.11?true bot_has_main_app:flags2.13?true bot_forum_view:flags2.16?true bot_forum_can_manage_topics:flags2.17?true bot_can_manage_bots:flags2.18?true bot_guestchat:flags2.19?true id:long access_hash:flags.0?long first_name:flags.1?string last_name:flags.2?string username:flags.3?string phone:flags.4?string photo:flags.5?UserProfilePhoto status:flags.6?UserStatus bot_info_version:flags.14?int restriction_reason:flags.18?Vector bot_inline_placeholder:flags.19?string lang_code:flags.22?string emoji_status:flags.30?EmojiStatus usernames:flags2.0?Vector stories_max_id:flags2.5?RecentStory color:flags2.8?PeerColor profile_color:flags2.9?PeerColor bot_active_users:flags2.12?int bot_verification_icon:flags2.14?long send_paid_messages_stars:flags2.15?long = User; + +channel#1c32b11c flags:# creator:flags.0?true left:flags.2?true broadcast:flags.5?true verified:flags.7?true megagroup:flags.8?true restricted:flags.9?true signatures:flags.11?true min:flags.12?true scam:flags.19?true has_link:flags.20?true has_geo:flags.21?true slowmode_enabled:flags.22?true call_active:flags.23?true call_not_empty:flags.24?true fake:flags.25?true gigagroup:flags.26?true noforwards:flags.27?true join_to_send:flags.28?true join_request:flags.29?true forum:flags.30?true flags2:# stories_hidden:flags2.1?true stories_hidden_min:flags2.2?true stories_unavailable:flags2.3?true signature_profiles:flags2.12?true autotranslation:flags2.15?true broadcast_messages_allowed:flags2.16?true monoforum:flags2.17?true forum_tabs:flags2.19?true id:long access_hash:flags.13?long title:string username:flags.6?string photo:ChatPhoto date:int restriction_reason:flags.9?Vector admin_rights:flags.14?ChatAdminRights banned_rights:flags.15?ChatBannedRights default_banned_rights:flags.18?ChatBannedRights participants_count:flags.17?int usernames:flags2.0?Vector stories_max_id:flags2.4?RecentStory color:flags2.7?PeerColor profile_color:flags2.8?PeerColor emoji_status:flags2.9?EmojiStatus level:flags2.10?int subscription_until_date:flags2.11?int bot_verification_icon:flags2.13?long send_paid_messages_stars:flags2.14?long linked_monoforum_id:flags2.18?long = Chat; + +---functions--- + +account.toggleUsername#58d6b376 username:string active:Bool = Bool; +account.reorderUsernames#ef500eab order:Vector = Bool; + +bots.reorderUsernames#9709b1c2 bot:InputUser order:Vector = Bool; +bots.toggleUsername#053ca973 bot:InputUser username:string active:Bool = Bool; + +channels.toggleUsername#50f24105 channel:InputChannel username:string active:Bool = Bool; +channels.reorderUsernames#b45ced1d channel:InputChannel order:Vector = Bool; +channels.deactivateAllUsernames#0a245dd3 channel:InputChannel = Bool; +Collectible usernames work just like basic @usernames, they appear in Global Search results and have deep links », just like basic usernames. + +The ownership of collectible usernames is secured by TON, a fast and scalable blockchain network. They can be bought and sold through the Fragment platform », giving a simple and secure way to acquire and exchange valuable Telegram domains. + +On the Fragment platform, clients may associate or dissociate purchased collectible usernames either to their Telegram account, or to a bot/channel/supergroup they own. + +If any collectible username is associated to an account, channel or supergroup, user.username and channel.username won't be set, and user.usernames and channel.usernames will be set, instead: these fields contain an array of username constructors, which indicate whether a certain username is a basic username (editable is set) or a collectible username (editable is not set); and whether a collectible username is active or not. +The first username in the usernames vector must be shown in-UI as the main username. + +Immediately after association, a username is marked as not active (i.e. only the owner can see it in the usernames list): use account.toggleUsername, bots.toggleUsername or channels.toggleUsername to mark it as active. +Note that you can't mark as inactive the basic (non-collectible) username, if any. + +channels.deactivateAllUsernames may also be used to mark as inactive all collectible usernames associated to a certain supergroup or channel: useful for example when making a group or channel private, by first invoking channels.updateUsername with an empty username to remove the editable username (if present), and then invoking this method to remove all associated collectible usernames. + +Use account.reorderUsernames/bots.reorderUsernames/channels.reorderUsernames to change the order of the usernames associated to an account, channel or supergroup: all currently active usernames must be specified. + +Collectible phone numbers +Fragment collectible phone numbers can only be used to create Telegram accounts, using the usual sign up/login flow ». + +Fetching info about Fragment collectibles +Schema: + +inputCollectibleUsername#e39460a9 username:string = InputCollectible; +inputCollectiblePhone#a2e214a4 phone:string = InputCollectible; + +fragment.collectibleInfo#6ebdff91 purchase_date:int currency:string amount:long crypto_currency:string crypto_amount:long url:string = fragment.CollectibleInfo; + +---functions--- + +fragment.getCollectibleInfo#be1e85ba collectible:InputCollectible = fragment.CollectibleInfo; +fragment.getCollectibleInfo may be used to fetch info about Fragment collectible owned by us or other users (i.e. the purchase date & price). + +The collectible must be visible to the current user, for example it can be a Fragment user/phone number collectible we own, or a Fragment username that another user has enabled on their account, or another user's Fragment phone number that we can see thanks to the owner's privacy settings. \ No newline at end of file From 66a196726067c7cfdaf967963d1471e19766bf18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=A6=E6=B8=8A?= <101690169+666666g@users.noreply.github.com> Date: Mon, 6 Jul 2026 20:27:07 +0800 Subject: [PATCH 2/2] docs: add public deployment port documentation for gramsrv MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为中英文 README 补充公网部署所需的端口清单文档，包括基础聊天、管理后台、可选功能以及内部调试端口的详细说明，并提醒配置监听地址和公网IP以确保客户端正常连接。 --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ README.zh-CN.md | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+) diff --git a/README.md b/README.md index ef60dbdd..37a91207 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,46 @@ The optional sticker seed directory is skipped when it does not exist. Optional OpenAI-compatible, Kimi/Moonshot, Gemini, and Anthropic provider variables are documented in `.env.example`. +## Public Deployment Ports + +When deploying `gramsrv` on a public server, open the following ports according +to the features you enable. + +### Minimal public deployment (chat only) + +| Port | Protocol | Purpose | Required | +|---|---|---|---| +| 2398 | TCP | MTProto main port; also handles WebSocket when `TELESRV_WEBSOCKET_ENABLE=true` | Yes | + +### With Admin backend + +| Port | Protocol | Purpose | Notes | +|---|---|---|---| +| 2399 | TCP | Admin REST API | Restrict to trusted IPs or put behind VPN | +| 2600 | TCP | Admin Web UI | Use Nginx/reverse proxy + HTTPS in production | + +### Optional feature ports + +| Port | Protocol | Purpose | When needed | +|---|---|---|---| +| 2400 | TCP | RTMP live stream ingest | Live streaming | +| 12399 | UDP | SFU/WebRTC conferencing | Voice/video group calls | +| 12400 | UDP | TURN/STUN server | P2P/call relay | +| 12500-12999 | UDP | TURN relay port range | TURN relay | +| configurable | TCP | Bot API | When `TELESRV_BOT_API_ADDR` is set | +| configurable | TCP | Sticker Web deep-link landing | When `TELESRV_STICKER_WEB_ADDR` is set | + +### Internal/debug ports (do not expose publicly) + +| Port | Default bind | Purpose | +|---|---|---| +| 6060 | `127.0.0.1:6060` | pprof debugging endpoint | +| 5432 | `127.0.0.1:5432` | PostgreSQL | +| 6399 | `127.0.0.1:6399` | Redis | + +Make sure `TELESRV_LISTEN=0.0.0.0:2398` is set, and `TELESRV_ADVERTISE_IP` +points to your public IP so clients can connect. + ## Client Compatibility Stock Telegram clients will not connect to `gramsrv` because they trust diff --git a/README.zh-CN.md b/README.zh-CN.md index 72e48c19..c70d21b2 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -102,6 +102,44 @@ go build -o bin/gramsrv.exe ./cmd/telesrv 如果 sticker seed 目录不存在，启动时会自动跳过。 可选的 OpenAI-compatible、Kimi/Moonshot、Gemini、Anthropic provider 变量见 `.env.example`。 +## 最小公网部署端口清单 + +在公网服务器部署 `gramsrv` 时，需要根据启用的功能开放以下端口。 + +### 最小公网部署（仅聊天） + +| 端口 | 协议 | 用途 | 是否必须 | +|---|---|---|---| +| 2398 | TCP | MTProto 主端口；`TELESRV_WEBSOCKET_ENABLE=true` 时同时处理 WebSocket | 是 | + +### 启用管理后台 + +| 端口 | 协议 | 用途 | 说明 | +|---|---|---|---| +| 2399 | TCP | Admin REST API | 建议限制可访问 IP 或放在 VPN 后 | +| 2600 | TCP | Admin Web UI | 生产环境建议前面加 Nginx/反向代理 + HTTPS | + +### 可选功能端口 + +| 端口 | 协议 | 用途 | 何时需要 | +|---|---|---|---| +| 2400 | TCP | RTMP 直播推流 ingest | 启用直播 | +| 12399 | UDP | SFU/WebRTC 群通话 | 启用语音/视频群通话 | +| 12400 | UDP | TURN/STUN 服务器 | 启用 P2P/通话 relay | +| 12500-12999 | UDP | TURN relay 端口段 | 启用 TURN relay | +| 可配置 | TCP | Bot API | 设置 `TELESRV_BOT_API_ADDR` 时 | +| 可配置 | TCP | Sticker Web 深链落地页 | 设置 `TELESRV_STICKER_WEB_ADDR` 时 | + +### 内部/调试端口（不要暴露到公网） + +| 端口 | 默认监听 | 用途 | +|---|---|---| +| 6060 | `127.0.0.1:6060` | pprof 调试端点 | +| 5432 | `127.0.0.1:5432` | PostgreSQL | +| 6399 | `127.0.0.1:6399` | Redis | + +确保设置 `TELESRV_LISTEN=0.0.0.0:2398`，且 `TELESRV_ADVERTISE_IP` 指向公网 IP，客户端才能正确连接。 + ## 客户端兼容 官方 Telegram 客户端不能直接连接 `gramsrv`，因为它们信任的是 Telegram 官方 DC 列表和 RSA keys。你可以使用 [官网](https://telesrv.net) 提供的体验客户端，也可以自己做最小协议 patch。