diff --git a/addons/mediaserver/README.md b/addons/mediaserver/README.md
index f9f96c0..2301189 100644
--- a/addons/mediaserver/README.md
+++ b/addons/mediaserver/README.md
@@ -63,6 +63,173 @@ Init-контейнер автоматически прописывает в `co
 <ProxyBypassLocalAddresses>True</ProxyBypassLocalAddresses>
 ```
 
+### Настройка Hysteria2 сервера
+
+#### Способ 1 — URL (Shadowrocket / Clash / NekoBox / hyst2 import)
+
+Hysteria2 поддерживает стандартный URL-формат — его можно скопировать прямо из Shadowrocket, NekoBox, Hiddify и любого другого клиента:
+
+```
+hysteria2://PASSWORD@HOST:PORT?insecure=0&obfs=salamander&obfs-password=OBFS_PASS#MyProxy
+```
+
+Части URL:
+
+| Часть | Значение |
+|---|---|
+| `PASSWORD` | Пароль аутентификации (`auth`) |
+| `HOST:PORT` | Адрес и порт сервера |
+| `insecure=1` | Отключить проверку TLS-сертификата (self-signed) |
+| `insecure=0` | Проверять сертификат (Let's Encrypt / доверенный CA) |
+| `obfs=salamander` | Включить obfuscation типа salamander |
+| `obfs-password=...` | Пароль для obfuscation |
+| `#MyProxy` | Имя (метка — игнорируется, только для отображения) |
+
+Примеры URL:
+
+```
+# Без obfuscation, с проверкой TLS
+hysteria2://mypassword@vps.example.com:443
+
+# Без obfuscation, самоподписанный сертификат
+hysteria2://mypassword@1.2.3.4:443?insecure=1
+
+# С salamander obfuscation
+hysteria2://mypassword@vps.example.com:443?obfs=salamander&obfs-password=obfsecret
+
+# Полный вариант с именем
+hysteria2://mypassword@vps.example.com:443?insecure=0&obfs=salamander&obfs-password=obfsecret#MyVPS
+```
+
+Чтобы использовать URL в vault — просто разбери его на части:
+
+```yaml
+# Из URL: hysteria2://mypassword@vps.example.com:443?obfs=salamander&obfs-password=obfsecret
+vault_hysteria2_server: "vps.example.com:443"
+vault_hysteria2_auth: "mypassword"
+```
+
+Obfuscation и TLS задаются отдельными переменными — см. ниже.
+
+---
+
+#### Способ 2 — JSON / inline конфиг
+
+Если у тебя есть конфиг в JSON-формате (экспорт из Hiddify, XRay-клиентов и т.д.):
+
+```json
+{
+  "server": "vps.example.com:443",
+  "auth": "mypassword",
+  "tls": {
+    "insecure": false,
+    "sni": "vps.example.com"
+  },
+  "obfs": {
+    "type": "salamander",
+    "salamander": {
+      "password": "obfsecret"
+    }
+  },
+  "socks5": {
+    "listen": "127.0.0.1:1080"
+  }
+}
+```
+
+Маппинг JSON → переменные Ansible:
+
+| JSON поле | Ansible переменная |
+|---|---|
+| `server` | `vault_hysteria2_server` |
+| `auth` | `vault_hysteria2_auth` |
+| `tls.insecure: true` | `mediaserver_hysteria2_insecure: true` |
+| `obfs.type` | `mediaserver_hysteria2_obfs_type` |
+| `obfs.salamander.password` | `mediaserver_hysteria2_obfs_password` |
+
+---
+
+#### Параметры в `group_vars/all/main.yml`
+
+```yaml
+# Адрес и порт сервера (из vault)
+vault_hysteria2_server: "vps.example.com:443"
+vault_hysteria2_auth: "mypassword"
+
+# TLS — пропустить проверку сертификата (self-signed)
+mediaserver_hysteria2_insecure: false    # true если сервер с самоподписанным сертом
+
+# Obfuscation (salamander) — скрыть протокол от DPI
+mediaserver_hysteria2_obfs_type: "salamander"   # "" — без obfuscation
+mediaserver_hysteria2_obfs_password: "obfsecret"
+
+# UDP переадресация включена по умолчанию в Hysteria2
+# Интервал смены UDP портов (hop) — защита от блокировки по порту
+# Задаётся в конфиге: transport.udp.hopInterval: 30s
+```
+
+Итоговый конфиг, который попадёт в Secret (`hysteria2-secret.yaml.j2`):
+
+```yaml
+server: vps.example.com:443
+auth: mypassword
+tls:
+  insecure: false           # true = игнорировать самоподписанный сертификат
+obfs:
+  type: salamander
+  salamander:
+    password: obfsecret
+socks5:
+  listen: 127.0.0.1:1080   # Prowlarr подключается сюда
+transport:
+  udp:
+    hopInterval: 30s        # UDP port hopping каждые 30 сек
+```
+
+---
+
+#### Быстрый старт без obfuscation (минимальный пример)
+
+```yaml
+# vault.yml
+vault_hysteria2_server: "1.2.3.4:443"
+vault_hysteria2_auth: "supersecretpassword"
+```
+
+```bash
+make addon-mediaserver
+```
+
+#### С obfuscation salamander
+
+```yaml
+# vault.yml
+vault_hysteria2_server: "vps.example.com:443"
+vault_hysteria2_auth: "supersecretpassword"
+```
+
+```yaml
+# group_vars/all/main.yml или через ARGS
+mediaserver_hysteria2_obfs_type: "salamander"
+mediaserver_hysteria2_obfs_password: "obfs-secret-phrase"
+```
+
+```bash
+make addon-mediaserver ARGS="-e mediaserver_hysteria2_obfs_type=salamander -e mediaserver_hysteria2_obfs_password=obfs-secret-phrase"
+```
+
+#### Self-signed сертификат на сервере
+
+```bash
+make addon-mediaserver ARGS="-e mediaserver_hysteria2_insecure=true"
+```
+
+#### Без прокси (если не нужен)
+
+```bash
+make addon-mediaserver ARGS="-e mediaserver_hysteria2_enabled=false"
+```
+
 ## Установка
 
 ### 1. Vault секреты