docs: update README for install script, update, uninstall and users

Document incremental export, full uninstall cleanup, vault wiring, Makefile commands and role structure.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -42,14 +42,23 @@ git clone https://git.antropoff.ru/DevOpsTools/hysteria2.git
 cd hysteria2
 git checkout main
 
+# 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
@@ -57,15 +66,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` | Установка masquerade + экспорт URL/QR/HTML |
-| `make update` | Обновить бинарник, конфиг, перевыпустить экспорт |
+| `make update` | Обновить бинарник и конфиг; экспорт только для новых/изменённых пользователей |
-| `make export` | Только экспорт (URL, QR, HTML) |
+| `make export` | Только экспорт (URL, QR, HTML) без изменений на сервере |
-| `make uninstall` | Полное удаление Hysteria2 с VPS + `output/<server>/` + пересборка `output/index.html` |
+| `make uninstall` | Полное удаление с VPS + `output/<server>/` + пересборка `output/index.html` |
-| `make vault-encrypt` | Зашифровать vault |
+| `make vault-init` | Создать `.vault_pass`, включить `vault_password_file` в `ansible.cfg` |
-| `make vault-edit` | Редактировать vault |
+| `make vault-encrypt` | Зашифровать `vault.yml` |
+| `make vault-edit` | Редактировать vault (редактор **nano**, см. `EDITOR` в Makefile) |
+| `make vault-view` | Показать расшифрованный vault |
 
 ```bash
 make install LIMIT=vps-de
@@ -73,10 +85,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
@@ -190,6 +205,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:**
@@ -202,10 +218,67 @@ hysteria2_user_passwords:
 3. **Автогенерация** — Ansible `password` lookup, если пароль не задан ни в inventory/vault, ни в `output/<server>/server-info.yml`.
 
 При `make update` / `make export`:
-- **существующие** пользователи сохраняют пароли из `server-info.yml` (и URL/QR, если домен/порт/obfs не менялись);
+- **существующие** пользователи сохраняют пароли из `server-info.yml` (и URL/QR, если домен/порт не менялись);
 - **новые** получают автогенерацию и полный экспорт;
 - **удалённые** из inventory убираются из конфига Hysteria2 и из `output/<server>/`.
 
+Принудительно перевыпустить URL/QR для всех: `hysteria2_force_export: true` (в `group_vars/all.yml` или `EXTRA_VARS`).
+
+### Добавить / удалить пользователя
+
+1. Отредактируйте `hysteria2_users` в `inventory/hosts.yml` (добавьте имя или уберите).
+2. Запустите `make update LIMIT=<хост>`.
+
+Пароли существующих клиентов **не меняются** (берутся из `output/<server>/server-info.yml`).  
+Новому пользователю генерируется пароль и создаются URL/QR.  
+Удалённый пользователь пропадает из `/etc/hysteria/config.yaml` и из папки `output/<server>/`.
+
+---
+
+## Установка бинарника Hysteria2
+
+Официальный скрипт `install_server.sh` хранится в `roles/hysteria2/files/`.
+
+Перед `make install` / `make update` на **control node** (ваш Mac):
+
+1. Скачивается копия с https://get.hy2.sh/
+2. Сравнивается SHA256 с локальным файлом в роли
+3. При отличии — локальная копия обновляется
+4. Скрипт копируется на VPS и запускается оттуда (без `curl | bash` на сервере)
+
+---
+
+## `make update` — что меняется
+
+| Компонент | Поведение |
+|---|---|
+| Бинарник `hysteria` | Обновляется (`install_server.sh --force`) |
+| `/etc/hysteria/config.yaml` | Перекатывается под текущий inventory |
+| Пароли VPN | Сохраняются для существующих пользователей |
+| URL / QR | Только для новых, изменённых или при `hysteria2_force_export=true` |
+| `apt upgrade` | **Не** выполняется (отключено в Makefile) |
+| Ожидание ACME | **Не** выполняется (`hysteria2_wait_for_acme=false`) |
+
+---
+
+## `make uninstall` — полная очистка
+
+На **VPS** удаляется:
+
+- сервис и бинарник Hysteria2 (`install_server.sh --remove`);
+- `/etc/hysteria/` (конфиг и данные ACME);
+- `/var/www/masq` (сайт-заглушка);
+- пользователь `hysteria` и его home;
+- правила ufw: `80/tcp`, `443/tcp`, `443/udp`;
+- пакеты `curl`, `micro`, `qrencode`.
+
+На **control node**:
+
+- папка `output/<server>/` (по умолчанию);
+- пересборка общего `output/index.html` без удалённого сервера.
+
+Сохранить локальный экспорт: `EXTRA_VARS='hysteria2_uninstall_remove_local_output=false'`.
+
 ---
 
 ## Let's Encrypt — обновление сертификата
