feat(gateway): include production Telegram user gateway
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.
This commit is contained in:
wmq
@@ -25,6 +25,7 @@ Nginx (web:80)
|
||||
| --- | --- |
|
||||
| `src/` | React 页面、组件、状态、API 客户端、国际化与类型 |
|
||||
| `server/src/index.js` | 认证、租户业务、消息、AI、渠道、Webhook、WebSocket 与数据初始化 |
|
||||
| `telegram-gateway/` | NestJS + TDLib 多租户 Telegram 普通账号网关，独立部署 |
|
||||
| `whatsapp-gateway/` | 普通 WhatsApp 多账号连接、消息/媒体/群组/联系人操作 |
|
||||
| `tests/e2e/` | Playwright 桌面与移动端验收 |
|
||||
| `docker/` | Nginx 与邮件协议测试辅助镜像 |
|
||||
@@ -74,6 +75,6 @@ Nginx (web:80)
|
||||
|
||||
## 6. 当前约束
|
||||
|
||||
- Telegram Gateway 为独立仓库和独立部署，本仓库只保存适配与配置。
|
||||
- Telegram Gateway 源码随本仓库版本化，但使用独立 Compose、数据库、Redis 和 TDLib 数据卷部署。
|
||||
- 普通 WhatsApp 接入依赖非官方 Web 多设备协议，生产使用前必须评估账号风控和平台条款。
|
||||
- API 目前集中在单入口文件，业务增长后应按领域拆分路由、服务、仓储和迁移文件。
|
||||
|
||||
@@ -12,6 +12,14 @@
|
||||
```bash
|
||||
git clone ssh://git@git.ohkeji.cn:23/wmq/lingxi-web.git
|
||||
cd lingxi-web
|
||||
|
||||
# 先配置并启动 Telegram Gateway
|
||||
cp telegram-gateway/.env.example telegram-gateway/.env
|
||||
# 编辑 telegram-gateway/.env，配置 TG_API_ID、TG_API_HASH 和强随机密钥
|
||||
docker compose --env-file telegram-gateway/.env \
|
||||
-f telegram-gateway/docker/docker-compose.yml up -d --build
|
||||
|
||||
# 再启动灵犀跨境平台
|
||||
cp .env.example .env
|
||||
# 编辑 .env 并替换全部占位值
|
||||
docker compose --env-file .env build
|
||||
@@ -27,6 +35,8 @@ docker compose exec api node -e "fetch('http://127.0.0.1:3100/health/ready').the
|
||||
docker compose logs --tail=100 api whatsapp-gateway web
|
||||
```
|
||||
|
||||
平台的 `TELEGRAM_GATEWAY_URL` 指向网关 `/api` 地址。生产环境应通过私有网络连接，不把 Gateway 管理接口直接暴露公网。详细配置见 [Telegram Gateway 接入指南](TELEGRAM-GATEWAY.md)。
|
||||
|
||||
## 3. 生产入口
|
||||
|
||||
在 Compose 外层部署 Caddy、Nginx 或云负载均衡：
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# 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 可用。
|
||||
@@ -10,6 +10,7 @@
|
||||
| 邮件协议 | `npm run test:email-protocol --prefix server` | IMAP/SMTP 协议 |
|
||||
| 邮件 API E2E | `npm run test:email-api --prefix server` | 真实测试邮件服务链路 |
|
||||
| WhatsApp 网关 | `npm test --prefix whatsapp-gateway` | 路由、状态、消息与可靠性 |
|
||||
| Telegram 网关 | `npm run build --prefix telegram-gateway`、`npm test --prefix telegram-gateway` | NestJS 编译、业务服务、路由、迁移与网关逻辑 |
|
||||
| 浏览器 E2E | `npm run test:e2e` | 桌面/移动端主要用户路径 |
|
||||
|
||||
## 提交前最低要求
|
||||
|
||||
Reference in New Issue
Block a user