Telemax

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 9)

Для параноиков, которым нужен Макс, но они не хотят его ставить и пользуются Телеграv

Telemax Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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-группу, с защитой от спама
- Аватарка группы и цвет иконки каждой темы форума выставляются автоматически

Полный список команд бота — `/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-группы. Проект не несёт ответственности за сохранность, утечку или неправомерное использование этих данных — обеспечение их безопасности (доступ к серверу, шифрование диска, ротация логов и т.д.) целиком на вас.

## Обратная связь

Нашли баг — заводите [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
```

Telemax

Telemax Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Telemax

Telemax Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README