lingxi-web/docs/TELEGRAM-GATEWAY.md

Telegram Gateway 接入指南

定位

telegram-gateway/ 使用 Telegram TDLib 登录普通用户账号，不是 Bot API。它负责账号授权、历史同步、消息与媒体、联系人、群组/频道、代理、会话设备、Webhook、审计、限流和异步任务；灵犀跨境 API 通过服务凭据调用它。

网关源码与平台在同一 Git 仓库版本化，但运行时保持独立：它拥有自己的 PostgreSQL、Redis 和 TDLib 持久卷，故障与扩缩容不会直接占用平台数据库。

配置

Copy-Item telegram-gateway/.env.example telegram-gateway/.env

至少替换：

• TG_API_ID、TG_API_HASH：从 Telegram 官方开发者后台申请，不能使用 Bot Token。
• JWT_SECRET、ADMIN_API_KEY：分别生成强随机值，不得复用。
• DB_PASSWORD：生产数据库强密码。
• CORS_ORIGINS：仅填写受信任的管理入口；平台服务端调用不依赖浏览器跨域。
• TG_DEFAULT_PROXY_*：可选的默认 TDLib 代理；账号绑定的专属代理优先。

生产环境不要使用示例中的 postgres 密码。.env 不得提交 Git。

启动

docker compose --env-file telegram-gateway/.env `
  -f telegram-gateway/docker/docker-compose.yml up -d --build

docker compose -f telegram-gateway/docker/docker-compose.yml ps
Invoke-RestMethod http://127.0.0.1:3000/api/admin/health
Invoke-RestMethod http://127.0.0.1:3000/api/admin/ready

Swagger 默认位于 http://127.0.0.1:3000/api/docs。生产环境应限制 Swagger 和管理接口的访问来源。

连接灵犀跨境

在平台根目录 .env 配置：

TELEGRAM_GATEWAY_URL=http://host.docker.internal:3000/api
TELEGRAM_GATEWAY_TOKEN=replace-with-gateway-jwt
TELEGRAM_GATEWAY_TENANT_ID=replace-with-gateway-tenant-id
TELEGRAM_GATEWAY_SERVICE_EMAIL=replace-with-service-account
TELEGRAM_GATEWAY_SERVICE_PASSWORD=replace-with-service-password
TELEGRAM_WEBHOOK_SECRET=replace-with-independent-webhook-secret

Linux 生产部署建议把两个 Compose 接入同一私有 Docker 网络，并把 URL 改为网关服务名。不要通过公网传递服务密码或长期 JWT。

数据边界

以下内容只存在部署环境，不能进入 Git 或普通源码备份：

• telegram-gateway/.env
• TDLib db.sqlite、td.binlog、WAL 文件及账号目录
• PostgreSQL/Redis 导出
• 下载媒体、上传文件和业务日志
• 验证码、二步密码、手机号及授权会话

平台数据库保存渠道引用和业务消息；网关数据库保存 Telegram 操作状态。备份与恢复必须同时记录两个系统的版本和时间点。

验证

npm ci --prefix telegram-gateway
npm run build --prefix telegram-gateway
npm test --prefix telegram-gateway

自动化测试通过后，仍需使用无重要数据的测试账号验证手机号、验证码、二步密码、历史同步、双向收发、媒体、Webhook、代理、断网重连和 FloodWait 退避。Mock/内存数据库测试不能证明真实 Telegram 可用。