hysteria2/README.md

# Ansible-роль: Hysteria2 Server

Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS: ACME-сертификат, masquerade под nginx, несколько пользователей, экспорт URL/QR и HTML-каталог.

## Быстрый старт

```bash
cd ~/Разработка/hysteria2

make init            # inventory, group_vars, vault, .vault_pass
# отредактировать:
#   inventory/hosts.yml
#   group_vars/all.yml
#   group_vars/hysteria2_servers/vault.yml

make vault-encrypt   # зашифровать пароли VPS
make ping            # проверить SSH
make install         # установка → output/ → браузер откроется сам
```

## Makefile

| Команда | Описание |
|---|---|
| `make help` | Справка |
| `make init` | Создать конфиги из `.example` |
| `make ping` | Проверить SSH к VPS |
| `make status` | `systemctl status hysteria-server` |
| `make install` | Установка + экспорт + `output/index.html` + открытие в браузере |
| `make update` | Обновить бинарник, конфиг, перевыпустить экспорт |
| `make export` | Только экспорт URL/QR/HTML |
| `make uninstall` | Удалить Hysteria2 с VPS |
| `make vault-encrypt` | Зашифровать vault |
| `make vault-edit` | Редактировать vault |

### Примеры

```bash
make install LIMIT=vps-de
make update LIMIT=vps-nl
make export
make uninstall LIMIT=vps-de EXTRA_VARS='hysteria2_uninstall_remove_local_output=true'
make install EXTRA_VARS='hysteria2_open_browser=false'   # без авто-открытия браузера
```

## Inventory

```yaml
all:
  children:
    hysteria2_servers:
      hosts:
        vps-de:
          ansible_host: 203.0.113.10
          ansible_port: 2222              # SSH-порт (если не 22)
          ansible_user: root
          ansible_password: "{{ vault_ssh_passwords['vps-de'] }}"
          hysteria2_domain: vpn-de.example.com
          hysteria2_users:
            - my
            - friend

        vps-nl:
          ansible_host: 203.0.113.20
          ansible_user: root
          ansible_password: "{{ vault_ssh_passwords['vps-nl'] }}"
          hysteria2_domain: vpn-nl.dynu.net
          hysteria2_users:
            - alice
            - bob
```

### SSH-подключение к VPS

| Параметр | Где | Описание |
|---|---|---|
| `ansible_host` | inventory | IP VPS |
| `ansible_port` | inventory | SSH-порт (по умолчанию `22`) |
| `ansible_user` | inventory | Пользователь SSH (обычно `root`) |
| `ansible_password` | inventory + vault | Пароль из `vault_ssh_passwords` |
| `ansible_ssh_private_key_file` | inventory | Альтернатива паролю — SSH-ключ |

```yaml
# group_vars/hysteria2_servers/vault.yml
vault_ssh_passwords:
  vps-de: "root-password-1"
  vps-nl: "root-password-2"
```

Ключи в `vault_ssh_passwords` совпадают с **именами хостов** в inventory.

## Пароли VPN-пользователей

1. **Vault** (рекомендуется):

```yaml
vault_hysteria2_user_passwords:
  vps-de:
    friend: "Aingae0Okit1eek4eeZahFohVei4akee"
```

2. **Per-host в inventory**:

```yaml
hysteria2_user_passwords:
  friend: "custom-password"
```

3. **Автогенерация** — `pwgen -s 40`, если пароль не задан.

При `make update` пароли подтягиваются из `output/<server>/server-info.yml`, если не указаны в vault/inventory.

## Результат: папка `output/`

```
output/
├── index.html              ← общий каталог всех серверов (открывается в браузере)
├── vps-de/
│   ├── index.html          ← страница сервера
│   ├── my.url
│   ├── my.png              ← QR PNG
│   ├── my.qr.txt           ← QR ASCII
│   ├── my.txt
│   └── server-info.yml
└── vps-nl/
    └── ...
```

### HTML-страницы

**`output/index.html`** — общий каталог:
- все серверы и пользователи на одной странице
- навигация по серверам
- поля ссылки/пароля с кнопкой копирования
- QR-коды
- ссылки на файлы и страницы серверов

**`output/<server>/index.html`** — страница одного сервера (тот же стиль, все пользователи сервера).

После `make install`, `make update` и `make export` **`output/index.html` автоматически открывается в браузере** (macOS: `open`, Linux: `xdg-open`).

Отключить авто-открытие:

```yaml
# group_vars/all.yml
hysteria2_open_browser: false
```

Или: `make install EXTRA_VARS='hysteria2_open_browser=false'`

## QR-коды

PNG генерируются средствами Ansible (без Python):

1. `apt install qrencode` на VPS (остаётся установленным)
2. `qrencode -o user.png "hysteria2://..."`
3. `fetch` — скачивание PNG на control node

ASCII QR — `hysteria share --qr` → `user.qr.txt`.

## Переменные

| Переменная | Где | Описание |
|---|---|---|
| `hysteria2_domain` | host | Домен с A-записью на IP |
| `hysteria2_users` | host | Список имён VPN-пользователей |
| `hysteria2_acme_email` | group | Email для Let's Encrypt |
| `hysteria2_user_passwords` | host/vault | Свои пароли VPN |
| `hysteria2_output_dir` | group | Папка экспорта (по умолчанию `./output`) |
| `hysteria2_output_name` | host | Имя подпапки (по умолчанию `inventory_hostname`) |
| `hysteria2_generate_qr_png` | group | PNG QR через `qrencode` |
| `hysteria2_open_browser` | group | Открыть `output/index.html` после экспорта |
| `hysteria2_uninstall_remove_local_output` | extra-vars | Удалить `output/<server>/` при uninstall |

## Безопасность

- `output/` содержит пароли и URL — в `.gitignore`
- `inventory/hosts.yml`, `vault.yml`, `.vault_pass` — не коммитить
- После `make init` выполните `make vault-encrypt`

## Требования

- Ansible 2.14+
- Debian/Ubuntu VPS с sudo
- Домен с A-записью на IP сервера
- Для авто-открытия браузера: macOS или Linux с `xdg-open`