chill-remna-bot — документация

Что умеет бот

Один бинарь на Go, запуск в Docker. База — SQLite или PostgreSQL (бот поднимает Postgres сам). Конфиг хранится в БД зашифрованным и переживает перезапуск.

stable уже в main → образ :latest dev пока в ветке dev → образ :dev (превью)

Для пользователя

📦 Подписки 1/3/6/12 мес stable

Сроки и цены задаёте вы. Подписка активируется сразу после оплаты — ссылка приходит в чат.

🎁 Триал stable

Бесплатный пробный период одной кнопкой, один раз на аккаунт.

♻️ Продление stable

Время добавляется к текущему сроку; счётчик трафика при платном продлении обнуляется.

💼 Кошелёк в рублях stable

Пополнить и платить с баланса, прогноз «на сколько хватит», промокоды. Суммы пополнения = ценам тарифов, своя сумма не больше самого дорогого тарифа.

🎟 Промокоды и рефералка stable

Бонус на баланс или дни подписки; личная ссылка-приглашение с бонусом.

🔗 Автопривязка к панели stable

Если учётка уже была в панели (по telegramId или username с TG ID) — бот свяжет её при регистрации; триал таким недоступен (анти-абуз).

➕ Доп-подписка (add-on) stable

Опциональная вторая подписка в панели (суффикс _addsub) со своими internal-сквадами и лимитом трафика. Срок, стратегия сброса и лимит устройств наследуются от основной. Выключена по умолчанию.

📱 Mini App stable

Приложение-кнопка внутри Telegram: покупка, продление, баланс, промокоды и рефералка — без выхода из чата.

🌐 Веб-кабинет stable

Личный кабинет сайтом в браузере (вход через Telegram или e-mail+пароль). На настраиваемом пути, с noindex, anti-fingerprint и локальным хостингом флагов — ничего со сторонних CDN. P2P со скриншотом прямо в кабинете, опциональная модерация новых регистраций.

⬇️ Экран «Подключить» stable

Подтягивает приложения под все платформы (iOS / Android / Windows / macOS / Linux / TV) со страницы подписки и импортирует ключ в один тап; QR для переноса на другое устройство.

🔄 Сброс устройств stable

Отключить все свои устройства одной кнопкой — в боте, Mini App и веб-кабинете. Ключи доступа обновятся, старые устройства отключатся; чтобы снова пользоваться, обновите подписку на нужных устройствах.

Для администратора всё в Telegram

💸 Продажи stable — тарифы (быстрый мастер или тонкая настройка: цена, трафик ГБ, HWID на тариф, стратегия сброса), триал, сквады, все платёжки, история платежей с итогами, аналитика выручки, чеки самозанятого (МойНалог).
📣 Маркетинг stable — промокоды, реферальная программа, рассылка всем пользователям, автонапоминания.
🎨 Интерфейс stable — свои баннеры на каждый раздел, премиум-эмодзи, контакты, текст соглашения.
👥 Пользователи stable — блокировка бота и/или подписки раздельно, вайтлист, доступ к P2P, удаление, ручная связка с панелью.
🛠 Система stable — статус панели, самообновление с выбором канала (stable/dev), уведомления об обновлениях, вебхуки, Mini App, веб-кабинет, поддомен подписок, лог API-запросов.
🖱 Редактирование «на месте» stable — экраны админки и пользователя обновляются прямо в текущем сообщении (общие баннеры разделов вместо «удалить+прислать заново»); меню реорганизованы по UX-практикам Telegram-ботов.
➕ Доп-подписка в продажах stable — управление add-on подпиской: трафик B, internal-сквады B, вкл/выкл прямо в разделе «Продажи».
📨 Контакты ссылкой/@юзернеймом stable — поддержку и группу можно задать как https://t.me/... или @username.
🖌 Свой дизайн мини-аппа и кабинета stable — смонтируйте папку /custom со своими файлами: они перекроют вшитую статику (index.html общий, miniapp.html/cabinet.html раздельные), правки видны без перезапуска.

🔒 Безопасность: автоблок скам-регистраций; экранирование имён (нет HTML-инъекций); верификация вебхуков и защита платежей от дублей; бот управляет в панели только аккаунтами этого пользователя (по telegramId/username — чужие учётки не трогает даже с тегом бота); доступ в админку только у ADMIN_TELEGRAM_ID; конфиг в БД зашифрован.

🧪 Надёжность и CI: восстановление после паник, отправка с учётом лимитов Telegram (429), корректное завершение фоновых задач при остановке; в CI — govulncheck (жёсткий гейт по известным CVE) и golangci-lint v2.

Каналы релизов

Образы собирает CI и публикует в GHCR. Канал выбирается тегом образа — и прямо в боте: Система → Обновление → канал.

🟢 Stable main

ghcr.io/mrvibecodic/chill-remna-bot:latest

Собирается из ветки main. Рекомендуется для продакшена — сюда попадает только проверенное.

🟣 Dev (превью) dev

ghcr.io/mrvibecodic/chill-remna-bot:dev

Собирается из ветки dev. Новые возможности появляются здесь раньше и после проверки попадают в stable.

