Billing - Lago (Биллинг и подписки)¶

Общее описание¶

Система биллинга на базе Lago — self-hosted платформы для usage-based биллинга. Обеспечивает управление подписками, тарифными планами, учётом использования, инвойсами и кошельками для всех тенантов AACSearch.

Расположение: /root/billing Сервер: 185.130.225.35 API домен: billing-api.aacsearch.com Frontend домен: billing.aacsearch.com Локальные порты: API — 3000, Frontend — 8080

Структура каталога¶

/root/billing/
├── api/                          # Rails API (бэкенд Lago)
│   ├── app/
│   │   ├── models/               # ActiveRecord модели (50+)
│   │   ├── services/             # Бизнес-логика (Service Layer)
│   │   ├── graphql/              # GraphQL схема и резолверы
│   │   ├── jobs/                 # Sidekiq фоновые задачи
│   │   └── controllers/         # REST контроллеры
│   ├── config/
│   │   ├── database.yml          # Конфигурация PostgreSQL
│   │   ├── sidekiq/              # Конфигурации очередей Sidekiq
│   │   ├── permissions.yml       # Разрешения ролей
│   │   ├── storage.yml           # Конфигурация хранилища файлов
│   │   └── initializers/
│   │       └── zz_license_premium.rb  # Патч активации Premium
│   ├── db/
│   │   ├── migrate/              # Миграции PostgreSQL (1000+)
│   │   ├── views/                # SQL-представления
│   │   ├── clickhouse_migrate/   # Миграции ClickHouse
│   │   └── seeds/                # Seed-данные
│   └── scripts/
│       ├── start.api.sh          # Запуск Rails API
│       ├── start.worker.sh       # Запуск Sidekiq worker
│       ├── start.clock.sh        # Запуск планировщика
│       ├── migrate.sh            # Миграции БД
│       └── generate.rsa.sh      # Генерация RSA ключей
├── front/                        # React/TypeScript frontend
├── events-processor/             # Kafka обработка событий
├── tochka-overlay/               # Интеграция с банком Точка
├── deploy/                       # Конфигурации деплоя
├── traefik/                      # Конфигурация reverse proxy
├── docker-compose.yml            # Основной Docker Compose (production)
├── docker-compose.dev.yml        # Разработка (с Traefik, ClickHouse и др.)
├── docker-compose.override.yml   # Переопределения (Premium + mock license)
├── .env                          # Переменные окружения
├── dc.sh                         # Скрипт-обёртка docker-compose
└── README_PREMIUM.md             # Документация Premium-фич

Docker Compose стек¶

Основные сервисы (docker-compose.yml)¶

Сервис	Образ	Порт	Назначение
`lago-db`	`postgres:15-alpine`	5432	База данных
`lago-redis`	`redis:7-alpine`	6379	Очередь задач, кеш
`lago-api`	`getlago/api:v1.41.2`	3000	REST + GraphQL API
`lago-front`	`getlago/front:v1.41.0`	80 (→ 8080)	React фронтенд
`lago-worker`	`getlago/api:v1.41.2`	—	Sidekiq worker
`lago-clock`	`getlago/api:v1.41.2`	—	Планировщик задач
`lago-gotenberg`	gotenberg	3000	Генерация PDF

Дополнительные сервисы (docker-compose.dev.yml)¶

Сервис	Назначение
Traefik v3	Reverse proxy с Let's Encrypt
Redpanda	Kafka-совместимая очередь событий
ClickHouse	Аналитическая OLAP база
Kafka Connect	Data pipeline
Redpanda Console	UI управления Kafka
MailHog	Тестовый почтовый сервер (порт 8025)
PgHero	Мониторинг PostgreSQL

Переопределения (docker-compose.override.yml)¶

Mock License Service (порт 3001) — эмулирует сервер лицензий
Premium-патч через initializer zz_license_premium.rb
Интеграция Точка — оверлей файлов через Docker volumes
Все 26 Premium-фич активированы

Переменные окружения (.env)¶

