bot_modular — модульная платформа Telegram-бота и веб-панели

Полностью модульное решение для связки Telegram-бота и веб-панели управления домашней инфраструктурой.

Обратная связь: https://github.com/Euk0r/bot_modular-feedback

История проекта

Проект начинался с простого скрипта: периодическое сканирование локальной сети через nmap и уведомления об изменениях прописанным администраторам.

Затем приходили новые идеи, новые методы, новые возможности. В какой-то момент стало ясно, что лоскутные доработки себя исчерпали, и код нужно переписать так, чтобы бот был полностью модульным.

С нуля проект переписывался дважды — каждый раз из-за низкоуровневых архитектурных изменений. Первый раз — ради внедрения модульности. Второй — ради добавления веб-платформы с зачисткой оставшегося спагетти-кода.

С переходом на веб-управление многое поменялось. Модули стали шире и функциональнее. Они уже не просто добавляли обработчики ответов пользователей в Telegram, а начали поставлять и регистрировать собственное API на контрактной основе — как для Telegram, так и для веба. Ядро все контракты модулей собирает и выстраивает из них структуру: меню бота, карточки кабинета, REST-роуты, права доступа. С каждым коммитом модулей становилось больше, функциональность росла.

В какой-то момент стало очевидно, что боту нужен полноценный менеджер модулей. А для него, как минимум, нужен сайт. Была идея опереться на GitHub, но хотелось заодно повозиться с личным сайтом — так релизы и маркет модулей поселились здесь.

Так простой локальный скрипт превратился в публичную модульную платформу Telegram/Web-бота для управления домашней инфраструктурой.

Структура проекта

Модули делятся на четыре категории:

• core — ядро системы прав и входа (access, web_users). Выключить нельзя.
• base — базовый сервис: администрирование, менеджер модулей, журнал, бэкапы, шлюз подключений, логи, уведомления.
• extra — дополнительные возможности: сеть, мониторинг, AI-чат, планировщик, автоматизация, файловый менеджер и другие.
• dev — служебные модули для разработки и самотестов.

Модули друг друга напрямую не импортируют. Общение идёт только через контекст ядра: API-вызовы, шина событий, кеш, конфиги и права. У каждого модуля есть манифест — паспорт с версией, API-методами, правами, зависимостями и веб-роутами.

Архитектура

flowchart LR
    subgraph clients [Клиенты]
        TG[Telegram]
        BR[Браузер]
    end

    subgraph host [Хост бота]
        direction TB
        TR[Транспорты<br/>telegram + web]
        CTX[core/ctx<br/>loader, api, rights,<br/>events, cache, audit]
        MOD[Модули<br/>core / base / extra]
        DATA[(data/)]
    end

    subgraph out [Внешнее]
        direction TB
        AI[AI<br/>Ollama, llama.cpp,<br/>OpenCode]
        INFRA[Инфра<br/>ssh, smb/nfs/ftp,<br/>proxmox, docker]
        SITE[euk0r.ru<br/>маркет, релизы]
    end

    TG <--> TR
    BR <--> TR
    TR <--> MOD
    MOD <--> CTX
    CTX <--> DATA
    MOD <--> DATA
    MOD -->|outbound| AI & INFRA
    SITE -->|маркет/скелет| MOD

Как читать схему:

• Клиенты. Telegram — основное управление ботом: меню, кнопки, диалоги. Браузер — веб-панель: кабинет, мониторинг, домашняя страница.
• Транспорты. Два входных канала. transport_telegram принимает апдейты, проверяет права и раскидывает по модулям. transport_web отдаёт SPA-кабинет, REST API и WebSocket-каналы (терминал, чаты, живой мониторинг).
• core/ctx. Ядро, которое ничего не знает о предметной области, но умеет всё связывать: загрузчик находит модули и собирает их по зависимостям, реестр API соединяет вызовы, служба прав решает «можно или нет», шина событий разносит уведомления, кеш и аудит держат состояние и историю.
• Модули. Собственно функциональность. Модуль заявляет в манифесте: «вот мои API-методы, вот мои права, вот мои кнопки и карточки». Ядро из этих заявок строит меню Telegram, разделы кабинета и REST-роуты.
• data/. Всё изменяемое состояние: права, пользователи, сессии, кеши, задачи, журнал, бэкапы, секреты. Код и данные разделены: обновление кода данные не трогает.
• outbound. Ни один модуль не ходит наружу сам. Все внешние подключения — через шлюз: точки, привязки, проверки состояния, журнал вызовов. AI-модели и инфраструктура подключаются одинаково — как потребители шлюза.
• Сайт. Маркет модулей (список, файлы, контроль целостности) и релизы ядра-скелета. Бот умеет ставить и обновлять модули с сайта, сверяя целостность, с бекапом перед заменой.

Жизненный цикл прост: клиент → транспорт → проверка прав → API модуля → ответ. Новый модуль — это новая папка с манифестом: положил, включил, перезапустил.

Кабинет

Управление правами пользователей. Права выдаются отдельно для Telegram и веба, есть служебный флаг полного доступа. Видно, у кого что включено, изменения применяются сразу.

Управление API-доступом. Токены для скриптов и автоматики с ограниченной областью прав, одноразовые пропуска для живого канала, привязка Telegram-аккаунта к учётной записи кабинета.

Кабинет модулей. Каждый модуль сам предоставляет своё меню и карточки — от настроек сети до чата с AI. Недоступное пользователю не показывается вовсе.

Мониторинг с редактированием. Модули добавляют свои панели (сеть, GPU, AI-воркеры, задачи). Положение, размер и права отображения панелей правятся прямо на месте.

Домашняя страница. Редактируемые блоки, ссылки и иконки — в какой-то мере заменяет dashy. Видна без входа, правится из кабинета.

Менеджер модулей. Проверка кода на безопасность, контроль хешей файлов, установка и обновление с сайта, перезалив, удаление с выбором (кеш, секреты), секреты модулей, индикатор «ждёт рестарта» с перезапуском из кабинета.

И многое другое...

Предупреждения

Так как при установке проекта требуется sudo, крайне рекомендую самостоятельно прочитать код скрипта перед установкой. Прочитать скрипт и файлы бота в целом важно, чтобы понимать, что именно выполняется.

То же касается и самих модулей. Правило «доверяй, но проверяй» актуально всегда. Я не выкладываю то, что может навредить системе, моя цель — делиться интересными разработками. Весь код модулей доступен прямо на сайте.

Установка

Бот работает под новым пользователем с минимальными правами (создаётся скриптом). По умолчанию используется папка /var/opt/bot_modular.

Тестирование проводилось на Ubuntu 24.04.2 LTS | Arch 7.2.9-arch1-1. Список поддерживаемых платформ будет расширяться.

Установка — одним скриптом (см. команду на странице проекта).