Cluster · разработчикам

Функционал Cluster

Здесь собраны возможности ядра и ограничения их работы. Параметры операций находятся в ROUTES.md, методы модуля в SDK.md.

Профиль

Регистрация использует почту, логин и пароль. Почта подтверждается одноразовым кодом. Пароль хранится через Argon2id. Письма сохраняются в зашифрованной очереди и отправляются с повторами при ошибке SMTP.

Двухэтапный вход работает через TOTP-приложение. При настройке выдаётся резервный код. Восстановление второго фактора выполняет администратор после проверки принадлежности профиля. Восстановление пароля через почту само по себе не отключает TOTP.

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

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

Подписка

Поддержаны периоды 30, 90 и 365 суток, одноразовые подарочные коды и бессрочный доступ. После окончания срока даются трое суток на продление, затем юзербот останавливается. Данные сохраняются 30 суток после остановки.

Есть локальная проверка продления и подключение Stripe с автоматическим продлением, проверкой подписи и учётом оплаченных счетов. Тестовый и рабочий режимы выбираются явно; данные Stripe для них разделены. Тарифы приведены в PRODUCT.md, настройка Stripe в PAYMENTS.md.

Изоляция

Каждый экземпляр модуля работает в своей среде Podman с gVisor/runsc. Сеть закрыта, корень доступен только для чтения. Пакет копируется во временный рабочий каталог, исходная версия остаётся неизменной.

Модули, сборки и терминал делят пределы процессора, памяти и процессов юзербота. Экземпляру можно задать меньшие пределы. Данные учитываются по квоте, при --volumes база находится на ограниченном ext4-томе.

Сессии, токены ботов, ключи, чужие базы и сокеты управления не подключаются к среде. Включённый исправный экземпляр запускается после перезапуска ядра. Необработанная ошибка отключает его до ручного включения. Остановка завершает среду вместе с дочерними процессами.

Права

Ядро проверяет права человека на вызов и права модуля на действие. Для модуля учитываются заявленные разрешения, согласие пользователя и ограничения экземпляра. Без разрешений действия недоступны.

Чаты, пользователи, сайты и зависимости проверяются при обращении. Вызов другого модуля сохраняет ограничения цепочки. Событие, овнерку и право запуска терминала нельзя получить подменой поля запроса.

telegram.full и bot.full дают низкоуровневые методы с отдельным согласием. Сессия и токен не передаются. Если адресатов общего запроса нельзя проверить при действующих ограничениях, ядро отклоняет запрос.

Изменение прав действует для работающей среды, соединений и задач. Уже принятое внешней службой действие может завершиться. Модуль с принятыми правами может выполнять самостоятельные задачи, поэтому при установке нужно учитывать доверие к автору.

Telegram и боты

Для подключения нужны номер, собственные api_id и api_hash, код и при необходимости пароль Telegram. Пароль Telegram не сохраняется. Смена подключения сохраняет профиль, модули, настройки и данные. Ожидающие операции прежнего подключения не отправляются с нового.

Клиент модуля отправляет и получает сообщения, загружает вложения в своё хранилище, отправляет файлы, меняет доступные поля профиля и фотографию. Низкоуровневые запросы проходят проверку операций Telethon. Действия авторизации и неизвестные методы закрыты.

У аккаунта общая очередь запросов. Обрабатываются FloodWait, потеря связи и авторизации. Отправка с неизвестным результатом автоматически не повторяется.

Сервисный бот BridgeSentinel выполняет служебные задачи и доставляет уведомления. Для команд, кнопок и форм модулей используется личный бот. Его можно подключить токеном или запросить создание через Managed Bots. Без личного бота продолжают работать функции, которым он не нужен.

Модули

Пакет описывает команды, обработчики сообщений, кнопки, действия сайта, функции, события, расписание и входящие запросы. Ядро сверяет это описание с обработчиками при запуске. Конфликт команд устраняется выбором другого алиаса. exec и load зарезервированы.

У одного модуля может быть несколько экземпляров с разными именами экземпляров. Данные, права, настройки и выбор зависимости у них отдельные.

Конфигуратор поддерживает строки, секреты, числа, переключатели, выбор, списки, чаты, пользователей, файлы и JSON. Страницы собираются из текста, показателей, таблиц, кнопок, форм и задач. Для надписей можно задать русский и английский. Произвольные HTML и JavaScript не исполняются.

Вебшоп

Публикация принимает ZIP, HTTPS-ссылку или GitHub. При первой публикации создаётся постоянный ID. Исправления выпускаются новой версией, ссылка GitHub закрепляется за коммитом. Архив проверяется до распаковки, код пакета не импортируется в ядро.

