From f5939c48fc0aba1f49849cb0ec6471474f2f8dc0 Mon Sep 17 00:00:00 2001 From: Sergey Antropoff Date: Wed, 1 Jul 2026 13:16:38 +0300 Subject: [PATCH] docs: update README for Salamander branch features Mirror main documentation: install script sync, incremental update/export, uninstall, vault wiring, Makefile and role structure. Co-authored-by: Cursor --- README.md | 138 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 116 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 172e2fa..72f3d6c 100644 --- a/README.md +++ b/README.md @@ -41,14 +41,23 @@ git clone https://git.antropoff.ru/DevOpsTools/hysteria2.git cd hysteria2 git checkout salamander +# macOS: установить Ansible (если ещё нет) +brew install ansible + make init -# отредактировать inventory/hosts.yml, group_vars/all.yml, vault +# отредактировать: +# inventory/hosts.yml +# group_vars/all.yml +# group_vars/hysteria2_servers/vault.yml +# group_vars/hysteria2_servers/vars.yml (проброс vault → роль) make vault-encrypt make ping make install # → output/index.html откроется в браузере ``` +После `make init` создаются локальные файлы из `.example` (не коммитятся). Пароль vault хранится в `.vault_pass`. + --- ## Makefile @@ -56,15 +65,18 @@ make install # → output/index.html откроется в браузере | Команда | Описание | |---|---| | `make help` | Справка | -| `make init` | Создать конфиги из `.example` | +| `make init` | Создать конфиги из `.example` и `.vault_pass` | +| `make check` | Проверить синтаксис playbook | | `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 + `output//` + пересборка `output/index.html` | -| `make vault-encrypt` | Зашифровать vault | -| `make vault-edit` | Редактировать vault | +| `make update` | Обновить бинарник и конфиг; экспорт только для новых/изменённых пользователей | +| `make export` | Только экспорт (URL, QR, HTML) без изменений на сервере | +| `make uninstall` | Полное удаление с VPS + `output//` + пересборка `output/index.html` | +| `make vault-init` | Создать `.vault_pass`, включить `vault_password_file` в `ansible.cfg` | +| `make vault-encrypt` | Зашифровать `vault.yml` | +| `make vault-edit` | Редактировать vault (редактор **nano**, см. `EDITOR` в Makefile) | +| `make vault-view` | Показать расшифрованный vault | ```bash make install LIMIT=vps-de @@ -72,10 +84,13 @@ make update LIMIT=vps-nl make export make uninstall LIMIT=vps-de make uninstall LIMIT=vps-de EXTRA_VARS='hysteria2_uninstall_remove_local_output=false' +make update EXTRA_VARS='hysteria2_force_export=true' # перевыпустить URL/QR для всех make install EXTRA_VARS='hysteria2_open_browser=false' make update EXTRA_VARS='hysteria2_wait_for_acme=false' ``` +`LIMIT` — имя хоста из `inventory/hosts.yml` (например `vps-de`). + --- ## Inventory @@ -187,6 +202,7 @@ vault_hysteria2_user_passwords: Подключается через `group_vars/hysteria2_servers/vars.yml`: ```yaml +hysteria2_user_passwords: "{{ vault_hysteria2_user_passwords[inventory_hostname] | default({}) }}" ``` 2. **Per-host в inventory:** @@ -215,6 +231,7 @@ vault_hysteria2_obfs_passwords: Подключается через `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`) при первой установке @@ -222,6 +239,59 @@ vault_hysteria2_obfs_passwords: > **Важно:** obfs-пароль на сервере и клиенте должен **совпадать**. При `make update` без vault пароль сохраняется из предыдущего экспорта. +Принудительно перевыпустить URL/QR для всех VPN-пользователей: `hysteria2_force_export: true`. + +### Добавить / удалить пользователя + +1. Отредактируйте `hysteria2_users` в `inventory/hosts.yml`. +2. Запустите `make update LIMIT=<хост>`. + +Пароли и obfs существующих клиентов **не меняются** (из `server-info.yml`). +Новому пользователю генерируется пароль и создаются URL/QR с параметрами Salamander. +Удалённый пользователь пропадает из конфига и из `output//`. + +--- + +## Установка бинарника Hysteria2 + +Официальный скрипт `install_server.sh` хранится в `roles/hysteria2/files/`. + +Перед `make install` / `make update` на **control node**: + +1. Скачивается копия с https://get.hy2.sh/ +2. Сравнивается SHA256 с локальным файлом в роли +3. При отличии — локальная копия обновляется +4. Скрипт копируется на VPS и запускается оттуда + +--- + +## `make update` — что меняется + +| Компонент | Поведение | +|---|---| +| Бинарник `hysteria` | Обновляется (`install_server.sh --force`) | +| `/etc/hysteria/config.yaml` | Перекатывается (auth + obfs) | +| Пароли VPN / obfs | Сохраняются для существующей конфигурации | +| URL / QR | Только для новых, изменённых или при `hysteria2_force_export=true` | +| `apt upgrade` | **Не** выполняется | +| Ожидание ACME | **Не** выполняется | + +--- + +## `make uninstall` — полная очистка + +На **VPS** удаляется: + +- сервис и бинарник Hysteria2; +- `/etc/hysteria/` (конфиг и ACME); +- пользователь `hysteria` и его home; +- правила ufw: `443/tcp`, `443/udp` (порт из `hysteria2_listen_port`); +- пакеты `curl`, `micro`, `qrencode`. + +На **control node**: `output//` и пересборка `output/index.html`. + +Сохранить локальный экспорт: `EXTRA_VARS='hysteria2_uninstall_remove_local_output=false'`. + --- ## Let's Encrypt — обновление сертификата @@ -301,18 +371,26 @@ ASCII QR — `hysteria share --qr` → `user.qr.txt`. | `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_force_export` | group | Перегенерировать URL/QR для всех пользователей (`false` — только новые/изменённые) | +| `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_dir` | group | Папка экспорта (`./output`) | | `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 | | `hysteria2_open_browser` | group | Открыть `output/index.html` после экспорта | -| `hysteria2_uninstall_remove_local_output` | group | Удалить `output//` при uninstall (по умолчанию `true`) | -| `hysteria2_uninstall_rebuild_global_index` | group | Пересобрать `output/index.html` после uninstall (по умолчанию `true`) | +| `hysteria2_uninstall_remove_local_output` | group | Удалить `output//` при uninstall (`true`) | +| `hysteria2_uninstall_rebuild_global_index` | group | Пересобрать `output/index.html` (`true`) | +| `vault_ssh_passwords` | vault | SSH-пароли root | +| `vault_hysteria2_user_passwords` | vault | VPN-пароли по серверам | | `vault_hysteria2_obfs_passwords` | vault | obfs-пароли по серверам | +Полный список: `roles/hysteria2/defaults/main.yml`, `defaults/uninstall.yml`. + --- ## Безопасность @@ -326,11 +404,12 @@ ASCII QR — `hysteria share --qr` → `user.qr.txt`. ## Требования -- Ansible 2.14+ -- Debian/Ubuntu VPS с sudo +- **Control node:** macOS или Linux с Ansible **2.14+** (`brew install ansible` на Mac) +- **VPS:** Debian/Ubuntu с sudo - Домен с A-записью на IP (для ACME TLS) +- Порт **443/tcp+udp** доступен с интернета - Клиент Hysteria2 с поддержкой Salamander (Shadowrocket, NekoBox, Hiddify и др.) -- Для авто-открытия браузера: macOS или Linux с `xdg-open` +- Для авто-открытия браузера: macOS (`open`) или Linux (`xdg-open`) --- @@ -338,15 +417,30 @@ ASCII QR — `hysteria share --qr` → `user.qr.txt`. ``` roles/hysteria2/ +├── defaults/ +│ ├── main.yml +│ └── uninstall.yml +├── files/ +│ └── install_server.sh ├── tasks/ -│ ├── obfs.yml ← генерация/загрузка obfs-пароля -│ ├── configure.yml ← Salamander, без masquerade -│ ├── export.yml ← URL, QR, HTML сервера -│ └── export_global.yml ← общий output/index.html +│ ├── main.yml +│ ├── validate.yml +│ ├── users.yml +│ ├── obfs.yml ← пароль Salamander obfs +│ ├── sync_install_script.yml +│ ├── 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 tls + obfs salamander - ├── client.yaml.j2 ← клиент с obfs - └── export/ ← HTML-каталоги + ├── config.yaml.j2 ← acme tls + obfs salamander + ├── client.yaml.j2 + └── export/ ``` ---