Платёж, подписка
и реальное состояние 3x-ui. Payment, subscription
and the actual state of 3x-ui.

Исходная задача и ограничения

Пользователю нужна была понятная цепочка: выбрать услугу в Telegram, пополнить баланс удобным способом и получить одну ссылку или QR-код. Для составной услуги за этим простым интерфейсом стоят несколько клиентов на разных 3x-ui-направлениях с одинаковыми сроками и лимитами.

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

Нагрузка здесь — несколько действий в минуту, поэтому развёртывание осталось компактным. При этом повторное уведомление не должно удваивать баланс, недоступность одной 3x-ui — оставлять половину составной подписки, а ручное изменение панели — проходить незамеченным.

Почему я реализовал свой обработчик платежей

YooMoney остаётся платёжным провайдером. Собственный компонент отвечает за прикладную часть: создаёт непрозрачную метку без Telegram ID, принимает уведомление, проверяет подпись HMAC-SHA256, тип операции, валюту и идентификатор, а затем связывает подтверждение с ожидаемой операцией пользователя.

Обычно платёж подтверждается входящим уведомлением. Если оно не дошло, пользователь может запустить проверку кнопкой; кроме того, фоновая задача раз в минуту сверяет незавершённые платежи через operation-history. Все три пути вызывают один обработчик и записывают источник подтверждения. Для входящих уведомлений ведётся отдельный журнал: адрес источника, метка, операция, результат проверки подписи и ошибка применения.

В уведомлении может прийти сумма уже после комиссии. Для карточного пополнения обработчик определяет канал по типу события и, когда возможно, по operation-details, а затем восстанавливает исходную сумму. Запланированная сумма не подменяет фактическую: в одной из ранних версий я исправил ошибку, при которой баланс мог пополняться минимум на ожидаемое значение.

func creditedAmount(kind string, netMinor int64) int64 {
    switch kind {
    case "card":
        return int64(math.Round(float64(netMinor) / 0.97))
    case "wallet":
        return netMinor
    default:
        return netMinor
    }
}

Платёж ещё не означает готовую подписку

Подтверждение платежа атомарно меняет транзакцию и баланс в PostgreSQL. Здесь же закрывается ожидаемое пополнение, фиксируется промокод и рассчитывается реферальное начисление. Создание клиентов 3x-ui начинается только после фиксации денег и желаемого состояния.

Повторная обработка блокируется на нескольких уровнях. Пара «провайдер — идентификатор операции» и внутренний ключ идемпотентности уникальны. Строка транзакции блокируется через FOR UPDATE; уже завершённый платёж возвращает already_processed. Обновление Telegram получает короткую аренду: после ошибки маркер освобождается для новой попытки, а завершённая обработка больше не запускается.

payment := lockByLabelOrOperationID(tx, label, operationID)
if payment.Status == "succeeded" {
    return AlreadyProcessed
}

markSucceeded(tx, payment.ID, operationID, actualAmount, source)
creditBalance(tx, payment.UserID, actualAmount)
completePendingOperation(tx, payment.UserID, label)

return tx.Commit()

Желаемое состояние вместо длинной транзакции

В первой реализации вызов 3x-ui выполнялся внутри транзакции БД. Сетевой запрос удерживал блокировки, а успешное изменение во внешней панели уже нельзя было отменить откатом PostgreSQL. При обрыве между ответом API и COMMIT панель и база расходились.

Теперь транзакция только записывает желаемые параметры узла: входящее правило, адрес и идентификатор клиента, срок, лимиты и поколение операции. После COMMIT обработчик получает задачу с пятиминутной арендой, обращается к нужному адаптеру 3x-ui и завершает её лишь тогда, когда маркер аренды и поколение всё ещё совпадают. Если желаемое состояние успело измениться, старый результат не может затереть новое.

UPDATE subscription_nodes
SET provisioning_status = 'processing',
    provisioning_attempts = provisioning_attempts + 1,
    provisioning_lease_until = NOW() + INTERVAL '5 minutes',
    provisioning_claim_token = $claim
