Align README with main branch: branches comparison, ACME renewal, switching.

Unified documentation structure across main and salamander branches. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-01 02:22:28 +03:00
parent b1be74d21f
commit f38b974d28
1 changed files with 130 additions and 51 deletions
@@ -1,25 +1,37 @@
 # Hysteria2 Ansible — ветка **Salamander**

 > **Ветка:** `salamander`  
-> **Режим:** обфускация **Salamander** (без masquerade-сайта nginx)  
-> **Основная ветка `main`:** masquerade под HTTPS-сайт — см. другую ветку
+> **Режим:** **Salamander obfs** — запутывание пакетов для обхода DPI  
+> **Основная ветка:** [`main`](https://git.antropoff.ru/DevOpsTools/hysteria2/src/branch/main) — masquerade под HTTPS-сайт nginx

-Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS с **Salamander obfs** — запутывание пакетов для обхода DPI, когда masquerade под «обычный сайт» недостаточен.
+Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS с **Salamander obfs** — когда masquerade под «обычный сайт» недостаточен.

 ---

-## Чем Salamander отличается от `main`
+## Выбор ветки: `main` или `salamander`

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

+### Когда выбирать `salamander`
+
+- masquerade из `main` **блокируют** или распознают по fingerprint;
+- не нужен фейковый сайт в браузере;
+- готовы хранить **дополнительный** obfs-пароль.
+
+### Когда выбирать `main`
+
+- нужен **нормальный HTTPS-сайт** при открытии домена;
+- достаточно маскировки под nginx;
+- хотите **минимум параметров** в URI клиента.
+
 ---

 ## Быстрый старт
@@ -43,18 +55,24 @@ make install    # → output/index.html откроется в браузере

 | Команда | Описание |
 |---|---|
+| `make help` | Справка |
 | `make init` | Создать конфиги из `.example` |
 | `make ping` | Проверить SSH к VPS |
+| `make status` | `systemctl status hysteria-server` |
 | `make install` | Установка Salamander + экспорт URL/QR/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 EXTRA_VARS='hysteria2_wait_for_acme=false'
+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'
 ```

 ---
@@ -75,17 +93,35 @@ all:
          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"
+  vps-de: "root-password-1"
+  vps-nl: "root-password-2"
 ```

-Пароли VPN и Salamander obfs тоже можно хранить в vault — см. ниже.
+Ключи в `vault_ssh_passwords` совпадают с **именами хостов** в inventory.

 ---

@@ -139,9 +175,29 @@ hysteria2://my:password@vpn-de.example.com:443?obfs=salamander&obfs-password=OBF

 ### VPN-пользователи (`userpass`)

-1. **Vault:** `vault_hysteria2_user_passwords`
-2. **Inventory:** `hysteria2_user_passwords`
-3. **Авто:** `pwgen -s 40`
+1. **Vault (рекомендуется):**
+
+```yaml
+vault_hysteria2_user_passwords:
+  vps-de:
+    friend: "Aingae0Okit1eek4eeZahFohVei4akee"
+```
+
+Подключается через `group_vars/hysteria2_servers/vars.yml`:
+
+```yaml
+```
+
+2. **Per-host в inventory:**
+
+```yaml
+hysteria2_user_passwords:
+  friend: "custom-password"
+```
+
+3. **Автогенерация** — `pwgen -s 40`, если пароль не задан.
+
+При `make update` пароли подтягиваются из `output/<server>/server-info.yml`, если не указаны в vault/inventory.

 ### Salamander obfs (один на сервер)

@@ -168,14 +224,14 @@ vault_hysteria2_obfs_passwords:

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

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

-**Условия для авто-продления:**
+**Условия для авто-продления (ветка `salamander`):**

- Сервер **запущен** и доступен из интернета
- Домен по-прежнему указывает на IP VPS
- Порт **443** открыт (для `acme type: tls` — TLS-ALPN challenge)
- Конфиг `acme` не удалён
+- сервер **запущен** и доступен из интернета;
+- домен указывает на IP VPS;
+- порт **443/tcp** открыт (ACME TLS-ALPN challenge);
+- конфиг `acme` не удалён.

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

@@ -183,7 +239,10 @@ vault_hysteria2_obfs_passwords:

 ## Firewall

-Открываются только порты Hysteria2 (по умолчанию **443/tcp** и **443/udp**).
+По умолчанию открываются только порты Hysteria2:
+
+- **443/tcp**
+- **443/udp**

 **Порт 80 не используется** — в отличие от ветки `main`.

@@ -197,7 +256,8 @@ output/
 ├── vps-de/
 │   ├── index.html             ← страница сервера + obfs-пароль
 │   ├── my.url                 ← URI с obfs=salamander
-│   ├── my.png                 ← QR
+│   ├── my.png                 ← QR PNG
+│   ├── my.qr.txt             ← QR ASCII
 │   ├── my.txt
 │   └── server-info.yml        ← mode, obfs_password, users
 └── vps-nl/
@@ -206,10 +266,26 @@ output/

 HTML-страницы показывают:

- режим **Salamander**
- **obfs-password** с кнопкой копирования
- пароль и URL каждого пользователя
- QR-коды
+- режим **Salamander** и **obfs-password** с кнопкой копирования;
+- пароль и 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`.

 ---

@@ -221,44 +297,34 @@ HTML-страницы показывают:
 | `hysteria2_domain` | host | Домен для TLS/SNI/ACME |
 | `hysteria2_users` | host | VPN-пользователи |
 | `hysteria2_acme_email` | group | Email Let's Encrypt |
+| `hysteria2_user_passwords` | host/vault | Свои пароли VPN |
 | `hysteria2_obfs_password` | host/vault | Пароль Salamander (или авто) |
 | `hysteria2_obfs_password_length` | group | Длина автопароля obfs (32) |
+| `hysteria2_output_dir` | group | Папка экспорта (по умолчанию `./output`) |
 | `hysteria2_listen_port` | group | Порт (443) |
-| `hysteria2_open_browser` | group | Открыть `output/index.html` |
+| `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 |
 | `vault_hysteria2_obfs_passwords` | vault | obfs-пароли по серверам |

 ---

-## Когда выбирать эту ветку
-
-**Используйте `salamander`, если:**
-
- masquerade из `main` блокируют или «палят» по fingerprint
- не нужен фейковый сайт в браузере
- готовы хранить **дополнительный** obfs-пароль
-
-**Используйте `main`, если:**
-
- нужен «нормальный» HTTPS-сайт при проверке домена
- достаточно маскировки под nginx
- хотите минимум параметров в URI
-
---
-
 ## Безопасность

- `output/` содержит пароли, obfs-ключи и URL — **не коммитить**
- `make vault-encrypt` обязателен после `make init`
- Salamander **не делает** вас невидимым: IP VPS и постоянный UDP-поток всё ещё можно анализировать
+- `output/` содержит пароли, obfs-ключи и URL — **не коммитить** (в `.gitignore`)
+- `inventory/hosts.yml`, `vault.yml`, `.vault_pass` — не коммитить
+- После `make init` выполните `make vault-encrypt`
+- Salamander **не делает** вас невидимым: IP VPS и UDP-поток всё ещё можно анализировать

 ---

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

 - Ansible 2.14+
- Debian/Ubuntu VPS
+- Debian/Ubuntu VPS с sudo
 - Домен с A-записью на IP (для ACME TLS)
 - Клиент Hysteria2 с поддержкой Salamander (Shadowrocket, NekoBox, Hiddify и др.)
+- Для авто-открытия браузера: macOS или Linux с `xdg-open`

 ---

@@ -268,11 +334,13 @@ HTML-страницы показывают:
 roles/hysteria2/
 ├── tasks/
 │   ├── obfs.yml          ← генерация/загрузка obfs-пароля
-│   ├── configure.yml     ← без masquerade, только Salamander
+│   ├── configure.yml     ← Salamander, без masquerade
+│   ├── export.yml        ← URL, QR, HTML сервера
 │   └── export_global.yml ← общий output/index.html
 └── templates/
    ├── config.yaml.j2    ← acme tls + obfs salamander
-    └── client.yaml.j2    ← клиент с obfs
+    ├── client.yaml.j2    ← клиент с obfs
+    └── export/           ← HTML-каталоги
 ```

 ---
@@ -280,8 +348,19 @@ roles/hysteria2/
 ## Переключение между ветками

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

-Конфиги на **уже установленном** сервере **не меняются** при переключении ветки в git — нужен `make install` или `make update` на целевой ветке (это **перекатит** конфиг сервера).
+Конфиги на **уже установленном** сервере **не меняются** при переключении ветки в git.  
+Чтобы применить другой режим на VPS:
+
+```bash
+git checkout main         # или salamander
+make install              # перекатит конфиг сервера
+# или
+make update
+```
+
+> Переключение режима **меняет** `/etc/hysteria/config.yaml` на сервере. Клиентские URI/QR нужно **перевыпустить** (`make export` или `make update`).