docs(bots): реестр ботов и разделение ролей; токен вынесен из workflow F6-2

This commit is contained in:
root committed 2026-10-14 13:00:30 +03:00
1 parent 200dbf1284
commit fd28f838a6
2 files changed
+110 -4

No files matched your search

+106
View File
@@ -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. |
@@ -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<TELEGRAM_AUTH_BOT_TOKEN>/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 <AUTHENTIK_API_TOKEN>" },
{ "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<TELEGRAM_AUTH_BOT_TOKEN>/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<TELEGRAM_AUTH_BOT_TOKEN>/sendMessage",
"sendHeaders": true,
"headerParameters": { "parameters": [{ "name": "Content-Type", "value": "application/json" }] },
"sendBody": true,