# Telemax Двусторонний мост между мессенджером **MAX** и **Telegram**: один номер MAX превращается в Telegram-группу с форум-темами (по одной на каждый MAX-чат), и переписка идёт в обе стороны как в едином окне. > ⚠️ Неофициальный проект. Не связан с MAX и Telegram, работает поверх вашего собственного номера/аккаунта на свой страх и риск — см. [«Отказ от ответственности»](#отказ-от-ответственности). ## Возможности - Текстовые сообщения, фото, файлы, голосовые, видео и видео-кружки (обе стороны) - Стикеры — статичные и анимированные (обе стороны) - Геолокация и контакты (обе стороны) - Опросы: создание и голосование в обе стороны, актуальный счёт по команде `/poll` - Удаление сообщений в обе стороны; удаление чата в MAX удаляет и его тему в Telegram - Ответы на сообщения (reply) — нативные в обе стороны, с переходом к оригиналу - Пересылка сообщений — обычным drag-forward в Telegram, с автоматической пометкой источника - 🎛 Пульт управления (`/panel`, закреплён в теме группы): поиск контакта MAX по номеру/нику и старт чата в один тап, пауза/возобновление MAX, бан/разбан чатов, ссылка и API-ключ веб-панели, обновление — всё кнопками - Управление MAX-группами прямо из Telegram: создание, приглашение/удаление участников, переименование, описание, выход, удаление - Уведомления о звонках (входящий/завершённый/пропущенный) — только текстом, без передачи аудио - Веб-панель мониторинга: статус подключения, живые метрики, экран первой авторизации - `/reboot` — полный сброс и пересинхронизация Telegram-стороны без повторной авторизации в MAX - `/kill` — аварийный сброс: то же самое + разлогинивание MAX-сессии и полное стирание сохранённых данных - `/version` — проверка обновлений и обновление по кнопке прямо из Telegram (см. [«Обновление»](#обновление)) - `/apikey` — напомнить ключ веб-панели, если потерялся - Прокси для Telegram (SOCKS5/HTTP) — если сервер выходит в Telegram только через прокси; MAX при этом идёт напрямую (см. [«Прокси для Telegram»](#прокси-для-telegram)) - Уведомления о сбоях (потеря связи с MAX, ошибки доставки, внутренние ошибки) прямо в Telegram-группу, с защитой от спама - 🐞 Приём баг-репортов в личку бота с двусторонней перепиской (опционально, включается `BUGREPORT_INBOX`); по умолчанию посторонним, написавшим боту в личку, показывается ссылка на баг-репорт-бот проекта - Аватарка группы и цвет иконки каждой темы форума выставляются автоматически Полный список команд бота — `/help` прямо в боте после запуска. ## Пульт управления Команда `/panel` (и закреплённое в теме группы сообщение) открывает пульт с кнопками — меню прямо в Telegram-группе, без захода в веб-панель: - **👤 Найти контакт** — поиск MAX-контакта по номеру или нику; из карточки результата «Начать чат» в один тап создаёт диалог и его тему. - **🚫 Управление чатами** — заглушить (бан) или вернуть чат. - **🌐 Веб-панель** — ссылка для входа и API-ключ. - **⚙️ Система** — пауза MAX на время (10 мин / 1 час / 1 сутки / до ручного возобновления), обновление, пересинхронизация, список команд. Пульт виден всем участникам группы, но кнопки/команды срабатывают только у администраторов. ## Требования - Docker + Docker Compose - Telegram-бот (токен из [@BotFather](https://t.me/BotFather)) и Telegram-группа с включёнными темами (forum topics), куда бот добавлен администратором **с правом «Управление темами» (Manage Topics)** — без него бот не сможет создавать темы под MAX-чаты - Номер MAX, на который будет авторизован мост ## Быстрый старт На чистом Ubuntu/Debian-сервере (по SSH, от root) — одна команда: ```bash curl -fsSL https://raw.githubusercontent.com/Trollobot/Telemax/main/install.sh | bash ``` Она сама обновит систему, поставит git, Docker и jq (если их ещё нет), склонирует проект в `/opt/telemax` и запустит интерактивную настройку. Спросит токен Telegram-бота (создаётся через [@BotFather](https://t.me/BotFather)) — id группы искать не придётся: добавьте бота в свою группу (с включёнными темами) администратором, отправьте туда любое сообщение, и скрипт сам определит нужный id. Секретные ключи сгенерирует сама, соберёт образ и запустит контейнер. Первая сборка дольше обычного (внутри образа headless-браузер для рендера анимированных стикеров) — это нормально, обычно несколько минут. В конце спросит номер телефона MAX и код из SMS прямо в консоли — переключаться в браузер для первого запуска не нужно (подробнее — [«Первая авторизация»](#первая-авторизация)). Безопасно запускать повторно. Если Docker и git уже стоят (или разворачиваете не с нуля) — то же самое, но без системной части: ```bash git clone https://github.com/Trollobot/Telemax.git cd Telemax ./setup.sh ``` Совсем руками, без интерактивных скриптов: ```bash cp .env.example .env # впишите TELEGRAM_BOT_TOKEN и TARGET_TELEGRAM_GROUP, остальное сгенерируйте: # openssl rand -hex 24 -> API_KEY # openssl rand -hex 32 -> MAX_SESSION_KEY docker compose up -d --build ``` ## Первая авторизация > ⚠️ **Не пропустите этот шаг.** Запрос номера MAX и SMS-кода появляется **в самом конце**, уже **после** многоминутной сборки образа. Легко принять «Контейнер запущен» за финал и уйти — но без авторизации мост поднят, но ни к какому аккаунту не подключён и ничего не пересылает. В конце `setup.sh` явно печатает итог: `✅ авторизован` или `⚠️ НЕ авторизован`. `setup.sh` спрашивает номер телефона MAX и код из SMS прямо в консоли — переключаться в браузер для первого запуска не нужно. После успешной авторизации сессия сохраняется зашифрованной в `.data/` — повторной авторизации при перезапуске контейнера не требуется. Веб-панель (`https://<сервер>:порт`, ключ — `API_KEY` из `.env` или команда `/apikey` в боте) нужна не для первого запуска, а для всего, что происходит позже: повторная авторизация после `/kill`, смена номера, живые метрики и логи. Если консольную авторизацию при установке пропустили (или она не удалась) — то же самое можно сделать там же. ## Безопасность Бот отвечает только внутри той Telegram-группы, что указана в `TARGET_TELEGRAM_GROUP` — любое сообщение или нажатие кнопки из другого чата (личка боту, добавление в чужую группу и т.п.) игнорируется. Внутри группы доступ разграничен: обычные участники могут читать и писать (в группу можно добавлять людей для общего обсуждения), но **команды боту выполняются только для администраторов группы** — снести сессию (`/kill`), пересобрать мост (`/reboot`), получить ключ веб-панели (`/apikey`), управлять MAX-группами может лишь админ, рядовой участник — нет. Учтите: любой участник Telegram-группы видит в ней **все** зеркалированные MAX-чаты (по теме на чат), а не какой-то один. Доступ к самой группе — чувствительная вещь, раздавайте его осознанно. Веб-панель работает по HTTPS с самоподписанным сертификатом (генерируется при первом старте, лежит в `.data/tls`) — ключ панели, SMS-код и пароль MAX не ходят по сети открытым текстом. Браузер при первом входе один раз предупредит о неизвестном издателе — это ожидаемо, нажмите «Дополнительно» → «Перейти на сайт». Если панель стоит за вашим собственным reverse proxy с настоящим TLS — поставьте `PANEL_TLS=off` в `.env`. Сертификаты российского государственного УЦ (нужны только потому, что через них выпущен TLS-сертификат самого MAX) доверяются **только** соединениям с серверами MAX — запросы к Telegram, GitHub и всему остальному проверяются исключительно по стандартному набору корневых сертификатов Mozilla (подробнее — `certs/README.md`). ## Обслуживание ```bash docker compose logs -f # логи docker compose restart # перезапуск docker compose down # остановка ``` Все состояние (сессия MAX, привязка чатов к темам) лежит в `./data` на хосте — бэкап этой папки достаточен для переноса на другой сервер. ## Прокси для Telegram Если сервер выходит в Telegram только через прокси (например, домашний сервер, где прямой доступ к `api.telegram.org` закрыт) — укажите его. **MAX при этом всегда идёт напрямую**, через прокси гоняется только Telegram-трафик. Форматы: `socks5://[логин:пароль@]хост:порт` или `http://[логин:пароль@]хост:порт`. Задать можно тремя способами: - **При установке** — `setup.sh` спрашивает про прокси ещё до проверки связи (иначе на proxy-only хосте проверка Telegram ложно упала бы), и тут же проверяет доступность через него. - **В `.env`** — переменная `TELEGRAM_PROXY`. - **В веб-панели** — вкладка Configuration → «Telegram-прокси»: кнопка «Проверить» тестирует связь через прокси вживую, «Сохранить и перезапустить» применяет его. Значение сохраняется в `./data` и перекрывает `.env`; применяется после короткого перезапуска контейнера (Telegraf задаёт прокси при старте, на лету не подменяется). ## Если что-то не работает Сама установка проходит на любом Ubuntu/Debian (проверено вплоть до Debian 13 trixie) даже на VPS с менее чем 1 ГБ RAM — окружение почти никогда не причём. Быстрее всего локализовать проблему по одному признаку — **проявляется ли бот в вашей Telegram-группе хоть как-то**: приходит ли после старта его сообщение «✅ Telemax подключён к этой группе», заводятся ли темы под MAX-чаты. - **Бота в группе не видно вообще** (ни стартового сообщения, ни тем) — он не достучался до Telegram или до группы: пункты 1–3. - **Бот активен, но сообщения из MAX не приходят** — почти всегда не завершена авторизация MAX: пункт 4. Все команды — из папки установки (`cd /opt/telemax`): 1. **Бот не достучался до Telegram (частый случай на хостингах в РФ).** На dual-stack серверах IPv6-маршрут до `api.telegram.org` бывает заблокирован, а система по умолчанию пробует сначала именно IPv6 — бот виснет на подключении, в группе полная тишина. Свежие версии форсируют IPv4 сами, так что первым делом обновитесь: `/version` в группе → «Обновить» (или `./update.sh`). Если по какой-то причине не помогло — как временный обходной путь можно прибить IPv4-адрес Telegram в `/etc/hosts`: `149.154.167.220 api.telegram.org`. 2. **Контейнер не запущен.** ```bash docker ps ``` Если в списке пусто — посмотрите причину падения (`docker compose logs --tail=50`) и поднимите заново: `docker compose up -d`. 3. **Бот добавлен в группу без нужных прав.** Он должен быть в группе администратором **с правом «Управление темами» (Manage Topics)** — без него бот не может создавать темы под MAX-чаты. И `TARGET_TELEGRAM_GROUP` в `.env` должен быть id именно этой группы. Если прав не хватает, бот сам напишет об этом в группу. 4. **Не завершена авторизация MAX — самая частая причина, когда бот в группе есть, а переписки нет.** Запрос номера и SMS-кода легко пропустить: он идёт после сборки (см. [«Первая авторизация»](#первая-авторизация)). Проверьте логи: ```bash docker compose logs --tail=30 ``` Если нет строки `Resumed session for +…` — аккаунт не подключён. Проще всего добить авторизацию, **запустив `./setup.sh` ещё раз**: он увидит, что MAX не авторизован, и предложит ввести номер и код прямо в консоли. То же самое можно сделать в веб-панели: откройте `https://<адрес-сервера>:порт`, введите `API_KEY`, затем номер и код из SMS. 5. **Не видно ключа веб-панели.** Он в `.env`: ```bash grep API_KEY .env ``` Либо спросите у бота командой `/apikey` в вашей Telegram-группе. 6. **Не открывается веб-панель.** Она работает по **HTTPS** (`https://…`, не `http://`) с самоподписанным сертификатом — браузер один раз предупредит, жмите «Дополнительно» → «Перейти на сайт». Если сервер за NAT/файрволом — проверьте, что порт (по умолчанию 3000) проброшен/открыт. 7. **Установка встала на проверке связи.** `setup.sh` в начале проверяет доступность MAX и Telegram и падает с явной ошибкой, если один из серверов недоступен (файрвол хостинга или гео-блокировка). Если установка остановилась именно на этой проверке — дело в сети сервера. Не нашли причину — заводите [Issue](https://github.com/Trollobot/Telemax/issues) с выводом `docker compose logs --tail=50` (ключи/токены из `.env` не прикладывайте). ## Обновление Раз в сутки (в случайное время) бот сам проверяет, есть ли на GitHub новые коммиты в `main`, и если да — присылает в группу сообщение с кнопками **«Обновить»** / **«Позже»**. То же самое можно спросить в любой момент командой `/version`. Технически апдейт устроен так: сам контейнер с ботом ничего не обновляет и не перезапускает — у него нет и не будет доступа ни к докеру, ни к хосту (это осознанный выбор: код, который разбирает сообщения из MAX/Telegram, не должен иметь возможность управлять сервером). Вместо этого: - Кнопка «Обновить» просто оставляет файл-маркер в `./data`. - На хосте (не в контейнере) параллельно работает **systemd-таймер `telemax-updater`**, который ставит `setup.sh` — раз в минуту проверяет этот маркер, и если он есть, запускает `update.sh` (`git pull` → пересборка образа → `docker compose up -d`). - Таймер добавлен в автозапуск (`systemctl enable`), то есть переживает перезагрузку сервера. - `update.sh` пишет в группу на каждом шаге: сразу — что начал, при ошибке (`git pull`/сборка/рестарт/контейнер не поднялся) — что именно сломалось и что мост остался на прежней версии. После успешного перезапуска бот сам напишет, до какой версии обновился. Проверить/поуправлять им можно как обычным systemd-юнитом: ```bash systemctl status telemax-updater.timer # включён ли, когда сработает в следующий раз systemctl disable --now telemax-updater.timer # выключить совсем — обновляться придётся вручную: ./update.sh ``` ## Отказ от ответственности Проект не аффилирован ни с MAX, ни с Telegram, ни с их правообладателями. Используя его, вы работаете со своим собственным аккаунтом MAX на свой страх и риск, в том числе в части соблюдения условий использования сервиса. Переписка, которую бот пересылает, временно оседает на вашем собственном сервере: в логах контейнера, в персистентном хранилище (`./data`) и в истории самой Telegram-группы. Проект не несёт ответственности за сохранность, утечку или неправомерное использование этих данных — обеспечение их безопасности (доступ к серверу, шифрование диска, ротация логов и т.д.) целиком на вас. ## Обратная связь Нашли баг или есть вопрос — напишите боту [@TelemaxSvv_bot](https://t.me/TelemaxSvv_bot) прямо в Telegram (ответим там же) или заведите [Issue](https://github.com/Trollobot/Telemax/issues). Идеями и впечатлениями можно поделиться в [Discussions](https://github.com/Trollobot/Telemax/discussions). ## Поддержать проект - Рублями: [pay.cloudtips.ru/p/3c71b5e8](https://pay.cloudtips.ru/p/3c71b5e8) - GRAM (TON): `UQALpK2PKI90-XpupOM8sRJGdwrFMsPcwQZPR0k180umXBcA` ## Разработка ```bash npm install npm run dev # сервер + Vite dev middleware на http://localhost:3000 npm run lint # проверка типов (бэкенд и фронтенд отдельно) npm test # vitest ``` ## Телеметрия Чтобы понимать, сколько инстансов моста реально работает, раз в сутки бот отправляет **анонимный** пинг: случайный идентификатор установки (UUID, генерируется один раз и хранится в `.data/install-id`) и текущую версию. **Никаких** номеров телефонов, содержимого сообщений, IP или иных персональных данных не передаётся и не хранится — только «эта установка жива, версия такая-то». Отключить полностью — добавьте в `.env`: ```bash TELEMETRY=off ``` и перезапустите контейнер (`docker compose up -d`). После этого бот не отправляет ничего.