Безопасность и шифрование¶

Переменная	Назначение
`SECRET_KEY_BASE`	Ключ Rails для подписи сессий/cookies
`LAGO_RSA_PRIVATE_KEY`	RSA ключ для JWT подписи
`LAGO_ENCRYPTION_PRIMARY_KEY`	Основной ключ шифрования данных
`LAGO_ENCRYPTION_DETERMINISTIC_KEY`	Детерминистический ключ шифрования
`LAGO_ENCRYPTION_KEY_DERIVATION_SALT`	Соль для деривации ключей

База данных¶

POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DB=lago
POSTGRES_USER=lago
POSTGRES_PASSWORD=changeme
DATABASE_URL=postgresql://lago:changeme@db:5432/lago?search_path=public

Redis¶

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_URL=redis://redis:6379
LAGO_REDIS_CACHE_HOST=redis
LAGO_REDIS_CACHE_PORT=6379

URL-адреса приложения¶

LAGO_API_URL=https://billing-api.aacsearch.com
LAGO_FRONT_URL=https://billing.aacsearch.com
LAGO_PDF_URL=http://pdf:3000

Лицензия Premium¶

LAGO_LICENSE=premium-activated-via-patch
LAGO_LICENSE_URL=http://mock-license:3000

SMTP (Resend)¶

LAGO_FROM_EMAIL=billing@aacsearch.com
LAGO_SMTP_ADDRESS=smtp.resend.com
LAGO_SMTP_PORT=2587
LAGO_SMTP_USERNAME=resend
LAGO_SMTP_PASSWORD=re_MdhhhN82_DPJSBhFUnhrKNLXeN2Lvq2Bk

AI-интеграция¶

MISTRAL_API_KEY=we2dZfIFyViaH0dsZiNGId9eDKSFpMzT
MISTRAL_AGENT_ID=ag_019c4240a9a772e08ecd598ea57c8d64

Флаги¶

Флаг	Значение	Описание
`LAGO_DISABLE_SIGNUP`	false	Разрешена регистрация
`LAGO_DISABLE_PDF_GENERATION`	false	PDF-генерация включена
`LAGO_DISABLE_SEGMENT`	true	Аналитика отключена
`LAGO_SIDEKIQ_WEB`	true	Sidekiq UI включён

Архитектура базы данных¶

Многобазовая конфигурация¶

БД	Назначение
Primary (PostgreSQL)	Основная БД приложения
Events (PostgreSQL)	Отдельная БД для обработки событий
ClickHouse	Аналитический Data Warehouse (опционально)

Connection Pool¶

Среда	Соединений
Development / Test	5
Production / Staging	10

Sidekiq — Очереди фоновых задач¶

Очереди¶

Очередь	Конкурентность	Назначение
`high_priority`	10	Срочные задачи
`default`	10	Общие задачи
`mailers`	10	Отправка email
`clock`	10	Запланированные задачи
`providers`	10	Обработка платежей
`webhook`	10	Отправка вебхуков
`webhook_worker`	10	Выделенный обработчик вебхуков
`invoices`	10	Генерация инвойсов
`integrations`	10	Сторонние интеграции
`billing`	10 (prod: 5)	Биллинговые операции
`low_priority`	10	Фоновые задачи
`long_running`	10	Долгие задачи

Скрипты запуска воркеров¶

Скрипт	Назначение
`start.worker.sh`	Общий worker
`start.events.worker.sh`	Обработка событий
`start.pdfs.worker.sh`	Генерация PDF
`start.billing.worker.sh`	Биллинговые задачи
`start.webhook.worker.sh`	Вебхуки
`start.clock.worker.sh`	Планировщик
`start.analytics.worker.sh`	Аналитика
`start.ai_agent.worker.sh`	AI-агент

Тарифные планы AACSearch¶

Настроенные планы¶

План	Код	Описание
Starter	`starter_v1`	Базовый план для начинающих
Professional	`professional_v1`	Расширенный для бизнеса
Enterprise	`enterprise_v1`	Корпоративный без ограничений
Pay-As-You-Go	`payg_v1`	Оплата по факту использования

