150 lines
5.7 KiB
Markdown
150 lines
5.7 KiB
Markdown
# 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).
|