From 6630fb0343ed2114a6c9f8930c7750277a6a04b1 Mon Sep 17 00:00:00 2001 From: Sergey Antropoff Date: Thu, 23 Jul 2026 10:30:16 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B2=D0=BE=D1=81=D1=81=D1=82=D0=B0?= =?UTF-8?q?=D0=BD=D0=BE=D0=B2=D0=B8=D1=82=D1=8C=20README=20salamander=20?= =?UTF-8?q?=D0=B8=20=D0=BF=D1=83=D0=BD=D0=BA=D1=82=20=D0=BF=D1=80=D0=BE=20?= =?UTF-8?q?=D1=81=D0=BA=D0=B0=D1=87=D0=B8=D0=B2=D0=B0=D0=BD=D0=B8=D0=B5=20?= =?UTF-8?q?=D1=84=D0=B0=D0=B9=D0=BB=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 205 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 114 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 48932f3..b741a11 100644 --- a/README.md +++ b/README.md @@ -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-info.yml`. При `make update` / `make export`: -- **существующие** пользователи сохраняют пароли из `server-info.yml` (и URL/QR, если домен/порт не менялись); +- **существующие** пользователи сохраняют пароли из `server-info.yml` (и URL/QR, если домен/порт/obfs не менялись); - **новые** получают автогенерацию и полный экспорт; - **удалённые** из inventory убираются из конфига Hysteria2 и из `output//`. -Принудительно перевыпустить 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-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-info.yml`). -Новому пользователю генерируется пароль и создаются URL/QR. -Удалённый пользователь пропадает из `/etc/hysteria/config.yaml` и из папки `output//`. +Пароли и obfs существующих клиентов **не меняются** (из `server-info.yml`). +Новому пользователю генерируется пароль и создаются URL/QR с параметрами Salamander. +Удалённый пользователь пропадает из конфига и из `output//`. --- @@ -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