From 5853aaae00dfc2d0af020d0dfa45b644c5966fc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BD=D0=B4=D1=80=D0=B5=D0=B9=20=D0=91=D0=BE=D0=B1?= =?UTF-8?q?=D1=8B=D1=80=D0=B5=D0=B2?= Date: Thu, 14 May 2026 18:54:58 +0300 Subject: [PATCH] docs: panel guide + README refresh for multi-instance & cascade - Add docs/panel-guide.md (features, troubleshooting, API table) - README: intro, two AWG_PROFILES examples with pskPath, landing port note - Bump package.json to 1.1.0; update verify grep for current UI Co-authored-by: Cursor --- README.md | 27 ++++++++++++++------ docs/panel-guide.md | 61 +++++++++++++++++++++++++++++++++++++++++++++ package.json | 4 +-- 3 files changed, 83 insertions(+), 9 deletions(-) create mode 100644 docs/panel-guide.md diff --git a/README.md b/README.md index b2e5cfa..bf5a14f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Amnezia Admin WebUI -Веб-панель на вашем VPS для управления клиентами **AmneziaWG**: вкл/выкл, удаление, переименование, дата отключения, при наличии `last_config` на сервере — **скачивание клиентского .conf**, а также **политика выхода через Cloudflare WARP** по клиентам (без Telegram и без QR — только скрипт установки на хосте и блок в вебе). Работает через Docker и `docker exec` в контейнер **Amnezia** (по умолчанию `amnezia-awg2`). +Веб-панель на вашем VPS для управления клиентами **AmneziaWG**: вкл/выкл, удаление, переименование, дата отключения; при нескольких контейнерах — переключатель **«Инстанс»** (`AWG_PROFILES`); **экспорт .conf** при наличии `last_config`; **новый клиент под каскад** (свой Endpoint и ключи на сервере); **Cloudflare WARP** по клиентам (без Telegram и без QR — скрипт на хосте и блок в вебе). Работает через Docker и `docker exec` в контейнер **Amnezia** (по умолчанию `amnezia-awg2`). + +Справочник по интерфейсу, типичным сбоям и HTTP API: **[docs/panel-guide.md](docs/panel-guide.md)**. **Безопасность:** контейнер с монтированием `docker.sock` эквивалентен root на хосте — используйте сложный пароль и по возможности ограничьте доступ по IP или TLS. @@ -73,14 +75,25 @@ cd /opt/amnezia-admin && chmod +x scripts/install.sh && sudo SKIP_DOWNLOAD=1 bas #### Несколько инстансов (AmneziaWG + Legacy и т.д.) -Пути и имена контейнеров на сервере могут отличаться — проверьте внутри контейнера (`docker exec … ls /opt/amnezia`). Пример **двух** профилей при запуске установщика (одна строка JSON в кавычках): +Пути и имена контейнеров на сервере могут отличаться — проверьте внутри контейнера (`docker exec … ls /opt/amnezia`). Установщик сохраняет JSON в **`/root/amnezia-admin.awg-profiles.json`** и при следующем запуске подставляет его, если вы не передали `AWG_PROFILES`. + +**Пример 1** — классическая схема: новый AWG в `amnezia-awg2`, Legacy в отдельном контейнере с каталогом `wireguard`: ```bash -AWG_PROFILES='[{"id":"awg","label":"AmneziaWG","container":"amnezia-awg2","confPath":"/opt/amnezia/awg/awg0.conf","clientsPath":"/opt/amnezia/awg/clientsTable","iface":"awg0","wgBinary":"awg"},{"id":"legacy","label":"AmneziaWG Legacy","container":"amnezia-wg0","confPath":"/opt/amnezia/wireguard/wg0.conf","clientsPath":"/opt/amnezia/wireguard/clientsTable","iface":"wg0","wgBinary":"wg"}]' \ +AWG_PROFILES='[{"id":"awg","label":"AmneziaWG","container":"amnezia-awg2","confPath":"/opt/amnezia/awg/awg0.conf","clientsPath":"/opt/amnezia/awg/clientsTable","iface":"awg0","wgBinary":"awg","pskPath":"/opt/amnezia/awg/wireguard_psk.key"},{"id":"legacy","label":"AmneziaWG Legacy","container":"amnezia-wg0","confPath":"/opt/amnezia/wireguard/wg0.conf","clientsPath":"/opt/amnezia/wireguard/clientsTable","iface":"wg0","wgBinary":"wg","pskPath":"/opt/amnezia/wireguard/wireguard_psk.key"}]' \ curl -fsSL https://raw.githubusercontent.com/andrey271192/Amnezia_web/main/scripts/install.sh | sudo -E bash ``` -Для **Legacy** часто используется обычный `wg`, для новой AmneziaWG — `awg`; подставьте свои `container`, `confPath`, `clientsPath`, `iface`, `pskPath` при необходимости. +**Пример 2** — оба конфигурационных набора внутри контейнера **`amnezia-awg`** (файл `wg0.conf` рядом с `awg0.conf` в `/opt/amnezia/awg/`), второй контейнер **`amnezia-awg2`**: + +```bash +AWG_PROFILES='[{"id":"awg","label":"AmneziaWG","container":"amnezia-awg2","confPath":"/opt/amnezia/awg/awg0.conf","clientsPath":"/opt/amnezia/awg/clientsTable","iface":"awg0","wgBinary":"awg","pskPath":"/opt/amnezia/awg/wireguard_psk.key"},{"id":"legacy","label":"AmneziaWG Legacy","container":"amnezia-awg","confPath":"/opt/amnezia/awg/wg0.conf","clientsPath":"/opt/amnezia/awg/clientsTable","iface":"wg0","wgBinary":"wg","pskPath":"/opt/amnezia/awg/wireguard_psk.key"}]' \ +curl -fsSL https://raw.githubusercontent.com/andrey271192/Amnezia_web/main/scripts/install.sh | sudo -E bash +``` + +Для **Legacy** часто используется обычный `wg`, для новой AmneziaWG — **`awg`**; поле **`pskPath`** желательно указывать явно, если путь к `wireguard_psk.key` нестандартный. + +Если в вебе пропал список **«Инстанс»**, смотрите раздел «Если пропал список Инстанс» в **[docs/panel-guide.md](docs/panel-guide.md)**. ### Cloudflare WARP (только AmneziaWG в Docker) @@ -101,7 +114,7 @@ chmod +x scripts/warp-amnezia.sh Необязательно передайте в контейнер **amnezia-admin** переменные `WARP_DIR`, `WARP_CONF_PATH`, `WARP_CLIENTS_LIST`, `AMNEZIA_START_SCRIPT` через установщик — см. таблицу выше. -После установки: **админ-панель** `http://IP:8080` (или ваш `HOST_PORT`), **страница с поддержкой проекта** `http://IP/` на порту лендинга (по умолчанию **80**). Кнопка на лендинге ведёт на админку с тем же `HOST_PORT`. +После установки: **админ-панель** `http://IP:8080` (или ваш `HOST_PORT`). **Лендинг** с поддержкой по умолчанию на порту **80**; если порт занят, установщик сообщит об ошибке — задайте **`LANDING_PORT=8081`** или **`SKIP_LANDING=1`** (на работу панели это не влияет). Кнопка на лендинге ведёт на админку с тем же `HOST_PORT`. Футер с ссылками (**Amnezia Admin WebUI**, Boosty, Ozon СБП, Telegram) в админке находится **внизу страницы** — прокрутите ниже таблицы. @@ -149,10 +162,10 @@ cd /opt/amnezia-admin && chmod +x scripts/install.sh && sudo SKIP_DOWNLOAD=1 bas После обновления сделайте в браузере **жёсткое обновление** страницы (Ctrl+Shift+R / ⌘+Shift+R), если интерфейс всё ещё старый. -Команда на сервере для проверки, что в образ попали новые статические файлы (после установки должно быть **Amnezia Admin WebUI**, не «Kaskad»): +Команда на сервере для проверки, что в образ попали актуальные статические файлы: ```bash -sudo docker run --rm amnezia-admin:latest grep -E -o 'Amnezia Admin WebUI|Kaskad' /app/public/index.html | head -1 +sudo docker run --rm amnezia-admin:latest grep -Eo 'Новый клиент под каскад|Cloudflare WARP' /app/public/index.html | head -1 ``` --- diff --git a/docs/panel-guide.md b/docs/panel-guide.md new file mode 100644 index 0000000..94ab6c8 --- /dev/null +++ b/docs/panel-guide.md @@ -0,0 +1,61 @@ +# Руководство по Amnezia Admin WebUI + +Краткий справочник по функциям, типичным проблемам и HTTP API. + +## Возможности + +| Блок в интерфейсе | Назначение | +|-------------------|------------| +| **Инстанс** | Переключение между профилями из `AWG_PROFILES` (разные контейнеры AmneziaWG / Legacy). Виден только если в контейнере панели задан JSON из **двух и более** профилей. | +| **Время** | Отображение часов контейнера и браузера; синхронизация времени хоста VPS по SSH (если доступно). | +| **Cloudflare WARP** | Выбор клиентов (IPv4 `/32`), выход в интернет через интерфейс `warp` в контейнере AWG. | +| **Новый клиент под каскад** | Создание нового peer на сервере с **вашим Endpoint** (промежуточный узел); выдача готового `.conf`. | +| **Пользователи** | Вкл/выкл peer, удаление, переименование, даты отключения; экспорт `.conf` если в записи есть `userData.last_config`. | + +## Переключатель «Инстанс» не отображается + +1. Проверьте переменную контейнера панели: + ```bash + docker inspect amnezia-admin --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^AWG_PROFILES=' + ``` +2. Если строки нет — один раз задайте JSON при установке (пример см. в основном [README](../README.md)) или восстановите файл **`/root/amnezia-admin.awg-profiles.json`** на VPS и снова запустите `install.sh` **без** своего `AWG_PROFILES` — установщик подставит значение из файла или из старого контейнера перед удалением. +3. После правок обновите страницу с **жёстким сбросом кэша** (Ctrl+Shift+R). + +## Лендинг не поднимается (порт 80 занят) + +При ошибке bind `:80` используйте при установке **`SKIP_LANDING=1`** или **`LANDING_PORT=8081`** — админка на `HOST_PORT` (например 8080) от этого не зависит. + +## Конфигурации клиентов + +- **Старые строки без `last_config`** — полный `.conf` с сервера собрать нельзя (нет приватного ключа). Используйте приложение Amnezia или блок **«Новый клиент под каскад»** (новый ключ на сервере). +- **Экспорт по кнопкам** — только если в `clientsTable` есть **`userData.last_config`** с полем `config` или `client_priv_key`. + +## HTTP API (все маршруты под `/`, кроме статики) + +Требуют cookie-сессии после **`POST /api/login`**, если не указано иное. + +| Метод | Путь | Назначение | +|-------|------|------------| +| GET | `/health` | Проверка живости | +| GET | `/api/session` | Есть ли действующая сессия | +| POST | `/api/login` | `{ "password": "…" }` | +| POST | `/api/logout` | Выход | +| POST | `/api/change-password` | Смена пароля | +| GET | `/api/protocols` | Текущий профиль, список инстансов, подсказка если профиль один | +| POST | `/api/protocol` | `{ "profileId": "…" }` — смена инстанса | +| GET | `/api/clients` | Таблица клиентов и метаданные WARP | +| POST | `/api/clients/disable` | Выключить peer | +| POST | `/api/clients/enable` | Включить peer | +| POST | `/api/clients/delete` | Удалить | +| POST | `/api/clients/rename` | Переименовать | +| POST | `/api/clients/disconnect-date` | Даты отключения / расписание | +| GET/POST | `/api/clients/export-config` | Скачать `.conf`; GET — прямая ссылка (сессия); опционально `?token=…` если задан `EXPORT_CONFIG_SECRET` | +| POST | `/api/clients/create-cascade` | `{ "endpointHost", "endpointPort?", "tunnelIp?", "clientName?", "profileId?" }` — новый peer и файл `.conf` | +| POST | `/api/warp/start` | Поднять WARP | +| POST | `/api/warp/stop` | Остановить WARP | +| POST | `/api/warp/routing` | Политика по клиентам | +| GET | `/api/server-time` | Время и подсказки по поясам | +| GET | `/api/time-sync-capabilities` | Доступность синхронизации по SSH | +| POST | `/api/sync-host-time` | Запись времени на хост через SSH | + +Подробности переменных окружения — в таблице установки в [README](../README.md). diff --git a/package.json b/package.json index 8b2a086..ae44b3a 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,8 @@ { "name": "amnezia-admin", - "version": "1.0.0", + "version": "1.1.0", "private": true, - "description": "Web-панель управления клиентами AmneziaWG (Docker, пароль, AWG)", + "description": "Web-панель AmneziaWG: несколько инстансов, WARP, каскад/Endpoint, экспорт .conf (Docker)", "license": "MIT", "repository": { "type": "git",