> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Grace access

> Временный ограниченный доступ после истечения подписки или исчерпания трафика

## Обзор

Grace access — временный урезанный доступ для подписок, которые только что перешли в `expired` (закончился срок) или `limited` (закончился трафик). Человек не остаётся полностью без связи и успевает продлиться, а не уходит к конкуренту в тот же вечер.

Подсистема появилась в `v3.65.0` и была упрощена в `v3.66.0`.

> [!NOTE]
>
> Биллинг остаётся источником истины. Grace — это **временный оверлей в Remnawave** и отдельная запись сессии. Подсистема никогда не меняет даты и статус подписки в биллинге и никогда не обнуляет использованный трафик.

## Как это работает

**1. Обнаружение**

Фоновый цикл ищет подписки, недавно перешедшие в `expired` или `limited`. Глубина поиска назад по времени — `GRACE_ACCESS_CANDIDATE_LOOKBACK_MINUTES`.

**2. Проверка права на grace**

Подписка должна подходить по типу (см. [Кому выдаётся](#кому-выдаётся)) и не иметь уже открытой сессии.

**3. Наложение оверлея**

В панели пользователю выставляется сквад grace и квота `GRACE_ACCESS_TRAFFIC_GB`. Прежнее состояние сохраняется в версионированном снимке.

**4. Окно доступа**

Сессия живёт `GRACE_ACCESS_DURATION_HOURS` часов. Всё это время пользователь может продлиться обычным способом.

**5. Восстановление**

По оплате, по истечении окна или по отзыву панельное состояние возвращается из снимка методом compare-and-set — чужие изменения, сделанные администратором вручную, не затираются.

## Режимы работы

`GRACE_ACCESS_MODE` принимает четыре значения:

| Режим | Что делает |
| - | - |
| `false` | Выключено. Ничего не пишется и не выдаётся |
| `observe` | Только журнал: кандидаты фиксируются, но доступ не выдаётся. Режим для обкатки на живом трафике |
| `true` | Рабочий режим: доступ выдаётся |
| `drain` | Новые сессии не открываются, уже открытые доживают до конца окна и корректно восстанавливаются |

> [!TIP]
>
> Порядок безопасного включения: `observe` → посмотреть в логах, сколько подписок попадает в кандидаты → `true`. Выключать лучше через `drain`, а не сразу в `false`: так открытые сессии не останутся с оверлеем в панели.

## Кому выдаётся

При `GRACE_ACCESS_MODE=true` доступ получают **обычные платные несуточные** подписки. Остальные категории включаются отдельно:

| Переменная | Категория | По умолчанию |
| - | - | - |
| `GRACE_ACCESS_TRIAL_ENABLED` | Триальные подписки | `false` |
| `GRACE_ACCESS_DAILY_ENABLED` | Суточные тарифы | `false` |
| `GRACE_ACCESS_FREE_ENABLED` | Бесплатные (0₽) тарифы | `false` |

> [!WARNING]
>
> Суточные тарифы и триалы по умолчанию выключены намеренно: у них срок истекает штатно и часто, поэтому grace для них превращается в постоянную бесплатную выдачу.

## Настройка

```env theme={null}
# false | observe | true | drain
GRACE_ACCESS_MODE=false

# Длительность окна и квота трафика на это время
GRACE_ACCESS_DURATION_HOURS=72
GRACE_ACCESS_TRAFFIC_GB=1

# Сквады, в которые уводятся подписки на время grace
GRACE_ACCESS_EXPIRED_SQUAD_UUID=
GRACE_ACCESS_LIMITED_SQUAD_UUID=

# Дополнительные категории подписок
GRACE_ACCESS_TRIAL_ENABLED=false
GRACE_ACCESS_DAILY_ENABLED=false
GRACE_ACCESS_FREE_ENABLED=false

# Фоновая сверка сессий
GRACE_ACCESS_RECONCILE_INTERVAL_SECONDS=60
GRACE_ACCESS_RECONCILE_BATCH_SIZE=200
GRACE_ACCESS_CANDIDATE_LOOKBACK_MINUTES=30
```

### Сквады

Заведите в Remnawave отдельные сквады под grace и укажите их UUID:

* `GRACE_ACCESS_EXPIRED_SQUAD_UUID` — для подписок, у которых закончился срок;
* `GRACE_ACCESS_LIMITED_SQUAD_UUID` — для подписок, у которых закончился трафик.

Разделение позволяет дать этим двум группам разные ноды или разную политику — например, увести истёкших на медленный сквад, а «упёршихся в трафик» оставить на прежних нодах с урезанной квотой.

> [!NOTE]
>
> Если UUID не задан, подписки этой категории grace не получают — сквад для оверлея обязателен.

## Жизненный цикл сессии

| Состояние | Значение |
| - | - |
| `pending` | Оверлей ещё не применён в панели (панель недоступна или не приняла переход) |
| `active` | Оверлей применён, идёт окно доступа |
| `restoring` | Идёт возврат прежнего панельного состояния |
| `completed` | Сессия закрыта |

Причина закрытия фиксируется отдельно:

| Причина | Когда |
| - | - |
| `paid` | Пользователь продлился — самый желанный исход |
| `timeout` | Окно закончилось |
| `drained` | Режим переведён в `drain` |
| `conflict` | Панельное состояние разошлось со снимком |
| `revoked` | Доступ отозван вручную |

## Ограничения

> **Grace не продлевает подписку**
>
> Даты и статус подписки в биллинге не меняются. Пользователь всё это время формально остаётся без активной подписки — grace только даёт временный канал связи.

> **Использованный трафик не обнуляется**
>
> Квота `GRACE_ACCESS_TRAFFIC_GB` — это то, что реально доступно во время окна, а не сброс счётчика подписки.

> **Панель может не принять переход сразу**
>
> Если Remnawave недоступна, сессия остаётся в `pending` и будет доведена фоновой сверкой. Сверка идёт раз в `GRACE_ACCESS_RECONCILE_INTERVAL_SECONDS` секунд батчами по `GRACE_ACCESS_RECONCILE_BATCH_SIZE`.

## Связанные разделы

> **[Подписки](/bot/subscriptions)**
>
> Статусы подписок и жизненный цикл

> **[Remnawave](/integrations/remnawave)**
>
> Сквады, синхронизация и панельная идентичность


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