wmq
06112602ec
Version the NestJS TDLib gateway with Docker deployment, migrations, automated tests and platform integration documentation while excluding all account sessions, credentials, runtime databases and backups.
73 lines
2.9 KiB
Markdown
73 lines
2.9 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`：仅填写受信任的管理入口；平台服务端调用不依赖浏览器跨域。
|
|
|
|
生产环境不要使用示例中的 `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 可用。
|