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.
2026-08-01 18:38:20 +08:00
parent af49d22ca7
commit 06112602ec
142 changed files with 23107 additions and 7 deletions
@@ -0,0 +1,90 @@
+# Production deployment
+
+## Prerequisites
+
+- Docker Desktop with the WSL 2 engine
+- Telegram `TG_API_ID` and `TG_API_HASH`
+- Strong, unique `DB_PASSWORD` and `JWT_SECRET`
+
+Never commit `.env` or `tdlib_data/`. Existing Telegram API credentials that
+have previously appeared in scripts should be rotated in Telegram's developer
+portal before exposing this service publicly.
+
+## Windows setup
+
+Run the following once in an **Administrator PowerShell**, then restart Windows:
+
+```powershell
+wsl --install --no-distribution
+```
+
+After restart, open Docker Desktop and wait until the Linux engine reports that
+it is running.
+
+## Configure
+
+Copy `.env.example` to `.env` and set at least:
+
+```dotenv
+NODE_ENV=production
+DB_USERNAME=postgres
+DB_PASSWORD=<strong-random-password>
+DB_DATABASE=telegram_gateway
+JWT_SECRET=<at-least-32-random-bytes>
+TG_API_ID=<telegram-api-id>
+TG_API_HASH=<telegram-api-hash>
+CORS_ORIGINS=https://your-control-plane.example
+```
+
+Production uses migrations and keeps TypeORM synchronization disabled.
+
+## Start
+
+From the project root:
+
+```powershell
+docker compose --env-file .env -f docker/docker-compose.yml up -d --build
+docker compose --env-file .env -f docker/docker-compose.yml ps
+```
+
+Readiness and API documentation:
+
+- `GET http://127.0.0.1:3000/api/admin/ready`
+- `GET http://127.0.0.1:3000/api/admin/health`
+- `http://127.0.0.1:3000/api/docs`
+
+## Verify
+
+```powershell
+npm run build
+npm test -- --runInBand
+npm run test:e2e -- --runInBand
+node test/real-readonly-smoke.js
+```
+
+The real smoke test uses the session selected by `TG_SESSION_DIR` and performs
+read-only calls only: authorization state, connection, current identity, public
+chat lookup, and chat listing.
+
+## Persistent data
+
+Docker volumes preserve:
+
+- PostgreSQL data
+- Redis data
+- uploaded files
+- TDLib authorization/session databases
+
+Back up PostgreSQL and the `tdlibdata` volume together. Losing `tdlibdata`
+requires Telegram account authorization again.
+
+## Operational behavior
+
+- `/health` is a liveness check.
+- `/ready` returns failure if PostgreSQL or Redis is unavailable.
+- Telegram workers wait for native TDLib initialization before an account is
+  marked started.
+- Active account sessions restart automatically after application restart.
+- Incoming TDLib updates are stored, mapped to webhook events, and delivered
+  through the retry queue.
+- Webhook, proxy, password, audit, message-job, and admin data are tenant scoped.