# 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 可用。