wmq
74 lines
3.0 KiB
Markdown
74 lines
3.0 KiB
Markdown
# Telegram Gateway 接入指南
|
|
|
|
## 定位
|
|
|
|
`telegram-gateway/` 使用 Telegram TDLib 登录普通用户账号，不是 Bot API。它负责账号授权、历史同步、消息与媒体、联系人、群组/频道、代理、会话设备、Webhook、审计、限流和异步任务；灵犀跨境 API 通过服务凭据调用它。
|
|
|
|
网关源码与平台在同一 Git 仓库版本化，但运行时保持独立：它拥有自己的 PostgreSQL、Redis 和 TDLib 持久卷，故障与扩缩容不会直接占用平台数据库。
|
|
|
|
## 配置
|
|
|
|
```powershell
|
|
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。
|
|
|
|
## 启动
|
|
|
|
```powershell
|
|
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` 配置：
|
|
|
|
```dotenv
|
|
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 操作状态。备份与恢复必须同时记录两个系统的版本和时间点。
|
|
|
|
## 验证
|
|
|
|
```powershell
|
|
npm ci --prefix telegram-gateway
|
|
npm run build --prefix telegram-gateway
|
|
npm test --prefix telegram-gateway
|
|
```
|
|
|
|
自动化测试通过后，仍需使用无重要数据的测试账号验证手机号、验证码、二步密码、历史同步、双向收发、媒体、Webhook、代理、断网重连和 FloodWait 退避。Mock/内存数据库测试不能证明真实 Telegram 可用。
|