Gatekeeper — Платформа управления закрытыми Telegram-каналами

SaaS-платформа для управления подписками на Telegram-каналы. Хост: LXC 150 (198.51.100.1), публикация через Traefik (gatekeeper.skud24.ru).

Статус (2026-07-23)

✅ API (NestJS): LIVE, LXC 150, порт 3000
✅ PostgreSQL 16: Подключена и работает
✅ Redis 7: BullMQ очереди готовы
✅ Traefik интеграция: Через traefik-ha (198.51.100.2)
✅ HTTPS/TLS: Let's Encrypt, домен gatekeeper.skud24.ru
✅ Health check: /healthz → OK

Архитектура

Модули (Phase 0 — MVP)

BotsModule — управление Telegram ботами
ChannelsModule — каналы и права доступа
PlansModule — тарифные планы
SubscribersModule — подписчики
SubscriptionsModule — управление подписками (active/grace/expired)
AccessModule — выдача доступа (approve/decline/kick)
EventsModule — доменные события
ReaperModule — автоматические операции (списание, отзыв доступа)

Технологический стек

Backend: NestJS + TypeScript, Node 22
БД: PostgreSQL 16
Cache/Queues: Redis 7 + BullMQ
Telegram: grammY библиотека
Платежи: ЮKassa, CloudPayments, Telegram Stars, CryptoBot (Phase 1)
Фронтенд: Next.js (Phase 1, не развёрнут)

API Endpoints (Phase 0)

Требуют аутентификацию через Authorization: Bearer <N8N_SERVICE_TOKEN>:

POST   /v1/bots              — Подключение бота
GET    /v1/channels          — Список каналов
POST   /v1/channels          — Создание канала
GET    /v1/plans             — Тарифы
POST   /v1/plans             — Создание тарифа
GET    /v1/subscriptions     — Подписки
POST   /v1/access            — Approve/decline/kick
POST   /tg/webhook/:botId    — Telegram webhook (для ботов)
GET    /healthz              — Health check (публичный)

Процессы (Phase 0 MVP)

1. Онбординг клиента

1. Регистрация (email/Telegram Login) → tenant создан 2. Подключение бота (token → getMe → webhook) 3. Добавление бота админом в канал 4. Создание тарифа (цена/период/каналы) 5. Генерация deep-link: t.me/<bot>?start=plan_<id>

2. Покупка подписки

1. Пользователь жмёт deep-link → видит тариф 2. Клик "Оплатить" → платёжный шлюз (ЮKassa) 3. После оплаты → подписка active, invite-link сгенерирован 4. Пользователь вступает в канал через join-request

3. Автосписание и отзыв доступа

Reaper каждые 5 минут проверяет expired подписки
Запускает subscription-reaper очередь
Soft-kick: ban → unban (мягче, чем просто remove)
События → n8n для dunning-цепочки (напоминания об оплате)

n8n интеграция

Webhook входящих событий: Ядро постит события из outbox на N8N_EVENTS_WEBHOOK_URL
Dunning процесс: n8n рассчитывает напоминания (T-3, T-1, T-0, T+1, T+3)
Reconciliation: Сверка участников канала с активными подписками
Billing: Платформенный биллинг клиентов (invoices, suspend)

Фазы разработки

| Фаза | Статус | Компоненты | |------|--------|-----------| | Phase 0 | ✅ MVP | API + Telegram бот + join-request flow | | Phase 1 | ⏳ TODO | Auth (JWT), Web кабинет (Next.js), платежи (ЮKassa/CloudPayments) | | Phase 2 | 📋 TODO | Mini App подписчика, аналитика, white-label для клиентов |

Диагностика 2026-08-18 — реальная топология прокси vs README проекта

Источник — не raw/, а прямая диагностическая сессия: пользователь не мог достучаться по SSH до 198.51.100.2 напрямую с локальной машины (Connection timed out), диагностика велась через SSH-мост n8n-skud24 (саб-workflow "SSH Execute", ka0cxJxH5Qp7bR9N).

Сервис исправен: curl https://gatekeeper.skud24.ru/healthz → 200.
Реальная топология прокси-слоя на traefik-ha (198.51.100.2) отличается от того, что описывает README.md в локальном проекте пользователя (gatekeeper-, не в vault): README описывает единый docker-compose.yml с сервисами api + postgres:16 + redis:7, поднятыми прямо на .44, с Traefik-лейблами напрямую на api. По факту на .44 крутится только лёгкий отдельный контейнер gatekeeper-proxy-gatekeeper-proxy-1 (nginx:alpine, каталог /opt/gatekeeper-proxy) в сети skud24-traefik_traefik-net (resolver le) — тот же паттерн "мини nginx-proxy контейнер per-сервис", что и у соседних *-proxy на этом хосте (см. traefik-ha). Этот nginx-proxy проксирует на LXC 150 (198.51.100.1) — порт 3000 (NestJS API) и порт 3001 (Next.js админка). Сами api/postgres/redis из README на .44 не запущены — БД/Redis/API живут на LXC 150.
README проекта не обновлён под фактическую архитектуру — правка не внесена без запроса пользователя.
Диагностика подтвердила прежнюю пометку в статусе выше (LXC 150 = 198.51.100.1, Traefik-интеграция через traefik-ha) — расхождение только в деталях прокси-слоя на .44, не в самом факте LXC-хостинга.
Как и в других SSH-диагностиках через этот мост, для выполнения команд создавались временные wrapper-workflow с паролём (см. паттерн в n8n-skud24) — все заархивированы после использования.

Узнать больше

Архитектура: /docs/telegram-subscription-platform/02-architecture.md (в PR #1)
Data Model: /docs/telegram-subscription-platform/03-data-model.md
n8n Automation: /docs/telegram-subscription-platform/04-n8n-automation.md
Roadmap: /docs/telegram-subscription-platform/05-roadmap.md

Связано с

agent-harness-n8n — Платформа автоматизации, использует Gatekeeper через n8n MCP
n8n-skud24 — Основной n8n инстанс (198.51.100.3)
traefik-ha — Реверс-прокси (198.51.100.2)
proxmox-pve3 — Физический хост LXC 150
lab-cameras — адрес 198.51.100.1 LXC 150 унаследовал от IP-камеры; из-за этого пробросы 8555/8556 вели в LXC (исправлено 2026-09-10)

Источник

GitHub PR: shelkovoymb-wq/n8nHarness#1 (claude/telegram-channels-platform-ldtz5v)
Документация в PR: docs/telegram-subscription-platform/*
Диагностическая сессия 2026-08-18 (SSH через n8n-мост, не raw/)