> ## Documentation Index
> Fetch the complete documentation index at: https://omniflow-vpn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Политика расширения

> Какие поверхности публичны и на них можно опираться, какие внутренние и будут меняться, что можно расширить без правки кода и что расширять намеренно нельзя

Omniflow расширяется двумя способами, и только двумя. Конфигурация дотягивается
до точек входа, которых сопровождающие никогда не увидят: сервер моделей на
вашем железе, поставщик идентичности, сервер MCP. Всё остальное — вклад в этот
репозиторий, отрецензированный и вкомпилированный. Плагинного рантайма нет, ABI
нет, и загрузить сторонний код в работающий процесс невозможно.

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

## Что публично

Эти поверхности покрыты [семантическим версионированием](https://omniflow-vpn.mintlify.site/ru/operations/compatibility.md)
и политикой устаревания на той же странице. Ломающее изменение любой из них — это
мажорная версия и запись в `CHANGELOG.md`, а не молчаливая смена поведения.

| Поверхность | Что это | Гарантия |
| - | - | - |
| `/v1/admin` | API с bearer-токеном для скриптов и других сервисов | Полностью описан в `api/openapi.yaml`. Устаревшая операция или поле продолжают работать минимум ещё один минорный выпуск. |
| `api/openapi.yaml` | Исходный контракт | То, что отображает опубликованный [справочник API](https://omniflow-vpn.mintlify.site/ru/integrations/api.md) и по чему строится сгенерированный клиент. |
| `POST /v1/payments/webhooks/{provider}` | Приём вебхуков провайдеров | Форма маршрута и поведение проверки подписи стабильны; тела принадлежат провайдерам. |
| `GET /v1/catalog/plans` | Анонимное чтение витрины | Стабильно и без учётных данных, для лендинга или прайс-листа. |
| `/healthz`, `/livez`, `/readyz`, `/metrics` | Пробы и метрики | Стабильные имена и стабильные метки метрик. |
| Переменные окружения | Всё из [Конфигурации](https://omniflow-vpn.mintlify.site/ru/getting-started/configuration.md) | Устаревшая переменная продолжает работать рядом со своей заменой минимум один минорный выпуск. |
| Образы контейнеров и их теги | `ghcr.io/kewldan/omniflow/*` | Версионированы, подписаны, с SBOM и provenance. |

## Что внутреннее

Опираться на любое из этого можно — это ваша установка, — но обещаний
совместимости здесь нет, и уведомление об устаревании не полагается.

* **`/v1/panel` и `/v1/account`.** Они существуют, чтобы обслуживать две панели, и
  меняются вместе с экранами. Они привязаны к сессии с CSRF, так что скрипту с
  ними в любом случае неудобно. Используйте `/v1/admin`.
* **Схема базы данных.** Миграции только вперёд, а таблицы перестраиваются, когда
  этого требует функция. Читайте с реплики, если необходимо; писать — только через
  API. Прямая запись обходит идемпотентность, аудит и правила
  «только-для-добавления», которые и делают финансовые записи достоверными.
* **Пакеты Go.** Каждый пакет лежит под `internal/`, поэтому компилятор
  гарантирует, что ничто вне этого модуля их не импортирует. Это намеренно: так
  сопровождающие свободны менять внутренности, а «расширение» никогда не
  превращается в «кто-то зависит от сигнатуры этой функции».
* **Каталоги сообщений, внутренности компонентов и сгенерированные клиенты.** Они
  перегенерируются.
* **Схема River и полезная нагрузка заданий.** Аргументы задания — деталь
  реализации того процесса, который его ставит.

## Расширение без правки кода

Четыре точки интеграции принимают выбранную вами точку входа, и вклад в
репозиторий не нужен. Именно поэтому плагинного рантайма нет, а не «он ещё не
готов»: то, что людям действительно хочется подключить, — это внешние сервисы, а
внешнему сервису нужны URL и учётные данные, а не механизм загрузки кода.

| Точка | Что предоставляете вы | Где |
| - | - | - |
| Провайдер моделей AI | Любая точка входа, совместимая с OpenAI, Anthropic или Gemini, включая модель на вашем железе | [Провайдеры AI и локальные модели](https://omniflow-vpn.mintlify.site/ru/operations/ai-providers.md) |
| Поставщик идентичности OIDC | Документ discovery; несколько провайдеров работают одновременно для операторов и для клиентов | [Вход через OIDC](https://omniflow-vpn.mintlify.site/ru/integrations/oidc.md) |
| Сервер MCP | Точка входа Streamable HTTP, разрешённая по каждому инструменту, с ограничением исходящих соединений и сопоставлением с RBAC | [Подключения MCP](https://omniflow-vpn.mintlify.site/ru/operations/mcp.md) |
| Обратный прокси | Caddy, Traefik или что угодно другое; поставляются два примера, и ни один не обязателен | [Обратный прокси](https://omniflow-vpn.mintlify.site/ru/operations/reverse-proxy.md) |

Ещё три — это конфигурация уже вкомпилированных адаптеров: платёжные провайдеры,
шлюз цифровых товаров и подключение к Remnawave. Вы выбираете, какие включены, с
какими учётными данными и какими возможностями, но не то, на каком протоколе они
говорят.

## Добавление адаптера

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

Платёжный адаптер реализует шесть методов — `Name`, `Capabilities`, `Create`,
`Poll`, `Refund` и `VerifyWebhook` — и объявляет, что он на самом деле умеет,
через `Capabilities`, а не через флаг в конфигурации. Три необязательных
интерфейса подхватываются, если реализованы: списание с сохранённого метода без
присутствия клиента, восстановление намерения, чья ссылка потеряна, и объявление
поддерживаемых валют. Адаптер, который не объявляет валюты, принимает ту, что
несёт заказ.

На чём ревью будет настаивать в любом случае:

* **Идемпотентность — забота адаптера тоже.** Каждый изменяющий вызов несёт ключ
  идемпотентности, и повторный вызов не должен подвинуть деньги дважды. Адаптер,
  который не может его соблюсти, обязан об этом сказать, и конвейер трактует
  неоднозначный исход как случай для человека, а не повторяет попытку, — ровно так
  сегодня и поступает шлюз цифровых товаров.
* **Возможности объявляются, а не предполагаются.** Кнопка возврата у провайдера,
  который не умеет возвращать, — это будущее обращение в поддержку.
* **Проверка вебхука выполняется раньше всего остального**, по сырому телу, с
  ограничением размера, и неуспешная проверка всё равно записывается.
* **Ни один секрет не попадает в лог, в ошибку, показанную браузеру, или в набор
  диагностики.** Текст ошибки провайдера может вернуть запрос обратно — поэтому
  адаптеры моделей возвращают статус и ничего больше.
* **Вместе с ним поставляются тесты путей отказа и идемпотентности**, а также
  фикстуры воспроизведения для форм вебхуков.

Сначала откройте предложение функции — см.
[SUPPORT.md](https://github.com/kewldan/omniflow/blob/main/SUPPORT.md), — потому
что вопрос, стоит ли нести этого провайдера, относится к сопровождению, а не к
качеству кода. `ROADMAP.md` прямо говорит, что дополнительные платёжные
провайдеры добавляются, когда об этом просит оператор, а не ради их количества.

## Что намеренно нерасширяемо

* **Нет плагинного рантайма.** Нет хоста WASM, нет динамической загрузки и нет
  точки расширения, выполняющей сторонний код в процессе Omniflow. Песочница
  возможностей — кандидат после 1.0, и ей нужен проект безопасности, а не
  библиотека.
* **Нет второго места, решающего, что позволено роли.** Каталог прав доступа и
  сопоставление ролей вкомпилированы в `internal/rbac`, поэтому ни файл
  конфигурации, ни строка в базе, ни интеграция не могут расширить доступ.
* **Никаких записей в хранилище Remnawave и никакого управления Xray** — ничем,
  включая адаптер. См.
  [запись 0004](https://omniflow-vpn.mintlify.site/ru/architecture/decision-0004-remnawave-boundary.md).
* **Ни AI, ни MCP не могут обойти RBAC, подтверждение, идемпотентность или журнал
  аудита.** Инструмент сопоставлен с правом доступа, которое у оператора уже
  есть, а значимое изменение требует человека.

## Смежное

> **[Интеграция с API](https://omniflow-vpn.mintlify.site/ru/integrations/api.md)**
>
> Bearer-токен, ключи идемпотентности, курсоры, ответы об ошибках и известные пробелы контракта.

> **[Совместимость и обновления](https://omniflow-vpn.mintlify.site/ru/operations/compatibility.md)**
>
> Матрица версий, окно обновления и политика устаревания, на которую опирается эта страница.

> **[Процесс выпуска](https://omniflow-vpn.mintlify.site/ru/contributing/releases.md)**
>
> Как изменение становится версией и что публикует выпуск.

> **[Архитектурные решения](https://omniflow-vpn.mintlify.site/ru/architecture/decisions.md)**
>
> Записи, ограничивающие то, чем расширению позволено быть.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.