126 lines
4.5 KiB
Markdown
126 lines
4.5 KiB
Markdown
# 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
|
||
- какая версия 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
|
||
```
|
||
|
||
## 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`.
|
||
|
||
## Правила эксплуатации
|
||
|
||
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).
|