HY2XS_flamy/docs/12-operations-and-troubleshooting.md

Operations and troubleshooting

Цель документа

Зафиксировать минимальный operational контур после установки.

Что должен помнить оператор

1. Builder и target — разные миры

Если нужно изменить состав install package, это делается в локальном builder layer, а не на target server.

2. UI приезжает из нашего пакета

Если проблема в UI, сначала смотреть:

• какой HUI_FORK_REF
• какой HUI_BUILD_ID
• тот ли пакет вообще стоит на сервере

3. Hysteria приходит из upstream

Если проблема в ядре Hysteria, сначала смотреть:

• какую фактическую версию оркестратор установил
• что записано в HY2_VERSION
• не связано ли поведение со свежим upstream release

4. Оркестратор — Bun/TypeScript, но target не билдит его

Если проблема в install flow, сначала смотреть:

• какой ORCH_BUILD_ID
• какой ORCH_ENTRYPOINT
• не подменён ли install package вручную

Базовые команды проверки

Проверка сервисов:

systemctl status hysteria-server
systemctl status hy2xs-admin

Проверка порта:

ss -uln

Проверка firewall:

nft list ruleset

Проверка post-install.env:

cat /etc/hysteria/post-install.env

Типовые проблемы

Сервер установился, но UI не работает

Проверить:

• разложился ли bundled UI
• корректен ли unit hy2xs-admin
• совпадает ли HUI_INSTALL_DIR с реальностью
• не сломан ли bind host / port

Hysteria скачалась, но не стартует

Проверить:

• валиден ли config
• совпадают ли listen port и firewall rule
• домен / SNI / TLS policy
• реальную установленную версию Hysteria

Тестовый клиент не подключается

Проверить:

• server_name
• порт
• obfs.password
• auth material
• что используется совместимый клиентский конфиг

Скорость не соответствует ожиданиям

Проверить:

• bandwidth.* на сервере
• клиентские up_mbps/down_mbps
• нет ли ложного ожидания, что один только host BBR решает speed policy

Изменили post-install.env, но runtime не изменился

Это ожидаемо.

post-install.env — reference file, а не autoreconcile engine.

Правила эксплуатации

1. Не править сервер как будто на нём есть builder.
2. Не считать bundled UI источником install-policy.
3. Не считать post-install.env автоматическим механизмом применения изменений.
4. Не расширять install-only baseline до lifecycle-manager без отдельного проектного решения.
5. Не смешивать install baseline и access/bot platform в одной документации.