DevOpsTools/hysteria2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add Salamander obfs branch: replace masquerade with packet obfuscation.

Browse Source 
- ACME TLS challenge on 443 (no port 80 or nginx decoy)
- Auto-generate and persist obfs password per server
- Update client export, HTML catalog, and vault examples
- Document Salamander vs main and ACME auto-renewal in README

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Sergey Antropoff
2026-07-01 02:17:22 +03:00
parent 47e440341a
commit 8a7a4c0889
19 changed files with 367 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+205 -103
View File
@@ -1,48 +1,64 @@
# Ansible-роль: Hysteria2 Server
# Hysteria2 Ansible — ветка **Salamander**
Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS: ACME-сертификат, masquerade под nginx, несколько пользователей, экспорт URL/QR и HTML-каталог.
> **Ветка:** `salamander`
> **Режим:** обфускация **Salamander** (без masquerade-сайта nginx)
> **Основная ветка `main`:** masquerade под HTTPS-сайт — см. другую ветку
Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS с **Salamander obfs** — запутывание пакетов для обхода DPI, когда masquerade под «обычный сайт» недостаточен.
---
## Чем Salamander отличается от `main`
| | **`main` (masquerade)** | **`salamander` (эта ветка)** |
|---|---|---|
| Маскировка | HTTPS-сайт nginx + Let's Encrypt | **Salamander obfs** — пакеты выглядят как шум |
| Порт 80/tcp | Нужен (ACME HTTP + masquerade) | **Не нужен** |
| ACME | `type: http` | `type: tls` (TLS-ALPN на 443) |
| Сайт-заглушка | `/var/www/masq` | **Нет** |
| Obfs-пароль | — | **Обязателен** (один на сервер) |
| URI клиента | `hysteria2://user:pass@domain:443` | + `obfs=salamander&obfs-password=...` |
| Лучше когда | Нужен «легитимный» сайт в браузере | Агрессивный DPI, блокировка QUIC fingerprint |
---
## Быстрый старт
```bash
cd ~/Разработка/hysteria2
git clone https://git.antropoff.ru/DevOpsTools/hysteria2.git
cd hysteria2
git checkout salamander
make init # inventory, group_vars, vault, .vault_pass
# отредактировать:
# inventory/hosts.yml
# group_vars/all.yml
# group_vars/hysteria2_servers/vault.yml
make init
# отредактировать inventory/hosts.yml, group_vars/all.yml, vault
make vault-encrypt # зашифровать пароли VPS
make ping # проверить SSH
make install # установка → output/ → браузер откроется сам
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` | Установка + экспорт + `output/index.html` + открытие в браузере |
| `make install` | Установка Salamander + экспорт URL/QR/HTML |
| `make update` | Обновить бинарник, конфиг, перевыпустить экспорт |
| `make export` | Только экспорт URL/QR/HTML |
| `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' # без авто-открытия браузера
make update EXTRA_VARS='hysteria2_wait_for_acme=false'
make install EXTRA_VARS='hysteria2_open_browser=false'
```
---
## Inventory
```yaml
@@ -55,132 +71,218 @@ all:
ansible_port: 2222 # SSH-порт (если не 22)
ansible_user: root
ansible_password: "{{ vault_ssh_passwords['vps-de'] }}"
hysteria2_domain: vpn-de.example.com
hysteria2_domain: vpn-de.example.com # для TLS/SNI и ACME
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-ключ |
### SSH (VPS)
```yaml
# group_vars/hysteria2_servers/vault.yml
vault_ssh_passwords:
vps-de: "root-password-1"
vps-nl: "root-password-2"
vps-de: "root-password"
```
Ключи в `vault_ssh_passwords` совпадают с **именами хостов** в inventory.
Пароли VPN и Salamander obfs тоже можно хранить в vault — см. ниже.
## Пароли VPN-пользователей
---
1. **Vault** (рекомендуется):
## Как работает Salamander в этом проекте
### Сервер (`/etc/hysteria/config.yaml`)
```yaml
vault_hysteria2_user_passwords:
vps-de:
friend: "Aingae0Okit1eek4eeZahFohVei4akee"
listen: 0.0.0.0:443
acme:
type: tls # сертификат без порта 80
domains:
- vpn-de.example.com
email: admin@example.com
auth:
type: userpass
userpass:
my: "..."
friend: "..."
obfs:
type: salamander
salamander:
password: "общий_obfs_пароль_сервера"
```
2. **Per-host в inventory**:
### Клиент (генерируется автоматически)
```yaml
hysteria2_user_passwords:
friend: "custom-password"
server: vpn-de.example.com:443
auth: my:password
obfs:
type: salamander
salamander:
password: общий_obfs_пароль_сервера
```
3. **Автогенерация** — `pwgen -s 40`, если пароль не задан.
### URI (пример)
При `make update` пароли подтягиваются из `output/<server>/server-info.yml`, если не указаны в vault/inventory.
```
hysteria2://my:password@vpn-de.example.com:443?obfs=salamander&obfs-password=OBFS_PASS#my
```
Роль вызывает `hysteria share` — URI и QR уже содержат параметры Salamander.
---
## Пароли
### VPN-пользователи (`userpass`)
1. **Vault:** `vault_hysteria2_user_passwords`
2. **Inventory:** `hysteria2_user_passwords`
3. **Авто:** `pwgen -s 40`
### Salamander obfs (один на сервер)
1. **Vault (рекомендуется):**
```yaml
vault_hysteria2_obfs_passwords:
vps-de: "cry_me_a_r1ver_salamander_obfs"
```
Подключается через `group_vars/hysteria2_servers/vars.yml`:
```yaml
hysteria2_obfs_password: "{{ (vault_hysteria2_obfs_passwords | default({}))[inventory_hostname] | default('') }}"
```
2. **Авто:** `pwgen -s 32` при первой установке
3. **При update:** загружается из `output/<server>/server-info.yml`
> **Важно:** obfs-пароль на сервере и клиенте должен **совпадать**. При `make update` без vault пароль сохраняется из предыдущего экспорта.
---
## Let's Encrypt — обновление сертификата
**Да, Hysteria2 обновляет сертификат автоматически.**
При `acme:` в конфиге встроенный ACME-клиент Hysteria2 сам получает и **продлевает** сертификат Let's Encrypt (срок ~90 дней). Перезапуск ansible для продления **не нужен** — процесс `hysteria-server` делает это сам (подтверждено maintainer проекта).
**Условия для авто-продления:**
- Сервер **запущен** и доступен из интернета
- Домен по-прежнему указывает на IP VPS
- Порт **443** открыт (для `acme type: tls` — TLS-ALPN challenge)
- Конфиг `acme` не удалён
Проверка логов: `journalctl -u hysteria-server -f`
---
## Firewall
Открываются только порты Hysteria2 (по умолчанию **443/tcp** и **443/udp**).
**Порт 80 не используется** — в отличие от ветки `main`.
---
## Результат: папка `output/`
```
output/
├── index.html ← общий каталог всех серверов (открывается в браузере)
├── index.html ← все серверы (открывается в браузере)
├── vps-de/
│ ├── index.html ← страница сервера
│ ├── my.url
│ ├── my.png ← QR PNG
│ ├── my.qr.txt ← QR ASCII
│ ├── index.html ← страница сервера + obfs-пароль
│ ├── my.url ← URI с obfs=salamander
│ ├── my.png ← QR
│ ├── my.txt
│ └── server-info.yml
│ └── server-info.yml ← mode, obfs_password, users
└── vps-nl/
└── ...
```
### HTML-страницы
HTML-страницы показывают:
**`output/index.html`** — общий каталог:
- все серверы и пользователи на одной странице
- навигация по серверам
- поля ссылки/пароля с кнопкой копирования
- режим **Salamander**
- **obfs-password** с кнопкой копирования
- пароль и URL каждого пользователя
- 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 |
| `hysteria2_mode` | defaults | `salamander` (информативно) |
| `hysteria2_domain` | host | Домен для TLS/SNI/ACME |
| `hysteria2_users` | host | VPN-пользователи |
| `hysteria2_acme_email` | group | Email Let's Encrypt |
| `hysteria2_obfs_password` | host/vault | Пароль Salamander (или авто) |
| `hysteria2_obfs_password_length` | group | Длина автопароля obfs (32) |
| `hysteria2_listen_port` | group | Порт (443) |
| `hysteria2_open_browser` | group | Открыть `output/index.html` |
| `vault_hysteria2_obfs_passwords` | vault | obfs-пароли по серверам |
---
## Когда выбирать эту ветку
**Используйте `salamander`, если:**
- masquerade из `main` блокируют или «палят» по fingerprint
- не нужен фейковый сайт в браузере
- готовы хранить **дополнительный** obfs-пароль
**Используйте `main`, если:**
- нужен «нормальный» HTTPS-сайт при проверке домена
- достаточно маскировки под nginx
- хотите минимум параметров в URI
---
## Безопасность
- `output/` содержит пароли и URL — в `.gitignore`
- `inventory/hosts.yml`, `vault.yml`, `.vault_pass` — не коммитить
- После `make init` выполните `make vault-encrypt`
- `output/` содержит пароли, obfs-ключи и URL — **не коммитить**
- `make vault-encrypt` обязателен после `make init`
- Salamander **не делает** вас невидимым: IP VPS и постоянный UDP-поток всё ещё можно анализировать
---
## Требования
- Ansible 2.14+
- Debian/Ubuntu VPS с sudo
- Домен с A-записью на IP сервера
- Для авто-открытия браузера: macOS или Linux с `xdg-open`
- Debian/Ubuntu VPS
- Домен с A-записью на IP (для ACME TLS)
- Клиент Hysteria2 с поддержкой Salamander (Shadowrocket, NekoBox, Hiddify и др.)
---
## Структура роли
```
roles/hysteria2/
├── tasks/
│ ├── obfs.yml ← генерация/загрузка obfs-пароля
│ ├── configure.yml ← без masquerade, только Salamander
│ └── export_global.yml ← общий output/index.html
└── templates/
├── config.yaml.j2 ← acme tls + obfs salamander
└── client.yaml.j2 ← клиент с obfs
```
---
## Переключение между ветками
```bash
git checkout main # masquerade + nginx
git checkout salamander # Salamander obfs
```
Конфиги на **уже установленном** сервере **не меняются** при переключении ветки в git — нужен `make install` или `make update` на целевой ветке (это **перекатит** конфиг сервера).