Биллинговые метрики (12 шт.)¶

Метрика	Код	Тип агрегации
Поисковые запросы	`search_request`	COUNT
Векторный поиск	`vector_search`	COUNT
RAG запросы	`rag_query`	COUNT
Проиндексированные документы	`documents_indexed`	SUM
Хранимые документы	`documents_stored`	MAX
API вызовы	`api_call`	COUNT
Созданные синонимы	`synonym_set_created`	COUNT
Правила курирования	`curation_rule_created`	COUNT
Гео-запросы	`geo_query`	COUNT
Мульти-поиск	`multi_search_query`	COUNT
Семантический поиск	`semantic_query`	COUNT
Поиск по изображениям	`image_query`	COUNT

Фичи (Entitlements, 21 шт.)¶

synonyms, curations, stopwords, presets, vector_search, rag,
multi_search, analytics_advanced, bulk_import, export, stemming,
nl_search, geo_search, faceting, grouping, semantic_search,
image_search, voice_search, joins, scoped_api_keys, conversations

Вебхуки¶

Эндпоинт для приёма¶

API-шлюз принимает вебхуки Lago на https://api.aacsearch.com/webhooks/lago

Типы поддерживаемых событий¶

Категория	События
Клиенты	`customer.created`, `customer.updated`, `customer.deleted`
Подписки	`subscription.created`, `subscription.updated`, `subscription.terminated`
Инвойсы	`invoice.created`, `invoice.updated`, `invoice.finalized`, `invoice.voided`
Кредитные ноты	`credit_note.created`, `credit_note.updated`, `credit_note.voided`
Купоны	`coupon.created`, `coupon.updated`
Add-ons	`add_on.created`, `add_on.updated`
Планы	`plan.created`, `plan.updated`
Кошельки	`wallet.depleted`, `wallet.depleted_ongoing_balance`
И другие	20+ типов

HMAC верификация¶

Ключ: d32fc8e8-fc04-48c0-a70d-f3db318f69de
Алгоритм: HMAC-SHA256
Кодировка: base64 (НЕ hex!)
Заголовок: X-Lago-Signature

Premium-фичи (26 шт. — все активированы)¶

Активация¶

Метод: Патч через Ruby initializer api/config/initializers/zz_license_premium.rb + Mock License Service на порту 3001.

Список Premium-фич по категориям¶

Биллинг и платежи (6)¶

Фича	Описание
Progressive Billing	Прогрессивное выставление счетов
Auto Dunning	Автоматическое взыскание просроченных платежей
Manual Payments	Ручные платежи
Zero Amount Fees	Нулевые комиссии
Payment Authorization	Авторизация платежей
Issue Receipts	Выдача квитанций

Аналитика (5)¶

Фича	Описание
Revenue Analytics	Панель аналитики доходов
Forecasted Usage	Прогноз использования
Projected Usage	Проекция использования
Lifetime Usage	Учёт использования за всё время
Analytics Dashboards	Аналитические дашборды

Интеграции (6)¶

Фича	Описание
NetSuite	ERP-интеграция
Okta SSO	Единый вход через Okta
Avalara	Налоговая интеграция
Xero	Бухгалтерская интеграция
HubSpot	CRM-интеграция
Salesforce	CRM-интеграция

Кастомизация (3)¶

Фича	Описание
Remove Branding	Удаление брендинга Lago
Custom Roles	Настраиваемые роли
Custom Email Sender	Кастомный отправитель писем

Multi-Entity (2)¶

Фича	Описание
Multi-Entity Pro	Мульти-юрлицо (Pro)
Multi-Entity Enterprise	Мульти-юрлицо (Enterprise)

Прочие (4)¶

Фича	Описание
API Permissions	Управление API-правами
Revenue Share	Распределение доходов
Events Targeting Wallets	События для кошельков
Preview	Предпросмотр

Ключевые модели данных¶

