209 lines
16 KiB
Markdown
209 lines
16 KiB
Markdown
# Read-only аудит failover/failback
|
||
|
||
## Короткий вывод
|
||
|
||
Штатное переключение между `primary` и `reserve` меняет маршрут **только для новых соединений**. Уже установленные TCP/UDP-соединения не переносятся и не закрываются самим Harbor.
|
||
|
||
Поэтому:
|
||
|
||
- здоровая загрузка, игра или поток продолжаются через старый канал;
|
||
- если старый канал действительно умер, существующая сессия может оборваться независимо от переключения;
|
||
- после переключения новые соединения идут через новый канал;
|
||
- бесшовной миграции уже открытого TCP/UDP-сеанса на другой внешний адрес нет.
|
||
|
||
## 1. Точный механизм
|
||
|
||
### Конфигурация
|
||
|
||
Gateway собирает один dual-channel `sing-box` config:
|
||
|
||
- `channel-primary`;
|
||
- `channel-reserve`;
|
||
- selector `channel-selector`;
|
||
- стабильные `tproxy-in` и `mixed-in`;
|
||
- отдельные diagnostic inbounds для проверки каждого канала.
|
||
|
||
Пользовательский трафик направляется в selector, а selector настроен с:
|
||
|
||
```text
|
||
interrupt_exist_connections: false
|
||
```
|
||
|
||
См. `src/server/singbox.ts:204-247`.
|
||
|
||
Роль меняется через localhost Clash API:
|
||
|
||
- `PUT /proxies/channel-selector`;
|
||
- затем Harbor читает selector обратно и подтверждает выбранную роль.
|
||
|
||
См. `src/server/services/singboxSelectorService.ts:29-81`.
|
||
|
||
Failover API доступен только в Gateway:
|
||
|
||
- `PUT /api/failover`;
|
||
- `POST /api/failover/pause`;
|
||
- `POST /api/failover/switch`;
|
||
- `POST /api/failover/check`.
|
||
|
||
См. `src/server/http/routes/failoverRoute.ts:18-39`.
|
||
|
||
Переключение selector не вызывает `sing-box` restart/apply/stop.
|
||
|
||
### Автоматический failover
|
||
|
||
`FailoverService`:
|
||
|
||
1. Проверяет оба канала через отдельные diagnostic inbound и выбранные HTTPS-сервисы.
|
||
2. Считает канал healthy только если все проверки успешны; неизвестный результат даёт `unknown`.
|
||
3. При сбое primary ждёт `failureWindowMs`.
|
||
4. Переключается на reserve только если reserve healthy.
|
||
5. При включённом traffic guard ждёт свежий quiet-window.
|
||
6. Перед самой сменой повторно проверяет здоровье и активность.
|
||
7. Выполняет selector PUT, read-back и только после этого обновляет canonical applied state.
|
||
|
||
См. `src/server/features/failover/failoverService.ts:225-245`, `:320-514`; state machine — `src/shared/failover.ts:278-354`.
|
||
|
||
Дефолты:
|
||
|
||
- проверка каждые 60 секунд;
|
||
- сбой primary — 120 секунд;
|
||
- восстановление primary — 15 минут;
|
||
- quiet-window — 30 секунд;
|
||
- активный трафик — выше 32 КБ/с;
|
||
- минимум на reserve — 10 минут;
|
||
- после 3 failover за 24 часа — карантин primary на 6 часов.
|
||
|
||
См. `src/shared/failover.ts:137-148`.
|
||
|
||
### Автоматический failback
|
||
|
||
Отдельной реализации нет: это обратная ветка той же state machine.
|
||
|
||
Из reserve Harbor возвращается на primary только после:
|
||
|
||
- полного `recoveryWindowMs`;
|
||
- `minimumReserveMs`;
|
||
- окончания quarantine, если он действует;
|
||
- quiet-window при включённом traffic guard;
|
||
- подтверждения, что primary healthy.
|
||
|
||
Причина переключения публикуется как `primary-recovered`. См. `src/shared/failover.ts:311-354`.
|
||
|
||
## 2. Судьба существующих соединений
|
||
|
||
| Событие | Уже открытый TCP/UDP flow | Новые соединения |
|
||
|---|---|---|
|
||
| Автоматический failover primary → reserve | Остаётся на прежнем outbound; Harbor его не закрывает и не мигрирует | Идут через reserve |
|
||
| Автоматический failback reserve → primary | Остаётся на reserve | Идут через primary |
|
||
| Ручной selector switch | Не закрывается, если старый outbound ещё работает | Сразу идёт через выбранную роль |
|
||
| Pause | Ничего не меняет | Идут через текущую роль |
|
||
| Disable failover | Selector и текущий маршрут не меняются; dual config временно остаётся загруженным | Идут через текущую роль |
|
||
| Обычный stop/restart/config replacement | Процесс `sing-box` останавливается, поэтому TCP/UDP-сессии прерываются | После запуска — по новой конфигурации |
|
||
| Реальная авария primary | Уже существующий flow может оборваться сам; Harbor не может перенести его на другой внешний IP | После selector switch новые flow идут через reserve |
|
||
|
||
Проверка `interrupt_exist_connections: false` непосредственно подтверждена TCP- и UDP-fixture-тестом: существующие TCP socket и UDP association продолжают обмен после switch, а новые идут через reserve. См. `test/server/singbox-selector-capability.test.js:141-142`, `:237-356`.
|
||
|
||
## 3. Отличия режимов
|
||
|
||
### Ручное переключение
|
||
|
||
`POST /api/failover/switch` вызывает selector напрямую:
|
||
|
||
- traffic guard не проверяется;
|
||
- состояние здоровья целевого канала backend не проверяет;
|
||
- после успешного ручного переключения `failoverPolicy.paused` становится `true`;
|
||
- автоматический failback не произойдёт, пока пользователь не возобновит автоматическое переключение.
|
||
|
||
См. `src/server/features/failover/failoverService.ts:248-317`, `:614-631`.
|
||
|
||
Это означает, что ручной switch может быть выполнен даже на канал, который сейчас не подтверждён healthy. Это важная оговорка.
|
||
|
||
### Автоматический failover
|
||
|
||
Автоматическое переключение:
|
||
|
||
- ждёт failure window;
|
||
- требует healthy reserve;
|
||
- при включённом guard блокируется активным или неизвестным трафиком;
|
||
- повторно валидирует условия непосредственно перед selector mutation;
|
||
- не перезапускает `sing-box`.
|
||
|
||
### Восстановление primary
|
||
|
||
Восстановившийся primary не получает новые соединения сразу. Сначала выдерживаются recovery/hold/quarantine условия и quiet-window. Пока они не выполнены, новые подключения остаются на reserve.
|
||
|
||
### Pause и Disable
|
||
|
||
`pause` приостанавливает решения, но dual config и наблюдение остаются активными.
|
||
|
||
`disable` останавливает scheduler, probes и failover activity collector, но не переключает selector и не перезапускает процесс. После обычного stop/следующего запуска собирается single-channel config.
|
||
|
||
См. `README.md:78-84`, `docs/product/application-state.md:102-110`.
|
||
|
||
## 4. Практические сценарии
|
||
|
||
- **Загрузка файла:** при обычном автоматическом failover активная передача по умолчанию задерживает switch. Если primary всё же упал, текущая TCP-загрузка не переносится на reserve; она может завершиться ошибкой. Возобновление или новый HTTP-запрос после switch пойдёт через reserve.
|
||
- **Игровая сессия:** существующий TCP-сеанс остаётся на старом канале. TCP-сессия оборвётся, если primary реально недоступен. UDP-flow также не мигрирует и может начать терять пакеты или истечь по timeout; новая сессия после switch пойдёт через reserve.
|
||
- **Стрим:** активный поток обычно блокирует автоматический switch при включённом guard. Ручной switch может быть выполнен сразу, но существующий TCP/QUIC-поток остаётся на старом outbound. При аварии старого канала плеер должен переподключиться.
|
||
- **WebSocket/долгий polling:** действующий flow не переносится; новые подключения после switch используют новую роль.
|
||
- **Молчащее соединение:** наличие открытого socket само по себе не считается активностью. Guard смотрит на дельты переданных байтов.
|
||
|
||
## 5. Условия и оговорки
|
||
|
||
- Failover реализован только для **Gateway**, не для локального Connect или `gateway-direct`.
|
||
- Активность собирается существующим `/connections` observer каждые 2 секунды, с bounded окном до 10 секунд. См. `src/server/index.ts:311-333`, `src/server/services/domainTrafficService.ts:323-416`, `:437-495`.
|
||
- Короткое соединение, полностью завершившееся между двумя снимками, может не попасть в activity guard.
|
||
- Неизвестная или устаревшая activity-информация блокирует автоматический switch; ручной switch остаётся доступен.
|
||
- Отключение traffic guard разрешает автоматический switch без ожидания тишины, но `interrupt_exist_connections: false` всё равно защищает уже открытые connections от закрытия самим selector.
|
||
- При изменении policy во время работающего single-channel VPN dual config становится `pending`; скрытого restart нет. См. `src/server/features/connection/connectionService.ts:140-201`, `:288-361`.
|
||
- Явный stop/restart или обычная смена сервера вне активного failover уже является disruptive operation: `sing-box` получает SIGTERM и текущие сессии прекращаются. См. `src/server/singboxRuntime.ts:39-62`, `:65-122`.
|
||
- Оба канала находятся в одном процессе `sing-box`; process-wide crash не защищён selector-механизмом.
|
||
|
||
## 6. Основные файлы
|
||
|
||
- `src/server/singbox.ts:204-247` — dual config, selector, inbound routing.
|
||
- `src/server/services/singboxSelectorService.ts:29-81` — selector PUT/read-back.
|
||
- `src/server/features/failover/failoverService.ts:225-245` — проверки каналов.
|
||
- `src/server/features/failover/failoverService.ts:248-317` — selector switch, commit и rollback.
|
||
- `src/server/features/failover/failoverService.ts:320-514` — автоматический раунд и traffic guard.
|
||
- `src/server/features/failover/failoverService.ts:614-631` — ручное переключение.
|
||
- `src/shared/failover.ts:137-148`, `:278-354` — дефолты и state machine.
|
||
- `src/server/services/domainTrafficService.ts:129-160`, `:323-416`, `:437-495` — классификация и activity.
|
||
- `src/server/features/connection/connectionService.ts:140-201`, `:243-361` — обычный apply/stop/restart.
|
||
- `src/server/singboxRuntime.ts:39-122` — фактическая остановка и перезапуск процесса.
|
||
- `README.md:78-84` — пользовательская документация.
|
||
- `docs/product/application-state.md:102-110` — контракт состояния.
|
||
- `workpack/tasks/TASK-021-auto-server-selection-failover.md:93-106`, `:187-204` — относящийся план и ограничения; задача не выбиралась и не изменялась.
|
||
|
||
## 7. Тесты, подтверждающие выводы
|
||
|
||
- `test/server/singbox-selector-capability.test.js:141-356`
|
||
Интеграционная TCP/UDP-проверка: активный трафик задерживает failover, существующие TCP/UDP продолжают работать после switch, новые соединения идут через reserve, PID процесса не меняется. Тест opt-in и пропускается без `HARBOR_SINGBOX_IMAGE`.
|
||
- `test/server/singbox-gateway-mode.test.js:69-110`
|
||
Проверяет selector, `interrupt_exist_connections: false`, отдельные diagnostic routes и primary/reserve outbounds.
|
||
- `test/server/failover-service.test.js:83-200`
|
||
Failure window, traffic guard, both-unhealthy и failback recovery/hold/quarantine.
|
||
- `test/server/failover-service.test.js:255-420`
|
||
Disabled zero-work, отмена устаревших наблюдений и непосредственная revalidation активности.
|
||
- `test/server/failover-service.test.js:423-520`
|
||
Selector rollback, commit ordering и ручной switch с pause.
|
||
- `test/server/domain-traffic.test.js:209-239`
|
||
Activity считается по пользовательскому VPN traffic, diagnostic connection не блокирует switch.
|
||
- `test/server/connection-service.test.js:265-310`, `:340-390`
|
||
Restart dual config и rollback; pending edits для работающего single-channel.
|
||
- `test/server/singbox-runtime.test.js:16-50`
|
||
При изменении config runtime запускает новый процесс.
|
||
- `test/server/failover-route.test.js:10-53`
|
||
Gateway-only API и маршруты ручного switch/pause/check.
|
||
- `test/web/failover-feature-contract.test.js:19-76`
|
||
UI явно сообщает: новые подключения переключаются, открытые остаются на прежнем канале.
|
||
|
||
## Review findings и residual risks
|
||
|
||
- **medium — `src/server/features/failover/failoverService.ts:614-620`:** ручной switch не проверяет health целевого канала и не применяет traffic guard; он сразу меняет selector и ставит automation на pause.
|
||
- **medium — `test/server/singbox-selector-capability.test.js:141-356`:** capability test opt-in и использует deterministic `direct` outbounds, а не реальный VLESS/Trojan outage.
|
||
- **medium — `src/server/services/domainTrafficService.ts:414-416`, `:451-479`:** activity основана на polling и byte deltas; короткие или очень малые потоки могут не блокировать автоматическое решение.
|
||
- **info — `src/server/singboxRuntime.ts:39-122`:** явный stop/restart отличается от selector switch и прерывает существующие соединения.
|
||
- **info — архитектура одного процесса:** падение всего `sing-box` не компенсируется selector failover.
|
||
|
||
Файлы не изменялись. Тесты и live Gateway в рамках read-only аудита не запускались. |