WHERE id = $node
  AND provisioning_status <> 'done'
  AND (provisioning_lease_until IS NULL
       OR provisioning_lease_until <= NOW())
RETURNING provisioning_generation;

Почему я выбрал Go, PostgreSQL и два процесса

Go я выбрал из-за небольшого исполняемого файла, явных таймаутов и общего кода для HTTP, Telegram и адаптеров 3x-ui. PostgreSQL одновременно служит журналом денег, источником желаемого состояния и надёжной очередью небольшой нагрузки: частичные уникальные индексы, блокировки строк, аренды и поколения здесь полезнее отдельного брокера.

Один образ запускается в двух ролях. Процесс bot отвечает за Telegram, платёжные маршруты, выдачу агрегированных подписок и быстрые попытки применения. Процесс worker сверяет сроки, автопродление, незавершённую выдачу доступа и фактическое состояние 3x-ui. PostgreSQL остаётся общей точкой согласования, а наружу через Nginx публикуется только HTTP-контур бота.

Redis и отдельный брокер здесь не понадобились: при текущей нагрузке PostgreSQL закрывает очередь с меньшим числом служб в эксплуатации. Если появятся несколько реплик, тяжёлые очереди или жёсткое время доставки, это решение придётся пересмотреть.

Контроль нескольких 3x-ui

В текущей конфигурации код знает четыре логических направления 3x-ui. У каждого свой адаптер и входящее правило, а составная услуга разворачивает несколько узлов с общим сроком. Пользователь при этом получает одну токенизированную подписку с ограниченным сроком действия, а не набор внутренних адресов панели.

API 3x-ui менялся между версиями: отличались методы добавления и обновления клиента, формат отдельных полей и параметры VLESS. Адаптер сначала читает входящее правило, находит клиента по идентификатору или адресу, пробует изменить его и только при подтверждённом отсутствии создаёт нового. Параметры ссылки строятся из фактической конфигурации, включая TLS, REALITY, WebSocket, gRPC или XHTTP.

Сбои и компромиссы из истории проекта

1. 01.04
   Перестал доверять уведомлению только по факту доставки.

   Добавил секрет уведомлений Telegram, устранение повторов обновлений и более безопасный порядок привязки клиентов; позже дополнил YooMoney отдельной HMAC-проверкой и тестом.

2. 21.04
   Перевёл баланс на фактическую сумму платежа.

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

3. 26.05
   Зафиксировал версию 3x-ui как часть контракта.

   Поддержка v3.1 потребовала новых вариантов запросов. Различия оставил внутри адаптера, а не размазывал по прикладной логике.

4. 15.07
   Вынес вызовы 3x-ui из транзакций PostgreSQL.

   Добавил состояния выдачи, аренду, поколение операции и повторную обработку; следующим изменением — компенсацию расхождений между БД и панелью.

5. 18.07
   Убрал зависимость запуска от порядка контейнеров.

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

Что происходит при отказе

• не пришло уведомление — платёж может подтвердить пользовательская кнопка или фоновая сверка;
• уведомление повторилось — уникальные ключи и блокировка строки возвращают уже готовый результат без второго начисления;
• 3x-ui недоступен — деньги и желаемое состояние остаются в БД, задача получает задержку и повтор;
• клиента удалили или изменили вручную — фоновый процесс сравнивает активные неистёкшие подписки с панелью и ставит компенсацию;
• во время запроса изменился срок или лимит — старое поколение не может завершить новую задачу;
• ошибка становится повторяющейся — администратор получает уведомления на первой, третьей и затем каждой десятой попытке.

Измеримый результат

Коммерческие показатели и пользовательские данные закрыты. По текущей реализации можно назвать технические величины:

• 4логических направления 3x-ui в одном контуре управления
• 3пути подтверждения платежа сходятся в одну идемпотентную операцию
• 2процесса Go разделяют быстрый интерфейс и фоновое восстановление
• 1агрегированная ссылка и QR скрывают устройство составной подписки

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