Python-зависимости устанавливаются из PyPI или приложенных wheels. Для pip внутри контейнера запускается HTTP-сервер на Unix-сокете, который передаёт запросы через build/pypi/open и build/pypi/read. user/pip_runner.py направляет соединения pip в этот сокет, включая установку зависимостей сборки исходного пакета. Образ сборки закреплён по SHA256; совместимость с его версией pip проверяется при изменениях образа. Ядро скачивает данные только с официальных адресов PyPI по HTTPS, ограничивает размер и удаляет временные файлы после сборки. Сам контейнер остаётся без прямой сети. Скрипт сборки выполняется в изоляции. Для компиляции используется отдельный образ. Результат проверяется и учитывается в квоте.

Есть версии, сравнение открытых исходников, архивация, оценки, отзывы, установки, жалобы и тестеры. Галочка относится к конкретной проверенной версии. Непубличная публикация доступна автору и добавленным тестерам.

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

Сеть и файлы

Внешние запросы проходят через ядро. Доступны HTTPS и WSS на порту 443. Проверяются имя сайта, все адреса DNS, IP подключения и TLS. Частные и служебные адреса запрещены. Перенаправление возвращается модулю, следующий адрес проходит новую проверку.

У каждого экземпляра отдельные cookies и настройки HTTP/SOCKS-прокси.

Постоянные файлы загружаются порциями с резервированием размера. При завершении вычисляется SHA256 и сравнивается с ожидаемой суммой, если она была указана. Есть срок хранения, список с курсором, скачивание и удаление. Файловое поле конфигуратора открывает выбранный файл без полного доступа к чужому разделу юзербота.

Расписание и обмен

Расписание хранится в базе юзербота. Есть разовые и повторные задачи, ограниченные повторы после ошибки, отмена и удаление. Задача сохраняет права исходного вызова. После сбоя внешнее действие могло завершиться без сохранённого ответа, поэтому повтор требует учитывать это в обработчике.

Обмен передаёт JSON, текст, файлы и события по договору. Он закрепляет юзерботов, конкретные установки и ресурс. Адресат одобряет каждое направление отдельно. Наличие ресурса проверяется после согласия, недоступный участник сразу возвращает отказ.

События сохраняются у получателя с последовательными номерами. Их можно получать по курсору и удалять после обработки. Файлы копируются порциями с резервированием места. Метаданные ожидающего договора учитываются у инициатора, после одобрения размер делится поровну. Содержимое учитывается у того, кто его хранит.

Есть постоянный, разовый и групповой режимы. Группа объединяет отдельно одобренные направления. Отзыв запрещает новые передачи, уже принятая может завершиться. Смена Telegram сохраняет договор, переустановка экземпляра требует нового согласия.

Терминал и поддержка

Овнеры получают Bash через HTTP API и !exec. Поддержаны интерактивный ввод, долгие процессы, остановка, история и постоянные рабочие файлы. Через terminal_client доступны операции владельца, фактическая сессия остаётся в ядре. Доверка и модули не могут запускать терминал.

Пользователь выдаёт доступ поддержки через HTTP API. Доступ относится к одному юзерботу и прекращается после отзыва или завершения ремонта. Среда ремонта отделена от обычного терминала. Отдельной истории действий поддержки нет.

Журнал и копии

Журнал поддерживает уровни, группы, поиск, фильтры, получение новых записей и очистку. Внешний интерфейс может сохранить полученные записи в файл. Срок хранения задаётся для юзербота или экземпляра. Уведомления доступны через API и по выбору доставляются личным ботом, при его отсутствии сервисным. После включения доставки приходят только новые события; старые остаются на сайте. Важные системные уведомления отключить нельзя.

При 90% хранилища появляется предупреждение. При 100% увеличение данных запрещается. Освобождение места выбирает пользователь.

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

Восстановление доступно для остановленного юзербота. Архив проверяется, файлы готовятся отдельно, переключение фиксируется сохранённой отметкой. После сбоя ядро завершает восстановление по этой отметке. Экземпляры остаются остановленными.

Операторская копия создаётся после остановки служб и восстанавливается в новый каталог. Она не содержит Telegram-сессий и старых входов. Ключ хранится отдельно. Подробности в STORAGE.md.

Ограничения

Cluster работает на одном узле. Распределённого владения базами и межсерверного транспорта нет. Продажи модулей и исполнения произвольных веб-страниц нет.

Совместимость программы с gVisor зависит от её системных вызовов и библиотек. Для развёртывания нужны собственные параметры почты, Telegram и ботов. Настройка и проверка подключений описаны в DEPLOYMENT.md.