Всем привет!
Хочу рассказать о своем проекте универсального биллинга SaviorBill (или, скорее, уже ближе к движку магазина), почему я начал его делать и для кого.

Как я докатился до жизни такой

Изначально, при желании продавать некоторые цифровые товары и доступы, я решил использовать SHM. Проект в целом хороший, но мне он был неудобен. Хотя сейчас вроде как исправлены те вещи которые мне не понравились, но я решил написать свое, уж не умею я в перле ничего и под себя дописать быстро. Взял свой родной стек, который я знаю лучше всего. Но мой нелюбимый перфекционизм заставил все перевернуть с ног наголову и добавить Lua, мультивалютность и многие другие вещи которые я считал «красивыми».

Проект SaviorBill построен по принципу микросервисов и API First, хотя и он ближе к монолиту. Для работы с услугами (за исключением чистых текстовых цифровых ключей), интеграция с эквайрингами, добавление OAuth/OIDC провайдеров, триггеры и для работы с почтой (кроме чистого SMTP) необходимо написать свой скрипт на языке Lua который исполняется в изолированном контейнере.

Для кого этот проект?

Для начала считаю стоит мне рассказать что вообще можно сделать в SaviorBill и кому подходит мой проект.

Пример создания услуги в админ-панели SaviorBill

Пример создания услуги в админ‑панели SaviorBill

SaviorBill хорошо подходит для:
 — Цифровых ключей.
 — VPS/VDS хостинги с конфигуратором встроенным.
 — SaaS и API‑доступы подписки на веб‑сервисы, ботов
 — Пополнения балансов сервисов. (например Steam или OpenRouter, тут все зависит только от ваших хотелок)
 — Другие услуги с подписками/конфигуратором/произвольной или фиксированной суммой.

Компоненты системы и стек

— BillingCore: API и обработка и манипулирование задачами. (Python 3.12 + FastAPI)
— LuaWorker: исполнение пользовательских Lua скриптов, чистый LuaJIT
— MediaWorker: загрузка и раздача медиа с возможностью настроить конвертацию через ffmpeg и поддержкой S3 хранилища.
— sbuiSDK: библиотека для преобразовывания описанных в манифесте lua скриптов в UI формы.
и зависимости:
— PostgreSQL — базы данных и схемы.
— Valkey — кэш и очереди задач (задачи хранятся в БД, сюда попадают только те что должны вот‑вот начать выполняться)

Системные требования

Системные требования в целом небольшие, но опять‑же, на деле все зависит от активности и количества аудитории.

Минимальные

Рекомендуется

— 1 cpu
— 1GB RAM
— 30GB диск для базы, изображений и скриптов.

— 2 cpu
— 4–8GB RAM
— 50+ GB диск

*примечание: работа с видео может изрядно нагружать систему и выполняться долго.

*Идеально здесь и s3 для медиа и статики некоторой, и вынос на несколько нод.

При чем здесь LUA и как он используется?

Lua по своей сути интегрируемый язык, здесь же он используется по прямому назначению — для интеграций. Если быть конкретнее: для создания и работы с услугами, обработки платежей из любых эквайрингов/платежек, добавления OAuth/OIDC, создания триггеров по действиям и многих других вещей.

Все скрипты выполняются в LuaWorker, а billing передает ему задачи через Valkey Streams.

Lua и плагины — не одно и то же

Lua предназначен прежде всего для внешних интеграций и бизнес действий: создать пользователя во внешней панели, проверить платёж или отправить webhook.

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

Как скрипт понимает что ему нужно делать?

Каждый Lua‑скрипт получает объект ctx — контекст текущей задачи.

Структура контекста зависит от типа скрипта: скрипт услуг не получает тот же набор полей, что платёжный или OAuth‑скрипт. Сам скрипт должен работать только с полями своего контракта.

  • service (Скрипты услуг) — имеют действия create, renew, stop, delete, freeze;

  • payment (Эквайринги) — получают create, callback, check, refund;

  • auth (Авторизация) — получают startи callback;

  • email (Для интеграции email сервисов, но не обязателен, есть встроенный smtp) — получают send;

  • FX‑скрипт (нет отдельного класса, выбирается как generic) — получает rates;

  • trigger‑скрипты вместо ctx.action получают ctx.event.

