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 <cursoragent@cursor.com>
2026-07-01 13:16:38 +03:00
parent 0745fdce2c
commit f5939c48fc
1 changed files with 116 additions and 22 deletions
@@ -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/<server>/` + пересборка `output/index.html` |
-| `make vault-encrypt` | Зашифровать vault |
-| `make vault-edit` | Редактировать vault |
+| `make update` | Обновить бинарник и конфиг; экспорт только для новых/изменённых пользователей |
+| `make export` | Только экспорт (URL, QR, HTML) без изменений на сервере |
+| `make uninstall` | Полное удаление с VPS + `output/<server>/` + пересборка `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/<server>/`.
+
+---
+
+## Установка бинарника 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/<server>/` и пересборка `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/<server>/` при uninstall (по умолчанию `true`) |
-| `hysteria2_uninstall_rebuild_global_index` | group | Пересобрать `output/index.html` после uninstall (по умолчанию `true`) |
+| `hysteria2_uninstall_remove_local_output` | group | Удалить `output/<server>/` при 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/
 ```

 ---