# ADR-0003: цепочка 3x-ui REALITY на otreca — что нельзя менять

**Статус:** accepted

**Дата:** 2026-10-10

**Контекст:**

10 октября 2026 владелец сообщил: «по прежнему не работает xray inbound через
3x-ui на otreca. Не знаю, в какой момент после правок агента всё пошло не туда».
Разбор занял ~1.5 часа и дал неочевидный результат: **сервер был полностью
работоспособен**, а «поломка» читалась как системная катастрофа.

Хронология по коммитам и журналам:

| Время (MSK) | Событие |
|---|---|
| 16:25:52 | `0df9688` (задача T10) — удалён `reality443Forwarding` |
| 17:05:27 | первый `Connection refused` к `127.0.0.1:15380` в журнале nginx |
| 17:07:33 | первое `worker_connections are not enough` (адрес обезличен) |
| ~17:15 | клиенты уходят в ретрай-петлю: ~1668 ошибок за ~40 мин |
| 17:30:58 | `37b4956` — revert nftables (T3) |
| 17:54:18 | `07a0437` — `reality443Forwarding` восстановлен |
| 17:55:38 | контейнер `3xui_app` пересоздан с `127.0.0.1:15380:443/tcp` |
| ~18:05+ | флуд прекращается, ошибок 0 за 36 мин |
| 19:16–19:19 | живые REALITY-сессии, клиенты online |

Два вывода, которые неочевидны и потому требуют фиксации:

1. **Отказ `reality443Forwarding` не выглядит как отказ Xray.** Контейнер
   здоров (`restarts=0`), ядро 26.7.28 на месте, SSH жив, панель по SNI
   `pubray1.zeroq.su` отвечает валидным сертификатом. Умер только маршрут
   `443 → 15380`. Диагностировать «панель/Xray» по симптому бесполезно —
   надо проверять порт и `podman inspect .NetworkSettings.Ports`.

2. **`worker_connections are not enough` — вторичный симптом, а не причина.**
   nginx имеет пустой `events {}` → `worker_connections` = 512 (дефолт). Пока
   маршрут на 443 был мёртв, реальные клиенты слали 517-байтные ClientHello
   в цикле и выедали 512 соединений. Из-за этого «не работало всё» даже там,
   где конкретная причина уже была устранена, и создавался флуд в логах,
   уводящий от настоящей причины. Источники флуда — два адреса /24 из
   разных сетей; адреса и провайдеры обезличены (репозиторий публичный).

Отдельно: `x-ui.db.bak.1787862834` (2026-08-27) при поверхностном взгляде
выглядит как «бэкап, который можно откатить». Это **другая конфигурационная
эпоха** — инбаунды на портах 14380/14480/14910/14920, 7 клиентов, без
`dest media.mediavitrina.ru`. Откат заменил бы рабочие 443/8443 и обесценил
все 11 клиентских конфигов.

**Рассматриваемые альтернативы:**

1. **A. Оставить как есть, зафиксировать инвариантами (выбрано).** R1.10–R1.13
   + ловушки + порядок диагностики. Минимум правок в коде.
2. **B. Поднять `worker_connections` в `modules/vds/nginx.nix`.** Убирает
   вторичный симптом, но **не первопричину**, а файл в AGENTS.md помечен как
   мёртвый (T13: `networking.firewall.allowedTCPPorts` не применяется).
   Отложено до отдельной задачи — не смешивать с починкой.
3. **C. Бан ретрай-флуда (fail2ban/rate-limit на 443).** Отклонено: флуд
   создавали легитимные клиенты, а не атака. Jail `3x-ipl` в контейнере
   (`maxRetry=1`) за инцидент не забанил никого — 0 банов. Любое усиление
   должно отличать «шторм переподключений» от «злоупотребления».
4. **D. Пин версии образа 3x-ui вместо `:latest`.** Отклонено: противоречит
   R1.5 (панель намеренно `:latest`). Схема БД мигрирует на месте при
   обновлении — это отдельный риск, не решается версией образа.

**Решение:** вариант **A**. Зафиксированы R1.10 (уже был) и новые
R1.11–R1.13, две новые ловушки, порядок диагностики из 5 шагов и команды
проверки в раздел «Проверки».

**Обоснование:**

- **Стоимость ошибки асимметрична.** Удаление одной опции уронило прокси на
  1.5 часа и выглядело как «сломался весь сервер». Повторение должно быть
  видно в правилах, а не восстанавливаться снова.
- **Правило без сигнатуры бесполезно.** «Не удалять `reality443Forwarding`»
  без описания симптома не помогает — агент видит «панель отвечает» и
  concludes «3x-ui работает». Поэтому R1.10 дополнирован сигнатурой отказа
  и порядком диагностики.
- **Нумерация R1 была сломана.** В `project-rules.md` два пункта были
  помечены «8», из-за чего `reality443Forwarding` был девятым по счёту, но
  AGENTS.md, ловушки и `f2e70bb` уже ссылались на него как на **R1.10**.
  Порядок исправлен (R1.8 ядро, R1.9 бэкапы, R1.10 reality) — иначе
  перекрёстные ссылки расходятся.
- **Откат БД — ловушка с высоким потенциалом.** Файл называется
  `x-ui.db.bak.*` и выглядит как безопасный откат; на деле — снимок
  другой эпохи. Запрет зафиксирован явно (R1.12).

**Последствия:**

- Любая правка `ports` в `modules/containers/3x-ui.nix` требует
  `nixos-rebuild switch` **и** проверки `podman inspect .NetworkSettings.Ports` (R1.11).
- Деплой, пересоздающий `3xui_app`, = окно недоступности REALITY с
  ретрай-флудом. Планировать такие деплои в нерабочее время.
- `worker_connections = 512` остаётся известным пробелом — отдельная задача,
  файла в манифесте пока нет.
- Панель живёт по адресу `https://pubray1.zeroq.su/pubray/`; запрос к `/`
  даёт 404 и это норма (ловушка в `project-rules.md`).

**Связанное:** R1.10–R1.13, R1.5, R1.8, T10, T3, `.agent/rules/project-rules.md`.