K3S/addons/hysteria2-server/README.md

Hysteria2 Server

Устанавливает Hysteria2 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

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

2. Vault секреты

make vault-edit

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

3. Деплой

С SSH-ключом (рекомендуется):

make addon-hysteria2-server

С SSH-паролем (ввод в терминале):

make addon-hysteria2-server ARGS="-k"

С SSH-паролем + sudo-паролем:

make addon-hysteria2-server ARGS="-k -K"

На конкретный хост (без inventory):

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

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

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

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

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 файлы

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 блокируется провайдером:

hysteria2_server_obfs_enabled: true

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

---

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

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

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

---

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

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

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

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

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

Пароль

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

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

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

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

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

---

Примеры inventory

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

[hysteria2_server]
myvps ansible_host=1.2.3.4 ansible_user=root

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

[hysteria2_server]
myvps ansible_host=1.2.3.4 ansible_user=ubuntu

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

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

[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:

# 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://... и добавь как новый профиль в клиент.

---

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

# Статус
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

Обновление

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

Для фиксации версии:

hysteria2_server_version: "app/v2.5.1"

Официальные ресурсы

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