Пример: хаб за NAT, n8n, бот и CI

Сквозной пример — как связать всё, что вокруг хаба: вебхуки выкладок, API-токены, nkt-edge с ролями, n8n, бота Telegram и проверку из CI. Каждый шаг ссылается на свою страницу с подробностями; здесь — как это складывается вместе и в каком порядке настраивать.

Что есть и чего хотим

Есть:

• хаб — мини-ПК в офисе за NAT, наружу не открыт;
• web1 и db1 — VPS в группе prod; на web1 магазин — compose-стек с сайтом shop.example.com;
• gate — самый дешёвый VPS с белым адресом и именем gate.example.com (для nkt-edge);
• n8n в облаке и чат команды в Telegram;
• репозиторий магазина на GitHub, образ собирает GitHub Actions.

Хотим:

1. push тега → CI собирает образ, проверяет сухим прогоном и только потом выкладывает;
2. хост лёг, новые проблемы, выкладка упала → сообщение в чат с кнопками «Обзор», «Журнал», «Повторить»;
3. каждую ночь сухой прогон всех проверок; не прошёл — журнал в чат;
4. каждый час — бан адресов из внешнего списка на всех хостах;
5. упавшая выкладка → задача в GitHub с журналом;
6. порты и сертификат магазина проверяются так, как их видит интернет.

Схема

GitHub Actions ──HTTPS──▶ gate: nkt-edge ◀── туннель 8444 ── хаб (за NAT)
n8n (облако)  ──HTTPS──▶   роли: вебхуки, API,              │  │
                           проверки снаружи                  │  └─SSH─▶ web1, db1
                                                             │
хаб ──HTTPS──▶ api.telegram.org   (бот: хаб опрашивает сам)  │
хаб ──HTTPS──▶ n8n (облако)       (исходящий вебхук)  ◀──────┘

Наружу открыт только gate (443, 80 для certbot, 8444 для туннеля). Хаб входящих соединений не принимает вовсе: к Telegram и n8n он ходит сам, а всё, что приходит снаружи, — через туннель, который хаб держит к edge.

Шаг 1. nkt-edge на gate

1. Добавьте gate в хаб как обычный хост (достаточно SSH).
2. «Выкладки» → nkt-edge → «Установить на хост»: хост gate, имя gate.example.com, роли вебхуки, API и проверки снаружи.
3. Задание выпустит сертификат, поставит службу и подключит хаб; карточка покажет «подключён», адреса вебхуков и API.

Подробно — nkt-edge. API и вебхуки можно развести по разным edge (разные VPS и имена) — тогда захват одного VPS не затрагивает другую роль.

Проверка: «Проверить снаружи» у edge → shop.example.com, порты 80, 443, HTTPS — DNS ведёт на web1, оба порта open, сертификат годен. С этого момента мастер «Сайтов» и сухой прогон проверяют сайт тоже с edge (пометка «проверено снаружи с nkt-edge gate.example.com»).

Шаг 2. Конвейер магазина

«Выкладки» → «Новый конвейер» → compose-стек на web1 с блоком site: (shop.example.com) — как в примерах. «Сухой прогон» один раз вручную: выберите галочки проверок — выбор запомнится у конвейера, ночной прогон и бот возьмут те же.

«Вебхук» конвейера → вкладка «Через edge» — адрес https://gate.example.com/hooks/… и секрет; их — в секреты GitHub (NKT_HOOK_URL, NKT_HOOK_SECRET), как в примерах CI/CD.

Шаг 3. Токены: для CI и для n8n

«О системе» → «API-токены» → «Новый токен» — два отдельных, чтобы отзывать по одному:

Токен	Роль	Пределы	Через edge	Срок
ci	администратор (сухой прогон — действие)	хосты web1	да	365 дней
n8n	администратор (бан, сухой прогон)	группа prod	да	365 дней

Строку nkt_… каждого скопируйте сразу — она показывается один раз. Пределы держат токены в рамках: ci не дотянется ни до чего, кроме конвейеров web1, n8n — кроме хостов prod. Подробно — API и токены.

Шаг 4. CI: сухой прогон перед выкладкой