Примеры того, что и как могут получать услуги в контекст.

Скрипт услуги:

{
  action = "create",

  user = {
    id = 42,
    login = "UNVI",
    service = {
      id = 1001,
      status = "pending",
      params = {}
    }
  },

  service = {
    id = 25,
    slug = "vpn-license",
    settings = {}
  },

  order = {
    amount = "15.00",
    currency = "RUB",
    tier = nil,
    components = nil,
    form = {}
  }
}

Скрипт обработки платежей:

{
  action = "create",

  user = {
    id = 42,
    login = "UNVI",
    email = "unvi@example.com"
  },

  payment = {
    id = 500,
    amount = "950.00",
    currency = "RUB",
    status = "pending",
    target = "balance",

    provider_data = {
      slug = "yookassa",
      secrets = {},
      extra = {}
    }
  }
}

При обработке вебхука в action = «callback» скрипт дополнительно получает ctx.request с HTTP‑методом, IP‑адресом, заголовками, query‑параметрами и телом запроса. При этом реальный платёж ещё не найден: ядро передаёт временную заглушку, а скрипт должен вернуть payment_id или external_id, по которым SaviorBill найдёт настоящий платёж.

Триггер:

{
  event = "payment.paid",

  config = {
    webhook_url = "https://example.com/hook"
  },

  data = {
    user = {
      id = 42,
      login = "alice"
    },

    payment = {
      id = 500,
      amount = "950.00",
      currency = "RUB",
      status = "paid"
    }
  }
}

Так, один и тот же Lua‑механизм используется для разных задач, но структура ctx зависит от типа скрипта. Скрипту не нужно знать устройство всей платформы: он получает только контракт своего действия и возвращает результат в конкретном формате.

Например, сервисный скрипт может вернуть:

{
  public = {
    subscription = "https://example.com/sub/..."
  },

  private = {
    username = "alice_1234"
  },

  state = "active",
  expires_at = 1760000000
}

public содержит данные, которые можно показать пользователю, private — внутренние данные для ядра, а state и expires_at позволяют billing управлять жизненным циклом услуги.

На старт, внимание... Как запустить?

Запустить SaviorBill довольно просто. Для быстрого развертывания для небольшого магазина достаточно установить используя скрипт деплоя из репозитория, он скачает композ файл, задаст несколько вопросов, сгенерирует конфигурацию и запустит сервис:

mkdir ~/saviorbill && cd ~/saviorbill
bash <(curl -fsSL https://raw.githubusercontent.com/UNVISLATE/SaviorBill/master/deploy/setup.sh)

Больше подробностей по деплою здесь.

Что нужно для создания услуги?

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

Если коротко, то для создания услуги которую уже можно продать, необходимо:

  1. Загрузить lua скрипт для платежной системы или создать новый

  2. Создать платежного провайдера и привязать его к скрипту.

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

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

Заключение

SaviorBill находится в активной разработке. Множество идей ещё предстоит реализовать. Делитесь своими мнениями, буду рад узнать ваше мнение о проекте.

Некоторые скрины
Страница профиля пользователя

Страница профиля пользователя

Страница просмотра и управления платежными провайдерами/эквайрингами

Страница просмотра и управления платежными провайдерами/эквайрингами

Управление ролями и их список

Управление ролями и их список

Редактирование прав роли

Редактирование прав роли

Наблюдаемость для SaviorBill по инстансам и нагрузке в реальном времени

Наблюдаемость для SaviorBill по инстансам и нагрузке в реальном времени

Полезные ссылки

Репозиторий проекта: https://github.com/UNVISLATE/SaviorBill
Репозиторий клиентского ЛК: https://github.com/UNVISLATE/SBPersonalAccountClient

Благодарен вам что дочитали, надеюсь мы еще увидимся:)