Подготовить HY2XS к production-сборке

2026-04-25 23:13:12 +05:00
commit 84a4e94567
277 changed files with 26513 additions and 0 deletions
@@ -0,0 +1,94 @@
+# 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 вручную
+
+## Базовые команды проверки
+
+Проверка сервисов:
+```bash
+systemctl status hysteria-server
+systemctl status hy2xs-admin
+```
+
+Проверка порта:
+```bash
+ss -uln
+```
+
+Проверка firewall:
+```bash
+nft list ruleset
+```
+
+Проверка `post-install.env`:
+```bash
+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 в одной документации.