@@ -282,15 +355,23 @@ 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 |
+| `hysteria2_user_passwords` | host/vault | Фиксированные пароли VPN (`vars.yml` + vault) |
-| `hysteria2_force_export` | group | Перегенерировать URL/QR для всех пользователей (`false` — только новые/изменённые) |
+| `hysteria2_password_length` | group | Длина автогенерируемого пароля (40) |
-| `hysteria2_output_dir` | group | Папка экспорта (по умолчанию `./output`) |
+| `hysteria2_force_export` | group | Перегенерировать URL/QR для всех (`false` по умолчанию) |
-| `hysteria2_output_name` | host | Имя подпапки (по умолчанию `inventory_hostname`) |
+| `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_generate_qr_png` | group | PNG QR через `qrencode` |
+| `hysteria2_wait_for_acme` | group | Пауза при первом ACME (install) |
 | `hysteria2_open_browser` | group | Открыть `output/index.html` после экспорта |
-| `hysteria2_uninstall_remove_local_output` | group | Удалить `output/<server>/` при uninstall (по умолчанию `true`) |
+| `hysteria2_uninstall_remove_local_output` | group | Удалить `output/<server>/` при uninstall (`true`) |
-| `hysteria2_uninstall_rebuild_global_index` | group | Пересобрать `output/index.html` после uninstall (по умолчанию `true`) |
+| `hysteria2_uninstall_rebuild_global_index` | group | Пересобрать `output/index.html` после uninstall (`true`) |
+| `vault_ssh_passwords` | vault | SSH-пароли root по имени хоста |
+| `vault_hysteria2_user_passwords` | vault | VPN-пароли по серверам |
+
+Полный список defaults: `roles/hysteria2/defaults/main.yml`, `defaults/uninstall.yml`.
 
 ---
 
@@ -304,10 +385,11 @@ ASCII QR — `hysteria share --qr` → `user.qr.txt`.
 
 ## Требования
 
-- Ansible 2.14+
+- **Control node:** macOS или Linux с Ansible **2.14+** (`brew install ansible` на Mac)
-- Debian/Ubuntu VPS с sudo
+- **VPS:** Debian/Ubuntu с sudo
 - Домен с A-записью на IP сервера
-- Для авто-открытия браузера: macOS или Linux с `xdg-open`
+- Порты **80/tcp** и **443/tcp+udp** доступны с интернета (ветка `main`)
+- Для авто-открытия браузера: macOS (`open`) или Linux (`xdg-open`)
 
 ---
 
@@ -315,11 +397,25 @@ ASCII QR — `hysteria share --qr` → `user.qr.txt`.
 
 ```
 roles/hysteria2/
+├── defaults/
+│   ├── main.yml              ← основные переменные
+│   └── uninstall.yml         ← переменные удаления
+├── files/
+│   └── install_server.sh     ← официальный скрипт (синхронизация с get.hy2.sh)
 ├── tasks/
-│   ├── install.yml       ← пакеты, hysteria, qrencode
+│   ├── main.yml              ← порядок задач и теги
-│   ├── configure.yml     ← masquerade + ACME + firewall
+│   ├── validate.yml
+│   ├── users.yml             ← пароли (inventory / vault / server-info.yml)
+│   ├── 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
+│   ├── export_global.yml     ← общий output/index.html
+│   ├── share_user.yml
+│   ├── reuse_export_user.yml
+│   └── uninstall.yml
 └── templates/
     ├── config.yaml.j2        ← acme http + masquerade file
     ├── client.yaml.j2