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
• какая policy была в HY2XS_HYSTERIA_VERSION (latest|vX.Y.Z)

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

Проверка логов через journald:

journalctl -u hysteria-server -n 100 --no-pager
journalctl -u hy2xs-admin -n 100 --no-pager

Auth endpoint fail checklist

systemctl status hysteria-server
systemctl status hy2xs-admin

sudo -u hy2xs-admin test -r /etc/hysteria/config.yaml

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  --data '{"addr":"127.0.0.1:12345","auth":"invalid","tx":"0"}' \
  http://127.0.0.1:8080/hui/hysteria2/auth

curl -sS \
  -H "Authorization: <trafficStatsSecret>" \
  http://127.0.0.1:36712/online

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

Сервер установился, но 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.

Редактировать нужно /etc/hy2xs/hy2xs.env и затем запускать reconfigure --dry-run/--apply.

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

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