↻ Переключить канал можно без потери данных — состояние живёт в томе bot-data. После смены канала бот предложит обновиться на соответствующий образ.

Установка за 4 шага

Образ собирает CI и публикует в GHCR: ghcr.io/mrvibecodic/chill-remna-bot:latest. На сервере — только взять docker-compose.yml, вписать два значения и запустить. Никакой сборки на сервере.

Нужно заранее: Linux-сервер с Docker и Docker Compose v2, работающая панель Remnawave, токен бота от @BotFather и ваш Telegram ID от @userinfobot.

Папка и compose-файл

mkdir -p /opt/remnachillbot && cd /opt/remnachillbot
curl -fsSL -o docker-compose.yml \
  https://raw.githubusercontent.com/Mrvibecodic/chill-remna-bot/main/docker-compose.yml

Впишите два значения в docker-compose.yml:

BOT_TOKEN: "123456789:AAEabc..."   # токен от @BotFather
ADMIN_TELEGRAM_ID: "000000000"      # ваш Telegram ID (число)

Запуск

docker compose pull
docker compose up -d

Откройте бота и отправьте /start — пройдёт мастер настройки (язык, БД, подключение к панели).

Порты 80/443 нужны только для встроенного HTTPS вебхуков (см. ниже). Для базовой продажи их открывать не обязательно.

Мастер настройки

Запускается при первом /start от админа (или командой /setup). Шаги с пояснениями:

Язык — RU/EN интерфейса.
База данных — SQLite (старт, до нескольких тысяч юзеров) или PostgreSQL 17 (бот поднимает контейнер сам). Переключение позже — миграция встроена.
Расположение — бот в одной docker-сети с панелью (локально, рекомендуется) или удалённо через публичный HTTPS-домен панели.
Тип установки панели — официально (Caddy) или скрипт eGames (nginx, защита кукой) — от этого зависит, какие данные доступа спросит бот.
URL и API-токен панели (роль API; обычный логин не подойдёт).

Админка

Меню админа открывается автоматически (ваш ID в ADMIN_TELEGRAM_ID). Разделы:

💸 Продажи stable

Быстрая и тонкая настройка тарифов (цена, трафик, HWID, стратегия сброса NO_RESET/DAY/WEEK/MONTH/MONTH_ROLLING), триал, сквады, платёжки, история и аналитика, лог заказа (.log), чеки МойНалог.

➕ Доп-подписка stable

В разделе «Продажи»: включить add-on подписку B, задать её лимит трафика и internal-сквады. Вторая ссылка пользователю не выдаётся — подписка создаётся в панели как второй аккаунт с суффиксом _addsub.

📣 Маркетинг stable

Промокоды (КОД ТИП ЗНАЧЕНИЕ [ЛИМИТ] [ДНЕЙ]), рефералка, рассылка с предпросмотром, напоминания.

🎨 Интерфейс stable

Баннеры на каждый раздел (1280×640), премиум-эмодзи, контакты (поддержка+группа), соглашение. Контакты можно задать ссылкой или @username stable.

👥 Пользователи stable

Карточка с раздельным состоянием бота и подписки. Блок/разблок: бот+подписка / только подписка / только бот — меню показывает лишь применимые опции. Блок подписки = статус DISABLED в панели.

🛠 Система stable

Статус панели, /update с выбором канала (stable/dev), проверка и уведомления об обновлениях, вебхуки, Mini App, веб-кабинет, поддомен подписок, лог API (200 записей), перенастройка.

🛒 Витрина stable

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

🖱 Экраны «на месте» stable

Подразделы редактируются прямо на баннере родительского раздела — без мельтешения «удалить+прислать». Меню реорганизованы по UX-практикам Telegram-ботов.

🧾 Лог заказа: каждый шаг каждой оплаты (счёт → вебхук → перепроверка по API → действия в панели → дубли → реконсилятор) пишется в журнал. По ext_id платежа или Telegram ID бот пришлёт весь журнал .log-файлом. Хранение — 90 дней.

Способы оплаты stable

Каждый включается отдельно. Цены задаются в рублях.

Метод	Что это	Валюта
P2P	Перевод на карту, подтверждение вручную	₽
Telegram Stars	Встроенная валюта Telegram	⭐ (≈ из ₽)
ЮKassa	Карты/СБП, вебхук с перепроверкой	₽
CryptoBot	Крипта по курсу, цены в ₽ (фиат-режим)	₽ → крипта
Platega	Карты РФ / СБП (QR), перепроверка по API	₽
Tribute	Подписка через Tribute, продления по вебхуку	по кабинету

Идемпотентные платежи + фоновый реконсилятор: если вебхук не дошёл, бот сам перепроверит статус у провайдера и довыдаст подписку — деньги не теряются.

Вебхуки

ЮKassa, CryptoBot, Platega, Tribute и панель подтверждают события вебхуком. Внутри контейнера бот слушает порт 8080.

Путь	Назначение
`GET /healthz`	проверка живости
`POST /webhook/yookassa`	ЮKassa
`POST /webhook/cryptobot`	CryptoBot
`POST /webhook/platega`	Platega
`POST /webhook/tribute`	Tribute
`POST /webhook/remnawave`	события панели

