From fd28f838a6918bd5f041d67cff9ed2ee3c35a021 Mon Sep 17 00:00:00 2001 From: Roman Buryan Date: Wed, 14 Oct 2026 13:00:30 +0300 Subject: [PATCH] =?UTF-8?q?docs(bots):=20=D1=80=D0=B5=D0=B5=D1=81=D1=82?= =?UTF-8?q?=D1=80=20=D0=B1=D0=BE=D1=82=D0=BE=D0=B2=20=D0=B8=20=D1=80=D0=B0?= =?UTF-8?q?=D0=B7=D0=B4=D0=B5=D0=BB=D0=B5=D0=BD=D0=B8=D0=B5=20=D1=80=D0=BE?= =?UTF-8?q?=D0=BB=D0=B5=D0=B9;=20=D1=82=D0=BE=D0=BA=D0=B5=D0=BD=20=D0=B2?= =?UTF-8?q?=D1=8B=D0=BD=D0=B5=D1=81=D0=B5=D0=BD=20=D0=B8=D0=B7=20workflow?= =?UTF-8?q?=20F6-2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/BOTS.md | 106 ++++++++++++++++++ .../n8n/f6-2-self-service-registration.json | 8 +- 2 files changed, 110 insertions(+), 4 deletions(-) create mode 100644 docs/BOTS.md diff --git a/docs/BOTS.md b/docs/BOTS.md new file mode 100644 index 0000000..1e8cbba --- /dev/null +++ b/docs/BOTS.md @@ -0,0 +1,106 @@ +# Реестр Telegram-ботов + +**Обновлено:** 2026-10-14 +**Проверено:** все пять ботов отвечают, имена подтверждены запросом к Telegram API. + +> **Значений токенов в этом файле нет и быть не должно.** +> Токен каждого бота хранится ровно в одном месте — в `.env` соответствующего +> сервиса на сервере, права 600. Копия — в Vaultwarden. См. раздел «Ротация». + +--- + +## 1. Кто за что отвечает + +| Роль | Бот | ID | Режим работы | Кто использует | +|---|---|---|---|---| +| **Администратор** | `@Adm_buryans_bot` | 8653974364 | **опрос** (`getUpdates`) — двусторонний | `comms-agent` на CT 108 | +| **Аварии и мониторинг** | `@Buryans_AlertBot` | 8668603602 | только отправка | self-healing, бэкапы, слежение за версиями | +| **Доступы и регистрация** | `@Auth_buryans_bot` | 8698835423 | **вебхук** → n8n | workflow F6-2 (самообслуживание) | +| **Рабочие задачи** | `@Work_Buryan_bot` | 8754535508 | только отправка | задачи Gitea, еженедельный отчёт | +| **Медиа** | `@Media_buryans_bot` | 8760535198 | только отправка | медиа-стек (Sonarr, Radarr, Plex, Jellyfin) | + +Логика разделения простая: **один бот — одна роль — один владелец — одно место +хранения токена.** Когда администратор, аварии и регистрация сидят на одном +токене, невозможно ни понять, от кого пришло сообщение, ни отозвать доступ +частично — а именно это и произошло 14.10.2026, когда три потребителя +одновременно опрашивали бота Auth. + +--- + +## 2. Правила, которые нельзя нарушать + +1. **Один вебхук на всю инфраструктуру.** Вебхук — только у бота доступов + (`@Auth_buryans_bot`). Telegram не разрешает одновременно вебхук и опрос: + при попытке получить `TelegramConflictError` и бот перестаёт работать. +2. **Один опрашивающий бот.** Опрос — только у администратора + (`@Adm_buryans_bot`). Два опрашивающих с одним токеном конфликтуют между + собой точно так же, как опрос с вебхуком. +3. **Остальные три бота — только отправка.** У них не должно быть ни вебхука, + ни опроса. Проверять командой из раздела 6. +4. **Токен — никогда в Git.** Ни в реестре, ни в workflow, ни в скрипте. + Только `.env` (права 600) и Vaultwarden. +5. **Новый бот — новая строка в этой таблице.** Без записи в реестре бот + считается временным и подлежит удалению. + +--- + +## 3. Маршрутизация сообщений + +| Событие | Кто отправляет | Куда | +|---|---|---| +| Команды `/status`, `/issues`, `/runbook`, `/restart` | администратор, двусторонний | чат владельца и комната Matrix | +| Падение сервиса, сбой бэкапа, восстановление | `@Buryans_AlertBot` | чат владельца | +| Доступна новая версия образа | `@Buryans_AlertBot` | чат владельца + задача в Gitea | +| Заявка на доступ, одобрение, выдача | `@Auth_buryans_bot` | чат владельца, кнопки одобрения | +| Новая задача или изменение в Gitea | `@Work_Buryan_bot` | чат владельца | +| События медиа-стека | `@Media_buryans_bot` | чат владельца | + +Чат владельца: `273442500`. + +--- + +## 4. Где лежит токен каждого бота + +| Бот | Файл | Хост | +|---|---|---| +| `@Adm_buryans_bot` | `/opt/automation-lxc/telegram-admin-bot/.env` | CT 108 | +| `@Buryans_AlertBot` | `/opt/automation-lxc/docker-compose.yml` (окружение n8n) и `.env` бота | CT 108 | +| `@Auth_buryans_bot` | окружение workflow F6-2 (при переводе — в credentials n8n) | CT 108 | +| `@Work_Buryan_bot` | ещё не подключён | — | +| `@Media_buryans_bot` | ещё не подключён | — | + +--- + +## 5. Ротация токена + +Достаточно одного действия, потому что у каждого бота ровно один владелец: + +1. `@BotFather` → `/revoke` → выбрать бота → получить новый токен. +2. Записать новый токен в файл из таблицы раздела 4 (права 600). +3. Перезапустить соответствующий сервис: + - администратор: `pct exec 108 -- bash -c 'cd /opt/automation-lxc/telegram-admin-bot && docker compose up -d --force-recreate'` + - бот алертов: пересоздать контейнер `n8n` + - бот доступов: обновить значение в credentials n8n через веб-интерфейс +4. Убедиться, что режим доставки не сбился (раздел 6). +5. Обновить запись в Vaultwarden. + +--- + +## 6. Проверка состояния + +```bash +# на pve: проверяет всех ботов — имя, режим, вебхук (токены не печатает) +bash /root/verify-bots.sh /root/bots-tokens.env +``` + +Ожидаемая картина: вебхук — только у `AUTH`, у остальных пусто. + +--- + +## 7. История + +| Дата | Изменение | +|---|---| +| 2026-10-14 | Реестр создан. Обнаружено, что `@Adm_buryans_bot` использовался тремя потребителями одновременно (вебхук n8n, бот на VPS, бот на CT 108) — источник конфликта `TelegramConflictError`. | +| 2026-10-14 | Дубль админ-бота на VPS остановлен, два бота на CT 108 и VPS сведены в одного `comms-agent`. | +| 2026-10-14 | Выданы пять отдельных ботов; назначены роли согласно разделу 1. | diff --git a/workflows/n8n/f6-2-self-service-registration.json b/workflows/n8n/f6-2-self-service-registration.json index a0dcf66..05ece32 100644 --- a/workflows/n8n/f6-2-self-service-registration.json +++ b/workflows/n8n/f6-2-self-service-registration.json @@ -21,7 +21,7 @@ { "parameters": { "method": "POST", - "url": "https://193.233.210.184/tg-api/bot8653974364:AAHHM4adpj1Slwi0qcPDm5IgIt6l7gl2Sxo/sendMessage", + "url": "https://193.233.210.184/tg-api/bot/sendMessage", "sendHeaders": true, "headerParameters": { "parameters": [{ "name": "Content-Type", "value": "application/json" }] }, "sendBody": true, @@ -62,7 +62,7 @@ "sendHeaders": true, "headerParameters": { "parameters": [ - { "name": "Authorization", "value": "Bearer 1feyihg2W65EZv8MlreEooS7I8F6HJmXaBtY1bWhTr5AmDBkfkI14ndb8Ttk" }, + { "name": "Authorization", "value": "Bearer " }, { "name": "Content-Type", "value": "application/json" } ] }, @@ -79,7 +79,7 @@ { "parameters": { "method": "POST", - "url": "https://193.233.210.184/tg-api/bot8653974364:AAHHM4adpj1Slwi0qcPDm5IgIt6l7gl2Sxo/sendMessage", + "url": "https://193.233.210.184/tg-api/bot/sendMessage", "sendHeaders": true, "headerParameters": { "parameters": [{ "name": "Content-Type", "value": "application/json" }] }, "sendBody": true, @@ -95,7 +95,7 @@ { "parameters": { "method": "POST", - "url": "https://193.233.210.184/tg-api/bot8653974364:AAHHM4adpj1Slwi0qcPDm5IgIt6l7gl2Sxo/sendMessage", + "url": "https://193.233.210.184/tg-api/bot/sendMessage", "sendHeaders": true, "headerParameters": { "parameters": [{ "name": "Content-Type", "value": "application/json" }] }, "sendBody": true,