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] 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。