docs(ui): human cascade guide + kaskad_web_vpn

Expand cascade fold with steps, DNAT primer, install one-liner, link to github.com/andrey271192/kaskad_web_vpn; README and panel-guide aligned. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-20 14:42:00 +00:00 · 2026-05-15 04:49:14 +03:00
parent 0e7a7df636
commit df1f9dc826
4 changed files with 78 additions and 9 deletions
--- a/README.md
+++ b/README.md
@@ -216,7 +216,14 @@ UI_HIDE_SECTIONS=warp,cascade curl -fsSL https://raw.githubusercontent.com/andre

 ### Каскад (свой Endpoint для клиента)

-В панели блок **«Новый клиент под каскад»**: задаёте IP/DNS и при необходимости порт — сервер **генерирует ключи**, добавляет peer в текущий инстанс AmneziaWG и отдаёт `.conf`, где **Endpoint** указывает на ваш промежуточный узел. На этом узле нужен **проброс UDP** на VPS (тот же порт, что слушает WG на сервере, либо свой порт из формы).
+Сценарий: **устройство в интернете подключается не к вашему «основному» VPS напрямую**, а к **промежуточному узлу** (ещё один VPS, домашний роутер с пробросом и т.д.), а уже этот узел **пересылает UDP** на порт WireGuard вашего основного VPS, где живёт AmneziaWG и эта панель.
+
+Что нужно человеку, который ставит связку:
+
+1. На **этом** (основном) VPS — обычный AmneziaWG и панель PRO; здесь блок **«Новый клиент под каскад»** **создаёт peer и ключи** и выдаёт скачанный **`.conf`**, в котором **Endpoint** уже указывает на промежуточную машину.
+2. На **промежуточном** сервере нужен **проброс порта DNAT до основного VPS** на тот же **ListenPort**, что слушает туннель здесь (либо свой внешний порт → тогда его указывают в форме как «Порт Endpoint»).
+
+Готовая панель для правил проброса (iptables DNAT NAT «под ключ»): репозиторий **[andrey271192/kaskad_web_vpn](https://github.com/andrey271192/kaskad_web_vpn)** — установка `curl … install.sh | sudo bash`, затем вход в браузере на промежуточный VPS по порту из README (например `8088/setup`) и настройка правила «вход → IP основного VPS:порт WG». Подробные шаги и переменные среды см. там же в README.

 ### Экспорт конфигурации клиента (.conf)

--- a/docs/panel-guide.md
+++ b/docs/panel-guide.md
@@ -10,7 +10,7 @@
 | **Время** | Отображение часов контейнера и браузера; синхронизация времени хоста VPS по SSH (если доступно). |
 | **Cloudflare WARP** | *Необязательно.* Вывод части клиентов в интернет через интерфейс `warp` в контейнере AWG. Если WARP не ставили — статус **«Не установлен»** нормален; панель и VPN без этого работают. Установка и удаление — скрипт `scripts/warp-amnezia.sh` на хосте (`install` / **`uninstall`**), подробности в основном [README](../README.md). |
 | **Telegram MTProto‑прокси** | *Необязательно*, не часть AWG. Docker-контейнер официального образа **telegrammessenger/proxy**; установка из панели, ссылка **`tg://proxy`**, переменные **`MTPRO_*`** — см. основной [README](../README.md). |
-| **Новый клиент под каскад** | Создание нового peer на сервере с **вашим Endpoint** (промежуточный узел); выдача готового `.conf`. |
+| **Новый клиент под каскад** | Клиент в конфиге смотрит на **промежуточный узел** по Endpoint; peer и ключи создаются **на текущем VPS** и отдаются в `.conf`. На промежуточном сервере заранее нужен проброс порта DNAT UDP до WG этого VPS ([**kaskad_web_vpn**](https://github.com/andrey271192/kaskad_web_vpn) или свой проброс); в блоке см. текст и команду установки каскад-панели. |
 | **Пользователи** | Вкл/выкл peer, удаление, переименование, даты отключения; экспорт `.conf` если в записи есть `userData.last_config`. |

 ## Переключатель «Инстанс» не отображается
--- a/public/index.html
+++ b/public/index.html
@@ -163,15 +163,30 @@
        <span class="fold-arrow" aria-hidden="true"></span>
        <span class="fold-titles">
          <span class="fold-h">Новый клиент под каскад</span>
-          <span class="muted fold-meta">Создать peer и скачать .conf</span>
+          <span class="muted fold-meta">Клиент стучится в «первый» узел → трафик сюда; ключи выдаём на этом VPS</span>
        </span>
      </summary>
      <div class="panel-fold-body">
-        <p class="muted cascade-intro">
-          Укажите <strong>Endpoint</strong> — публичный IP или DNS узла, <em>куда клиент будет подключаться первым шагом</em>
-          (промежуточный сервер, домашний роутер с пробросом порта и т.д.). Порт по умолчанию совпадает с <code class="inline">ListenPort</code> этого инстанса.
-          Клиент будет <strong>создан на текущем сервере AmneziaWG</strong> (новые ключи); IP в туннеле можно задать явно или оставить пустым — подберём свободный в той же подсети, что у остальных.
-        </p>
+        <div class="muted cascade-guide">
+          <p class="cascade-intro">
+            <strong>Что здесь происходит.</strong> Приложение Amnezia всегда смотрит на поле <strong>Endpoint</strong> в конфиге.
+            При каскаде клиент «видит» только <strong>промежуточный узел</strong> (часто недорогой VPS поближе к пользователям), а <strong>реальное соединение AmneziaWG живёт на этом сервере</strong>, где крутится ваш основной контейнер.
+            Ключ и peer создаём здесь и выдаём файл <code class="inline">.conf</code> — Endpoint в файле будет на промежуточную машину, а не на прямой IP этого VPS в интернете.
+          </p>
+          <p class="cascade-intro cascade-intro-tight"><strong>Сначала нужна пересылка порта до этого VPS.</strong> На промежуточном сервере настройте проброс DNAT UDP (и TCP при необходимости).
+            Удобный вариант с веб-панелью iptables —
+            репозиторий <a href="https://github.com/andrey271192/kaskad_web_vpn" target="_blank" rel="noopener noreferrer"><strong>kaskad_web_vpn</strong></a>:
+            ставится одной командой ниже; в её панели создаёте правило «входящий порт → UDP на IP:порт этого AmneziaWG». Подробнее — README в том же репозитории.</p>
+          <pre class="cascade-snippet" tabindex="0" role="note" aria-label="Установка kaskad_web_vpn на промежуточном VPS">curl -fsSL https://raw.githubusercontent.com/andrey271192/kaskad_web_vpn/main/install.sh | sudo bash</pre>
+          <p class="cascade-intro cascade-intro-tight">После установки откройте <code class="inline">http://ПЕРЕХОДНОЙ_IP:8088/setup</code> (или свой <code class="inline">HOST_PORT</code>), задайте пароль админки каскада и добавьте правило проброса на <strong><code class="inline">ListenPort</code> этого инстанса</strong> на данном VPS (видно в шапке панели или в <code class="inline">awg show</code>).</p>
+          <ol class="cascade-steps">
+            <li>На промежуточном VPS: <strong>kaskad_web_vpn</strong> (команда выше) или свой DNAT / проброс порта на роутере.</li>
+            <li>Проверьте, что с промежуточной машины доходит UDP до WG-порта на <strong>этом</strong> сервере (если ниже поле порта Endpoint пустое — это тот же порт, что <code class="inline">ListenPort</code> здесь).</li>
+            <li>В форме ниже в <strong>Endpoint</strong> укажите публичный <strong>IP или DNS промежуточного узла</strong> — тот адрес, с которым реально установит туннель клиентское приложение из интернета.</li>
+            <li>Нажмите <strong>Создать на сервере и скачать .conf</strong> и импортируйте файл в Amnezia на телефоне или ПК.</li>
+          </ol>
+          <p class="cascade-intro cascade-intro-tight"><strong>Порт Endpoint</strong> — когда снаружи слушает не тот номер порта, что WG здесь (пусто значит «как у сервера»). <strong>IP в VPN-туннеле</strong> можно не заполнять — подберём свободный адрес в той же подсети, что у остальных клиентов.</p>
+        </div>
        <form id="cascade-form" class="cascade-form">
          <label for="cascade-endpoint">Endpoint (хост для клиента)</label>
          <input id="cascade-endpoint" type="text" placeholder="Например 203.0.113.50 или ddns.example.com" required autocomplete="off">
--- a/public/styles.css
+++ b/public/styles.css
@@ -505,7 +505,7 @@ h1 {
 }

 .panel-fold-body > .warp-intro:first-child,
-.panel-fold-body > .cascade-intro:first-child {
+.panel-fold-body > .cascade-guide:first-child {
  margin-top: 0.85rem;
 }

@@ -702,6 +702,53 @@ tr:last-child td {
  font-size: 0.85em;
 }

+.cascade-guide .cascade-intro {
+  margin: 0 0 0.75rem;
+  line-height: 1.5;
+}
+
+.cascade-guide .cascade-intro-tight {
+  margin-bottom: 0.55rem;
+}
+
+.cascade-guide a {
+  color: #7dd3fc;
+  text-decoration: underline;
+  text-underline-offset: 0.14em;
+}
+
+.cascade-guide a:hover {
+  color: #bae6fd;
+}
+
+.cascade-steps {
+  margin: 0.65rem 0 0.85rem;
+  padding-left: 1.35rem;
+  line-height: 1.52;
+}
+
+.cascade-steps li {
+  margin-bottom: 0.45rem;
+}
+
+.cascade-steps li:last-child {
+  margin-bottom: 0;
+}
+
+.cascade-snippet {
+  white-space: pre-wrap;
+  word-break: break-word;
+  background: #0a0f16;
+  border: 1px solid var(--line);
+  padding: 0.75rem 0.95rem;
+  border-radius: 12px;
+  color: #cbd5f5;
+  font-size: 0.78rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  margin: 0.5rem 0 0.85rem;
+  max-width: min(52rem, 100%);
+}
+
 .cascade-form {
  display: grid;
  gap: 0.55rem;