Hysteria2 Ansible — ветка main

Ветка: main
Режим: masquerade — маскировка под HTTPS-сайт nginx
Альтернатива: salamander — обфускация Salamander для агрессивного DPI

Ansible-роль для установки Hysteria 2 на Debian/Ubuntu VPS: Let's Encrypt, masquerade под nginx, несколько пользователей, экспорт URL/QR и HTML-каталог.

---

Выбор ветки: main или salamander

	main (эта ветка)	salamander
Маскировка	HTTPS-сайт nginx + Let's Encrypt	Salamander obfs — пакеты выглядят как шум
Порт 80/tcp	Нужен (ACME HTTP + masquerade)	Не нужен
ACME	type: http	type: tls (TLS-ALPN на 443)
Сайт-заглушка	/var/www/masq (nginx welcome)	Нет
Obfs-пароль	—	Обязателен (один на сервер)
URI клиента	hysteria2://user:pass@domain:443	+ obfs=salamander&obfs-password=...
Лучше когда	Нужен «легитимный» сайт в браузере	Агрессивный DPI, блокировка QUIC fingerprint

Когда выбирать main

• нужен нормальный HTTPS-сайт при открытии домена в браузере;
• достаточно маскировки под nginx;
• хотите минимум параметров в URI клиента;
• провайдер не «палит» Hysteria/QUIC внутри TLS.

Когда выбирать salamander

• masquerade из main блокируют или распознают по fingerprint;
• не нужен фейковый сайт;
• готовы хранить дополнительный obfs-пароль.

---

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

git clone https://git.antropoff.ru/DevOpsTools/hysteria2.git
cd hysteria2
git checkout main

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

make vault-encrypt
make ping
make install    # → output/index.html откроется в браузере

---

Makefile

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

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'
make update EXTRA_VARS='hysteria2_wait_for_acme=false'

---

Inventory

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-ключ

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

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

---

Как работает masquerade в этом проекте

Сервер (/etc/hysteria/config.yaml)

listen: 0.0.0.0:443

acme:
  type: http
  domains:
    - vpn-de.example.com
  email: admin@example.com

auth:
  type: userpass
  userpass:
    my: "..."
    friend: "..."

masquerade:
  type: file
  file:
    dir: /var/www/masq
  listenHTTP: :80
  listenHTTPS: :443
  forceHTTPS: true

Сайт-заглушка

В /var/www/masq/index.html — официальная страница Welcome to nginx!
При открытии домена в браузере — валидный HTTPS-сайт с Let's Encrypt.

Клиент (генерируется автоматически)

server: vpn-de.example.com:443
auth: my:password

URI (пример)

hysteria2://my:password@vpn-de.example.com:443#my

Роль вызывает hysteria share — URI и QR формируются автоматически.

---

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

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

vault_hysteria2_user_passwords:
  vps-de:
    friend: "Aingae0Okit1eek4eeZahFohVei4akee"

Подключается через group_vars/hysteria2_servers/vars.yml:

2. Per-host в inventory:

hysteria2_user_passwords:
  friend: "custom-password"

3. Автогенерация — Ansible password lookup (длина hysteria2_password_length), если пароль не задан.

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

---

Let's Encrypt — обновление сертификата

Да, Hysteria2 обновляет сертификат автоматически.

При блоке acme: в конфиге встроенный ACME-клиент Hysteria2 сам получает и продлевает сертификат Let's Encrypt (срок ~90 дней). Повторный make install или certbot для продления не нужны — процесс hysteria-server делает это сам.

Условия для авто-продления (ветка main):

• сервер запущен и доступен из интернета;
• домен указывает на IP VPS;
• порты 80/tcp и 443/tcp открыты (ACME HTTP challenge + masquerade);
• конфиг acme не удалён.

Проверка логов: journalctl -u hysteria-server -f

---

Firewall

По умолчанию открываются:

• 80/tcp — ACME HTTP + masquerade HTTP
• 443/tcp — HTTPS masquerade
• 443/udp — Hysteria2

---

Результат: папка 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-страницы показывают:

• пароль и URL каждого пользователя с кнопкой копирования;
• QR-коды;
• ссылки на файлы и страницы серверов.

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

Отключить: hysteria2_open_browser: false в group_vars/all.yml или EXTRA_VARS.

---

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_listen_port	group	Порт Hysteria2 (443)
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

---

Структура роли

roles/hysteria2/
├── tasks/
│   ├── install.yml       ← пакеты, hysteria, qrencode
│   ├── configure.yml     ← masquerade + ACME + firewall
│   ├── export.yml        ← URL, QR, HTML сервера
│   └── export_global.yml ← общий output/index.html
└── templates/
    ├── config.yaml.j2    ← acme http + masquerade file
    ├── client.yaml.j2
    ├── masq/index.html.j2
    └── export/           ← HTML-каталоги

---

Переключение между ветками

git fetch origin
git checkout main        # masquerade + nginx (эта ветка)
git checkout salamander  # Salamander obfs

Конфиги на уже установленном сервере не меняются при переключении ветки в git.
Чтобы применить другой режим на VPS:

git checkout salamander   # или main
make install              # перекатит конфиг сервера
# или
make update

Переключение режима меняет /etc/hysteria/config.yaml на сервере. Клиентские URI/QR нужно перевыпустить (make export или make update).