docs: восстановить README salamander и пункт про скачивание файлов

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-23 10:30:16 +03:00
parent 2d844e603f
commit 69ac036c2a
1 changed files with 114 additions and 91 deletions
@@ -1,10 +1,10 @@
-# Hysteria2 Ansible — ветка **main**
+# Hysteria2 Ansible — ветка **Salamander**

-> **Ветка:** `main`  
-> **Режим:** **masquerade** — маскировка под HTTPS-сайт nginx  
-> **Альтернатива:** [`salamander`](https://git.antropoff.ru/DevOpsTools/hysteria2/src/branch/salamander) — обфускация Salamander для агрессивного DPI
+> **Ветка:** `salamander`  
+> **Режим:** **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: Let's Encrypt, masquerade под nginx, несколько пользователей, экспорт URL/QR и HTML-каталог.
+Ansible-роль для установки [Hysteria 2](https://v2.hysteria.network/) на Debian/Ubuntu VPS с **Salamander obfs** — когда masquerade под «обычный сайт» недостаточен.

 ---

@@ -24,7 +24,7 @@ Ansible-роль для установки [Hysteria 2](https://v2.hysteria.netw

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

-| | **`main` (эта ветка)** | **`salamander`** |
+| | **`main`** | **`salamander` (эта ветка)** |
 |---|---|---|
 | Маскировка | HTTPS-сайт nginx + Let's Encrypt | **Salamander obfs** — пакеты выглядят как шум |
 | Порт 80/tcp | **Нужен** (ACME HTTP + masquerade) | **Не нужен** |
@@ -34,19 +34,18 @@ Ansible-роль для установки [Hysteria 2](https://v2.hysteria.netw
 | 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-пароль.

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

 ## Быстрый старт
@@ -54,7 +53,7 @@ Ansible-роль для установки [Hysteria 2](https://v2.hysteria.netw
 ```bash
 git clone https://git.antropoff.ru/DevOpsTools/hysteria2.git
 cd hysteria2
-git checkout main
+git checkout salamander

 # macOS: установить Ansible (если ещё нет)
 brew install ansible
@@ -84,7 +83,7 @@ make install    # → output/index.html откроется в браузере
 | `make check` | Проверить синтаксис playbook |
 | `make ping` | Проверить SSH к VPS |
 | `make status` | Краткий статус: active / not installed, uptime, PID, RAM |
-| `make install` | Установка masquerade + экспорт URL/QR/HTML |
+| `make install` | Установка Salamander + экспорт URL/QR/HTML |
 | `make update` | Обновить бинарник и конфиг; экспорт только для новых/изменённых пользователей |
 | `make export` | Только экспорт (URL, QR, HTML) без изменений на сервере |
 | `make index` | Пересобрать HTML всех серверов + общий `output/index.html` и открыть в браузере |
@@ -123,7 +122,7 @@ 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
@@ -159,7 +158,7 @@ vault_ssh_passwords:

 ---

-## Как работает masquerade в этом проекте
+## Как работает Salamander в этом проекте

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

@@ -167,7 +166,7 @@ vault_ssh_passwords:
 listen: 0.0.0.0:443

 acme:
-  type: http
+  type: tls                    # сертификат без порта 80
  domains:
    - vpn-de.example.com
  email: admin@example.com
@@ -178,38 +177,36 @@ auth:
    my: "..."
    friend: "..."

-masquerade:
-  type: file
-  file:
-    dir: /var/www/masq
-  listenHTTP: :80
-  listenHTTPS: :443
-  forceHTTPS: true
+obfs:
+  type: salamander
+  salamander:
+    password: "общий_obfs_пароль_сервера"
 ```

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

 ```yaml
 server: vpn-de.example.com:443
 auth: my:password
+obfs:
+  type: salamander
+  salamander:
+    password: общий_obfs_пароль_сервера
 ```

 ### URI (пример)

 ```
-hysteria2://my:password@vpn-de.example.com:443#my
+hysteria2://my:password@vpn-de.example.com:443?obfs=salamander&obfs-password=OBFS_PASS#my
 ```

-Роль вызывает `hysteria share` — URI и QR формируются автоматически.
+Роль вызывает `hysteria share` — URI и QR уже содержат параметры Salamander.

 ---

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

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

@@ -235,11 +232,31 @@ hysteria2_user_passwords:
 3. **Автогенерация** — Ansible `password` lookup, если пароль не задан ни в inventory/vault, ни в `output/<server>/server-info.yml`.

 При `make update` / `make export`:
- **существующие** пользователи сохраняют пароли из `server-info.yml` (и URL/QR, если домен/порт не менялись);
+- **существующие** пользователи сохраняют пароли из `server-info.yml` (и URL/QR, если домен/порт/obfs не менялись);
 - **новые** получают автогенерацию и полный экспорт;
 - **удалённые** из inventory убираются из конфига Hysteria2 и из `output/<server>/`.

-Принудительно перевыпустить URL/QR для всех: `hysteria2_force_export: true` (в `group_vars/all.yml` или `EXTRA_VARS`).
+### 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[inventory_hostname] | default('') }}"
+```
+
+2. **Авто:** Ansible `password` lookup (`hysteria2_obfs_password_length`) при первой установке  
+3. **При update/export:** загружается из `output/<server>/server-info.yml` (как VPN-пароли)
+
+> **Важно:** obfs-пароль на сервере и клиенте должен **совпадать**. При `make update` без vault пароль сохраняется из предыдущего экспорта.
+
+Принудительно перевыпустить URL/QR для всех VPN-пользователей: `hysteria2_force_export: true`.

 ```bash
 make install EXTRA_VARS='hysteria2_force_export=true'
@@ -262,12 +279,12 @@ make install LIMIT=новый-сервер

 ### Добавить / удалить пользователя

-1. Отредактируйте `hysteria2_users` в `inventory/hosts.yml` (добавьте имя или уберите).
+1. Отредактируйте `hysteria2_users` в `inventory/hosts.yml`.
 2. Запустите `make update LIMIT=<хост>`.

-Пароли существующих клиентов **не меняются** (берутся из `output/<server>/server-info.yml`).  
-Новому пользователю генерируется пароль и создаются URL/QR.  
-Удалённый пользователь пропадает из `/etc/hysteria/config.yaml` и из папки `output/<server>/`.
+Пароли и obfs существующих клиентов **не меняются** (из `server-info.yml`).  
+Новому пользователю генерируется пароль и создаются URL/QR с параметрами Salamander.  
+Удалённый пользователь пропадает из конфига и из `output/<server>/`.

 ---

@@ -275,12 +292,12 @@ make install LIMIT=новый-сервер

 Официальный скрипт `install_server.sh` хранится в `roles/hysteria2/files/`.

-Перед `make install` / `make update` на **control node** (ваш Mac):
+Перед `make install` / `make update` на **control node**:

 1. Скачивается копия с https://get.hy2.sh/
 2. Сравнивается SHA256 с локальным файлом в роли
 3. При отличии — локальная копия обновляется
-4. Скрипт копируется на VPS и запускается оттуда (без `curl | bash` на сервере)
+4. Скрипт копируется на VPS и запускается оттуда

 ---

@@ -289,11 +306,11 @@ make install LIMIT=новый-сервер
 | Компонент | Поведение |
 |---|---|
 | Бинарник `hysteria` | Обновляется (`install_server.sh --force`) |
-| `/etc/hysteria/config.yaml` | Перекатывается под текущий inventory |
-| Пароли VPN | Сохраняются для существующих пользователей |
+| `/etc/hysteria/config.yaml` | Перекатывается (auth + obfs) |
+| Пароли VPN / obfs | Сохраняются для существующей конфигурации |
 | URL / QR | Только для новых, изменённых или при `hysteria2_force_export=true` |
-| `apt upgrade` | **Не** выполняется (отключено в Makefile) |
-| Ожидание ACME | **Не** выполняется (`hysteria2_wait_for_acme=false`) |
+| `apt upgrade` | **Не** выполняется |
+| Ожидание ACME | **Не** выполняется |

 ---

@@ -304,10 +321,9 @@ make install LIMIT=новый-сервер
 - бинарник `/usr/local/bin/hysteria` и unit-файлы systemd;
 - `/etc/hysteria/` (конфиг и ACME);
 - `/var/lib/hysteria` и пользователь `hysteria`;
- `/var/www/masq` (сайт-заглушка, ветка **main**);
 - symlink'и `multi-user.target.wants/hysteria-server*`;
 - временные `/tmp/hysteria-client-*.yaml`;
- правила ufw, добавленные при install;
+- правила ufw: `443/tcp`, `443/udp` (порт из `hysteria2_listen_port`);
 - пакеты `curl`, `micro`, `qrencode`.

 На **control node**:
@@ -324,11 +340,11 @@ make install LIMIT=новый-сервер

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

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

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

 Проверка логов: `journalctl -u hysteria-server -f`
@@ -337,11 +353,12 @@ make install LIMIT=новый-сервер

 ## Firewall

-По умолчанию открываются:
+По умолчанию открываются только порты Hysteria2:

- **80/tcp** — ACME HTTP + masquerade HTTP
- **443/tcp** — HTTPS masquerade
- **443/udp** — Hysteria2
+- **443/tcp**
+- **443/udp**
+
+**Порт 80 не используется** — в отличие от ветки `main`.

 ---

@@ -351,19 +368,20 @@ make install LIMIT=новый-сервер
 output/
 ├── index.html                 ← все серверы (открывается в браузере)
 ├── vps-de/
-│   ├── index.html             ← страница сервера
-│   ├── my.url
+│   ├── index.html             ← страница сервера + obfs-пароль
+│   ├── my.url                 ← URI с obfs=salamander
 │   ├── my.png                 ← QR PNG
 │   ├── my.qr.txt             ← QR ASCII
 │   ├── my.txt
-│   └── server-info.yml
+│   └── server-info.yml        ← mode, obfs_password, users
 └── vps-nl/
    └── ...
 ```

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

- пароль и URL каждого пользователя с **кнопкой копирования**;
+- режим **Salamander** и **obfs-password** с кнопкой копирования;
+- пароль и URL каждого пользователя;
 - QR-коды;
 - ссылки на файлы и страницы серверов.

@@ -391,33 +409,37 @@ 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 (`vars.yml` + vault) |
-| `hysteria2_password_length` | group | Длина автогенерируемого пароля (40) |
-| `hysteria2_force_export` | group | Перегенерировать URL/QR для всех (`false` по умолчанию) |
+| `hysteria2_mode` | defaults | `salamander` (информативно) |
+| `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_password_length` | group | Длина автопароля VPN (40) |
+| `hysteria2_force_export` | group | Перегенерировать URL/QR для всех (`false`) |
+| `hysteria2_obfs_password` | host/vault | Пароль Salamander (или авто) |
+| `hysteria2_obfs_password_length` | group | Длина автопароля obfs (32) |
 | `hysteria2_output_dir` | group | Папка экспорта (`./output`) |
-| `hysteria2_output_name` | host | Подпапка экспорта (`inventory_hostname`) |
-| `hysteria2_listen_port` | group | Порт Hysteria2 (443) |
-| `hysteria2_upgrade_system` | group | `apt upgrade` перед install (`true`) |
-| `hysteria2_configure_firewall` | group | Открыть порты в ufw (`true`) |
+| `hysteria2_listen_port` | group | Порт (443) |
+| `hysteria2_upgrade_system` | group | `apt upgrade` перед install |
+| `hysteria2_configure_firewall` | group | Открыть порты в ufw |
 | `hysteria2_generate_qr_png` | group | PNG QR через `qrencode` |
-| `hysteria2_wait_for_acme` | group | Пауза при первом ACME (install) |
+| `hysteria2_wait_for_acme` | group | Пауза при первом ACME |
 | `hysteria2_open_browser` | group | Открыть `output/index.html` после экспорта |
 | `hysteria2_uninstall_rebuild_global_index` | group | Пересобрать `output/index.html` после uninstall (`true`) |
-| `vault_ssh_passwords` | vault | SSH-пароли root по имени хоста |
+| `vault_ssh_passwords` | vault | SSH-пароли root |
 | `vault_hysteria2_user_passwords` | vault | VPN-пароли по серверам |
+| `vault_hysteria2_obfs_passwords` | vault | obfs-пароли по серверам |

-Полный список defaults: `roles/hysteria2/defaults/main.yml`, `defaults/uninstall.yml`.
+Полный список: `roles/hysteria2/defaults/main.yml`, `defaults/uninstall.yml`.

 ---

 ## Безопасность

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

 ---

@@ -425,8 +447,9 @@ ASCII QR — `hysteria share --qr` → `user.qr.txt`.

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

 ---
@@ -436,29 +459,29 @@ ASCII QR — `hysteria share --qr` → `user.qr.txt`.
 ```
 roles/hysteria2/
 ├── defaults/
-│   ├── main.yml              ← основные переменные
-│   └── uninstall.yml         ← переменные удаления
+│   ├── main.yml
+│   └── uninstall.yml
 ├── files/
-│   └── install_server.sh     ← официальный скрипт (синхронизация с get.hy2.sh)
+│   └── install_server.sh
 ├── tasks/
-│   ├── main.yml              ← порядок задач и теги
+│   ├── main.yml
 │   ├── validate.yml
-│   ├── users.yml             ← пароли (inventory / vault / server-info.yml)
+│   ├── users.yml
+│   ├── obfs.yml              ← пароль Salamander obfs
 │   ├── sync_install_script.yml
-│   ├── install.yml           ← пакеты, бинарник
-│   ├── configure.yml         ← masquerade + ACME + ufw
-│   ├── update.yml            ← обновление бинарника
-│   ├── export_prepare.yml    ← инкрементальный экспорт
-│   ├── export.yml            ← URL, QR, HTML сервера
-│   ├── export_global.yml     ← общий output/index.html
+│   ├── install.yml
+│   ├── configure.yml         ← Salamander, без masquerade
+│   ├── update.yml
+│   ├── export_prepare.yml
+│   ├── export.yml
+│   ├── export_global.yml
 │   ├── share_user.yml
 │   ├── reuse_export_user.yml
 │   └── uninstall.yml
 └── templates/
-    ├── config.yaml.j2        ← acme http + masquerade file
+    ├── config.yaml.j2        ← acme tls + obfs salamander
    ├── client.yaml.j2
-    ├── masq/index.html.j2
-    └── export/               ← HTML-каталоги
+    └── export/
 ```

 ---
@@ -467,15 +490,15 @@ roles/hysteria2/

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

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

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