# Operations and troubleshooting

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

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

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

### 0. Target prerequisites обязательны

На target-хосте до запуска install должны быть доступны системные зависимости:

```bash
apt-get update
apt-get install -y sudo ca-certificates curl iproute2 tar openssl nftables systemd
```

`sudo` обязателен: используется smoke-проверками прав от имени runtime-пользователей (`hysteria`, `hy2xs-admin`).

### 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
- какая версия Hysteria зафиксирована в metadata установленного пакета

Для обновления бинарника Hysteria2 используйте новый release install package.
Изменение runtime env не обновляет бинарник Hysteria2.

### 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
```

Проверка логов через journald:
```bash
journalctl -u hysteria-server -n 100 --no-pager
journalctl -u hy2xs-admin -n 100 --no-pager
```

Проверка install-state marker:
```bash
cat /var/lib/hy2xs/install-state.json
```

Если `reconfigure` сообщает об отсутствии marker, нужно повторно выполнить чистый install и только потом применять runtime-изменения.

## Auth endpoint fail checklist

```bash
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`.

### Изменили bootstrap-поля, но пароль admin не сменился
Это ожидаемо.

`HY2XS_ADMIN_INITIAL_PASSWORD` и `HY2XS_ADMIN_CON_PASS` используются только как bootstrap-данные при первичной установке.
Для ротации существующих credentials нужен отдельный flow на уровне account-management.

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

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).