# 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 в одной документации.