Способ A — встроенный HTTPS (рекомендуется)

Бот сам получает сертификат Let's Encrypt и слушает 80/443. Направьте домен A-записью на сервер бота, затем в админке: Система → Вебхуки → Публичный HTTPS (вкл) → Домен → Применить. Бот пропишет порты в compose и перезапустится.

Способ B — за reverse-proxy панели

Бот отдаёт plain HTTP на 8080; HTTPS терминирует прокси панели — проксируйте /webhook/ → http://remnabot:8080. Если включены Mini App / веб-кабинет, этого мало: они живут на других путях того же порта (/miniapp/, /api/, путь кабинета, /flags/) — проксируйте на бот весь домен (location /) и обязательно передавайте X-Forwarded-Proto: https, иначе кабинет ответит «требуется HTTPS». Готовый пример nginx — в README, раздел «Reverse-proxy и безопасность».

🛡 Прод — reverse-proxy: для Mini App и веб-кабинета не выставляйте бинарь напрямую в интернет. Caddy/nginx или Cloudflare перед ботом: TLS с wildcard-сертом *.домен (индивидуальный серт светит хост в Certificate Transparency — кабинет легко найти), бот на 127.0.0.1:8080 под обычным пользователем, фаервол наружу только 80/443, скрытый origin, fail2ban/CrowdSec; кабинет, панель и страницу подписки — на разных доменах. Подробнее — в README.

Команды

Команда	Кому	Действие
`/start`	всем	старт; новый пользователь регистрируется автоматически
`/buy`	всем	открыть выбор тарифа
`/support`, `/paysupport`	всем	контакт поддержки (чек-лист Telegram для Stars)
`/terms`	всем	текст соглашения
`/status`	админу	связь с панелью + статистика и ресурсы
`/setup`	админу	пройти мастер заново
`/update`	админу	скачать свежий образ (канал stable/dev) и перезапуститься
`/p2p`, `/emoji`, `/welcome`	админу	быстрый вход в P2P / эмодзи / баннер

Переменные окружения

Задаются в docker-compose.yml. Обязательны только первые две.

Переменная	Обяз.	По умолчанию	Описание
`BOT_TOKEN`	✅	—	токен бота от @BotFather
`ADMIN_TELEGRAM_ID`	✅	—	ваш Telegram ID — доступ в админку
`DATA_DIR`		`/data`	каталог данных (том `bot-data`)
`DB_KIND`		—	`sqlite`/`postgres`; обычно задаёт мастер
`DATABASE_URL`		—	DSN Postgres при ручном подключении
`SECRET_KEY`		авто	ключ шифрования настроек (файл `/data/secret.key`)
`CUSTOM_STATIC_DIR`		`/custom`	папка со своим дизайном мини-аппа/кабинета (оверлей поверх вшитой статики)
`PANEL_CONTAINER`		`remnawave`	имя контейнера панели (режим «Локально»)
`COMPOSE_HOST_DIR`		`/opt/remnachillbot`	путь к папке бота на хосте

SECRET_KEY критичен: без него не прочитать зашифрованные настройки. Не теряйте secret.key из тома bot-data.

Обновление и бэкап

Обновление

Команда /update или кнопка в Система: бот делает docker compose pull && up -d через одноразовый контейнер-контроллер и перезапускается. Можно выбрать канал — stable (:latest) или dev (:dev). Раз в сутки бот сам сверяется с GitHub и, когда новый образ уже собран CI, присылает админу changelog с кнопкой «Обновить» (самоудаляется через 60 сек).

Бэкап

Всё состояние — в томе bot-data (SQLite-файл + secret.key). Бэкап = копия тома. Для Postgres — pg_dump. Конфиг зашифрован, поэтому без secret.key не восстановить.

FAQ

Чем отличается канал dev от latest? :latest собирается из ветки main (стабильное), :dev — из ветки dev (новые возможности раньше). Канал переключается в боте без потери данных.
Нужен ли отдельный nginx/Caddy для вебхуков? Нет — у бота есть встроенный HTTPS (способ A). Либо проксируйте через существующий reverse-proxy панели.
Работает ли веб-кабинет за reverse-proxy? Да, встроенный HTTPS не нужен: кабинет отдаётся тем же портом, что и вебхуки. Но проксировать надо весь домен (location /), а не только /webhook/, и передавать X-Forwarded-Proto: https. Пример конфига — в README.
Можно ли поставить свой дизайн мини-аппа и кабинета? Да — смонтируйте папку со своими файлами в /custom: они перекроют вшитые (index.html общий, miniapp.html/cabinet.html — раздельные), правки видны без перезапуска. Подробности — в README.
Что если вебхук не дошёл? Реконсилятор перепроверит платёж у провайдера и довыдаст подписку.
Можно ли мигрировать SQLite → Postgres? Да, миграция встроена; переключение в мастере/настройках.
Бот трогает чужие аккаунты в панели? Нет — только привязанные к этому Telegram ID; чужие не меняет даже при совпадении тега.
Где взять API-токен панели? В дашборде Remnawave создайте API-token с ролью API.