Биллинг¶

Модель	Описание
`Plan`	Тарифные планы
`BillableMetric`	Метрики для учёта использования
`Charge`	Стоимости/комиссии в планах
`Subscription`	Подписки клиентов
`Invoice`	Инвойсы
`Fee`	Отдельные позиции в инвойсах

Клиенты¶

Модель	Описание
`Customer`	Конечные клиенты (тенанты)
`BillingEntity`	Юридические лица для выставления счетов
`Wallet`	Предоплаченные кошельки

Промоции¶

Модель	Описание
`Coupon`	Скидочные купоны
`AddOn`	Разовые доплаты
`CreditNote`	Кредитные ноты
`Adjustment`	Корректировки

События¶

Модель	Описание
`Event`	Сырые события использования
`EnrichedEvent`	Обработанные события
`DailyUsage`	Агрегированное использование

Хранилище файлов¶

Текущая конфигурация: Локальное дисковое хранилище (по умолчанию)

Вариант	Статус
Local Disk	Активен
AWS S3	Настроен, отключён
Google Cloud Storage	Настроен, отключён

Варианты деплоя¶

1. Local (docker-compose.local.yml)¶

Один compose-файл, все сервисы вместе
Без Traefik/SSL
Для локальной разработки

2. Light (docker-compose.light.yml)¶

Traefik с Let's Encrypt
Один домен
Минимальный footprint

3. Production (docker-compose.production.yml)¶

Traefik + SSL
Portainer для управления
Несколько экземпляров воркеров
Профили: all, all-no-pg, all-no-redis, all-no-keys

4. Coolify (docker-compose.coolify.yml)¶

Деплой через Coolify платформу

Скрипт dc.sh¶

Обёртка для docker-compose, использующая production + override конфигурации:

# Внутри dc.sh:
docker compose -f docker-compose.prod.yml -f docker-compose.override.yml "$@"

# Использование:
./dc.sh up -d
./dc.sh logs -f lago-api
./dc.sh restart api-worker    # Имя сервиса в compose = api-worker

Имена сервисов: api, api-worker, api-clock (контейнеры: lago-api, lago-worker, lago-clock)

Интеграция с банком Точка — Monkey-patching¶

Кастомный платёжный провайдер Точка подключается через Docker volume оверлеи в docker-compose.override.yml. Три элемента, требующих monkey-patch:

PAYMENT_PROVIDERS constant — добавление :tochka в массив провайдеров
@delimiter в InclusionValidator — закешированная копия старого массива
@options hash — заморожен (frozen), требует dup перед модификацией

Используется TOCHKA_TYPE_REF константа для доступа к GraphQL singleton scope.

Текущий провайдер: код tochka_main, sandbox_mode=true

Файлы оверлея¶

/root/billing/tochka-overlay/
├── models/          # TochkaProvider, TochkaCustomer
├── services/        # Обработка платежей
├── graphql/         # Мутации и типы
├── controllers/     # Webhooks контроллер
└── config/          # Routes, initializers

Критические замечания¶

LAGO_API_URL: Для SDK должен заканчиваться на /api/v1 — SDK конкатенирует пути напрямую
Lago SDK выбрасывает исключения: На non-200 ответах SDK делает throw data — нельзя деструктурировать {data, error} в catch-блоке
Timestamps: Lago принимает Unix epoch integer (НЕ ISO 8601): Math.floor(date.getTime() / 1000)
HMAC подпись вебхуков: base64-кодировка, НЕ hex
Lago API Key: Получается из БД: docker exec -i lago-db psql -U lago -d lago -t -c "SELECT value FROM api_keys LIMIT 1"
HMAC Key: d32fc8e8-fc04-48c0-a70d-f3db318f69de (из SELECT hmac_key FROM organizations)
API v1 customer serialization: payment_provider внутри billing_configuration, НЕ на верхнем уровне
Tochka monkey-patch: 3 вещи требуют патча (PAYMENT_PROVIDERS, @delimiter, @options) — см. секцию выше