K3S/addons/hysteria2-server/README.md

# Hysteria2 Server

Устанавливает [Hysteria2](https://v2.hysteria.network/) VPN-сервер на удалённый VPS. На выходе даёт готовый URL для вставки в Shadowrocket, NekoBox, Hiddify или `vault_hysteria2_url` (Prowlarr sidecar).

## Что устанавливается

- Бинарник `hysteria` последней версии с GitHub
- Системный пользователь `hysteria`
- Конфиг в `/etc/hysteria/config.yaml`
- systemd-сервис `hysteria2` (autostart)
- Правило firewall (ufw / firewalld)
- TLS: self-signed cert **или** Let's Encrypt (ACME) **или** свой сертификат

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

### 1. Добавить VPS в inventory

```ini
# inventory/hosts.ini
[hysteria2_server]
myvps ansible_host=1.2.3.4 ansible_user=root
```

### 2. Vault секреты

```bash
make vault-edit
```

```yaml
# group_vars/all/vault.yml
vault_hysteria2_server_password: "my-secure-password-32chars+"
vault_hysteria2_obfs_password: "obfs-secret"   # если obfs включён
```

### 3. Деплой

**С SSH-ключом** (рекомендуется):
```bash
make addon-hysteria2-server
```

**С SSH-паролем** (ввод в терминале):
```bash
make addon-hysteria2-server ARGS="-k"
```

**С SSH-паролем + sudo-паролем**:
```bash
make addon-hysteria2-server ARGS="-k -K"
```

**На конкретный хост** (без inventory):
```bash
make addon-hysteria2-server ARGS="-i '1.2.3.4,' -u root -k"
```

После деплоя Ansible выведет готовый URL:
```
vault_hysteria2_url: "hysteria2://password@1.2.3.4:443?insecure=1#MyVPS"
```

---

## Конфигурация

### Режимы TLS

#### Self-signed (по умолчанию) — без домена, IP-only

```yaml
# group_vars/all/main.yml
hysteria2_server_tls_mode: "selfsigned"
```

Клиент подключается с `insecure=1`. URL автоматически получает `?insecure=1`.

#### ACME — Let's Encrypt (нужен домен)

```yaml
hysteria2_server_tls_mode: "acme"
hysteria2_server_domain: "vpn.example.com"
hysteria2_server_acme_email: "admin@example.com"
```

Требования: порт 80 открыт, DNS A-запись указывает на VPS. Hysteria2 сам получает и обновляет сертификат.

#### Custom — свои cert/key файлы

```yaml
hysteria2_server_tls_mode: "custom"
hysteria2_server_tls_cert_path: "/etc/hysteria/server.crt"
hysteria2_server_tls_key_path: "/etc/hysteria/server.key"
```

Сертификаты должны уже лежать на сервере до запуска роли.

---

### Obfuscation (salamander)

Скрывает протокол от DPI — важно если Hysteria2 блокируется провайдером:

```yaml
hysteria2_server_obfs_enabled: true
```

```yaml
# vault.yml
vault_hysteria2_obfs_password: "random-obfs-phrase"
```

---

### Лимиты полосы на клиента

```yaml
hysteria2_server_up_mbps: 100     # исходящий с сервера (= входящий у клиента)
hysteria2_server_down_mbps: 100   # входящий на сервер (= исходящий у клиента)
```

`0` — без ограничений.

---

### Все переменные

```yaml
hysteria2_server_version: ""          # "" = автоопределение последней версии
hysteria2_server_port: 443
hysteria2_server_password: "{{ vault_hysteria2_server_password }}"

hysteria2_server_tls_mode: "selfsigned"   # selfsigned | acme | custom
hysteria2_server_domain: ""
hysteria2_server_acme_email: ""
hysteria2_server_tls_cert_path: "/etc/hysteria/server.crt"
hysteria2_server_tls_key_path:  "/etc/hysteria/server.key"

hysteria2_server_obfs_enabled: false
hysteria2_server_obfs_password: "{{ vault_hysteria2_obfs_password | default('') }}"

hysteria2_server_masquerade_enabled: true
hysteria2_server_masquerade_url: "https://bing.com/"

hysteria2_server_up_mbps: 0
hysteria2_server_down_mbps: 0

hysteria2_server_name: "MyVPS"   # метка в URL (для клиентов)
```

---

## Подключение SSH

### Ключ (рекомендуется)

```bash
# Скопировать ключ на VPS
ssh-copy-id root@1.2.3.4

# Деплой
make addon-hysteria2-server
```

### Пароль

```bash
# Ввод пароля в терминале:
make addon-hysteria2-server ARGS="-k"
```

Или хранить в vault (не рекомендуется для SSH):

```yaml
# inventory/hosts.ini
[hysteria2_server]
myvps ansible_host=1.2.3.4 ansible_user=root ansible_ssh_pass="{{ vault_hysteria2_vps_ssh_password }}"
```

### Нестандартный SSH порт

```ini
# inventory/hosts.ini
[hysteria2_server]
myvps ansible_host=1.2.3.4 ansible_user=root ansible_port=2222
```

---

## Примеры inventory

### Один VPS, root + ключ

```ini
[hysteria2_server]
myvps ansible_host=1.2.3.4 ansible_user=root
```

### Один VPS, обычный пользователь + sudo

```ini
[hysteria2_server]
myvps ansible_host=1.2.3.4 ansible_user=ubuntu
```

```bash
make addon-hysteria2-server ARGS="-K"   # -K = prompt sudo password
```

### Несколько серверов (мульти-регион)

```ini
[hysteria2_server]
vps-nl ansible_host=1.2.3.4 ansible_user=root
vps-de ansible_host=5.6.7.8 ansible_user=root
```

---

## Что делать с URL после деплоя

Ansible выведет в конце:

```
vault_hysteria2_url: "hysteria2://mypassword@1.2.3.4:443?insecure=1&obfs=salamander&obfs-password=secret#MyVPS"
```

**Вариант 1 — вставить в vault для Prowlarr:**
```yaml
# group_vars/all/vault.yml
vault_hysteria2_url: "hysteria2://mypassword@1.2.3.4:443?insecure=1#MyVPS"
```
Затем: `make addon-mediaserver`

**Вариант 2 — вставить в Shadowrocket / NekoBox / Hiddify:**
Скопируй строку `hysteria2://...` и добавь как новый профиль в клиент.

---

## Управление сервисом

```bash
# Статус
ssh root@1.2.3.4 systemctl status hysteria2

# Логи в реальном времени
ssh root@1.2.3.4 journalctl -u hysteria2 -f

# Перезапуск после изменения конфига
ssh root@1.2.3.4 systemctl restart hysteria2

# Обновить до последней версии
make addon-hysteria2-server
```

## Обновление

```bash
# Скачает последнюю версию и перезапустит сервис
make addon-hysteria2-server
```

Для фиксации версии:
```yaml
hysteria2_server_version: "app/v2.5.1"
```
## Официальные ресурсы

- Официальный сайт: [https://hysteria.network/](https://hysteria.network/)
- Официальная документация: [https://v2.hysteria.network/docs/getting-started/Installation/](https://v2.hysteria.network/docs/getting-started/Installation/)
- Версии Helm chart / ПО: [https://github.com/apernet/hysteria/releases](https://github.com/apernet/hysteria/releases)