В workflow GitHub Actions перед вызовом вебхука — шаг «Сухой прогон на хабе»: NKT_URL=https://gate.example.com, ключ и секрет токена ci — из строки nkt_<ключ>_<секрет>. Прогон не прошёл — шаг падает, вебхук не вызывается, журнал проверок — в выводе CI.

Шаг 5. Бот Telegram

1. @BotFather → /newbot → токен.
2. «Оповещения» → «Настройка» → «Бот Telegram» → «Настроить»: токен, затем добавьте бота в чат команды и напишите /start — он назовёт номер чата.
3. Чат: роль администратор, оповещения — да. «Кому можно действовать» — id дежурных (бот назовёт свой каждому на /id). События — «не отвечает», «новые проблемы», «задание не выполнено», «выкладка не прошла».

Теперь в чате: оповещения с кнопками «Обзор», «Проблемы», «Журнал», «Повторить»; команды /status, /hosts, /deploy shop (после кнопки «Выложить»), /ban 198.51.100.7. Подробно — Боты.

Шаг 6. n8n: ночной прогон и бан по списку

1. Узлы nkt — архивом из релиза в каталог своих узлов n8n (установка). Для n8n в облаке без своих узлов — n8n на своём сервере или узел «HTTP Request» с подписью из примера.
2. Учётные данные nkt Hub API: Hub URL https://gate.example.com, строка токена n8n, Signed Requests. «Test» покажет «Token "n8n" (admin)».
3. Импортируйте из integrations/n8n/examples:
   • nightly-dry-run.json — укажите номер конвейера магазина и чат;
   • ban-from-blocklist.json — адрес своего списка.

Шаг 7. Упавшая выкладка → задача в GitHub

1. В n8n — процесс: nkt Trigger (события: «Deployment Failed») → GitHub: Create Issue: в заголовке — выражение с $json.pipeline.name, в тексте — $json.error, $json.tag и ссылка на хаб.
2. Production URL триггера — в хаб: «Оповещения» → «Настройка» → «Исходящие вебхуки» → «Новый адресат», события — «выкладка не прошла». Секрет, который покажет хаб, — в поле Signing Secret триггера.
3. «Проверить» у адресата — n8n получит событие test (триггер его пропустит: событие не выбрано) и ответит 200.

Хаб шлёт в n8n сам — входа для этого не нужно. Подробно — исходящие вебхуки.

Что получилось

Событие	Что происходит
push тега	CI собирает образ → сухой прогон через edge (токен ci) → вебхук через edge → выкладка; итог — в чат
выкладка упала	сообщение в чат с «Журнал» и «Повторить»; задача в GitHub через n8n
web1 не отвечает	сообщение в чат с «Обзор»; вернулся — ещё одно
ночь	n8n — сухой прогон магазина (токен n8n); не прошёл — журнал в чат
каждый час	n8n — бан адресов из списка на хостах prod
мастер сайтов, сухой прогон	порты и сертификат — с gate, как видит интернет

Проверьте целиком

• [ ] edge «подключён», роли — вебхуки, API, проверки снаружи;
• [ ] «Проверить снаружи» — оба порта open, сертификат годен;
• [ ] «Пробное сообщение» у чата бота дошло;
• [ ] «Test» учётных данных в n8n — «Token "n8n" (admin)»;
• [ ] «Проверить» у исходящего вебхука — ответ 200;
• [ ] тег в тестовой ветке проходит весь путь до сообщения в чате.

Что открыто и что будет, если…

• Захвачен gate. Секретов там нет: вебхуки подписаны, API — только подписанные запросы (секрет токена через edge не идёт), подпись одноразовая. Отключите edge («Забыть»), поставьте новый — токены и секреты конвейеров менять не нужно.
• Утёк токен n8n. «Отозвать» в «API-токенах» — действует сразу; до отзыва — только хосты prod и только вызовы автоматизации, без терминала, файлов и управления хабом. Все вызовы — в журнале действий от token:n8n.
• Кто-то нажал «Повторить» в чате. Сработает только у дежурного из списка и только после кнопки подтверждения; в журнале — telegram:<имя>.