amnezia_web-PRO/docs/panel-guide.md

Руководство по Amnezia Admin WebUI

Краткий справочник по функциям, типичным проблемам и HTTP API.

Возможности

Блок в интерфейсе	Назначение
Инстанс	Переключение между профилями AWG_PROFILES (разные контейнеры AmneziaWG / Legacy). Виден, если панель получила два и более профиля. Установщик сам создаёт профили, когда на VPS уже запущено несколько контейнеров amnezia-awg*.
Время	Отображение часов контейнера и браузера; синхронизация времени хоста VPS по SSH (если доступно).
Cloudflare WARP	Необязательно. Вывод части клиентов в интернет через интерфейс warp в контейнере AWG. Если WARP не ставили — статус «Не установлен» нормален; панель и VPN без этого работают. Установка и удаление — скрипт scripts/warp-amnezia.sh на хосте (install / uninstall), подробности в основном README.
Telegram MTProto‑прокси	Необязательно, не часть AWG. Docker-контейнер официального образа telegrammessenger/proxy; установка из панели, ссылка tg://proxy, переменные MTPRO_* — см. основной README.
Новый клиент под каскад	Клиент в конфиге смотрит на промежуточный узел по Endpoint; peer и ключи создаются на текущем VPS и отдаются в .conf. На промежуточном сервере заранее нужен проброс порта DNAT UDP до WG этого VPS (kaskad_web_vpn или свой проброс); в блоке см. текст и команду установки каскад-панели.
Импорт клиента	Перенос готового клиента из .conf или JSON backup Amnezia, если backup содержит текстовый конфиг. Панель восстанавливает строку в clientsTable, сохраняет last_config и добавляет peer только если его ещё нет в серверном конфиге.
Пользователи	Вкл/выкл peer, удаление, переименование, даты отключения; экспорт .conf если в записи есть userData.last_config.

Переключатель «Инстанс» не отображается

1. Проверьте переменную контейнера панели:

   docker inspect amnezia-admin --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^AWG_PROFILES='
   

2. Если строки нет, но docker ps показывает два контейнера вида amnezia-awg*, переустановите панель свежим установщиком из GitHub:

   curl -fsSL https://raw.githubusercontent.com/andrey271192/amnezia_web-PRO/main/scripts/install.sh | sudo env SKIP_LANDING=1 bash
   

   Установщик сам создаст AWG_PROFILES и сохранит /root/amnezia-admin.awg-profiles.json.
3. Ручной JSON нужен только при нестандартных путях внутри AWG-контейнеров.
4. После правок обновите страницу с жёстким сбросом кэша (Ctrl+Shift+R).

Инстансы задублировались

После переустановки старый AWG_PROFILES и сохранённые managed-инстансы могли указывать на один и тот же контейнер/конфиг с разными id. Начиная с v1.2.32 панель дедуплицирует профили по container + confPath + iface + clientsPath, а также чистит дубли при чтении/сохранении instances.json. Обновите панель из GitHub и сделайте жёсткое обновление страницы.

Если проверка на сервере показывает два разных контейнера, например amnezia-awg2 и amnezia-awg, с разными портами и разным числом клиентов — это не дубль, а два инстанса. Начиная с v1.2.33 карточки используют реальное имя профиля (label), чтобы AmneziaWG 2.0 и AmneziaWG не выглядели одинаково.

Если переключатель «Инстанс» показывает правильный контейнер, но таблица «Пользователи» остаётся от другого инстанса, обновите до v1.2.34. Клиентские запросы (/api/clients и операции над пользователями) теперь всегда передают явный profileId, а не полагаются только на cookie выбранного профиля.

Если клиенты есть в awg0.conf, но не отображаются из-за отсутствия/нестандартного clientsTable, обновите до v1.2.35. Таблица «Пользователи» теперь показывает объединение clientsTable + [Peer] из серверного конфига. Такие строки помечаются подсказкой: для экспорта .conf нужно импортировать клиентский .conf через блок «Импорт клиента».

Начиная с v1.2.36 в блоке «Пользователи» есть кнопка «Подтянуть из awg0.conf». Она создаёт недостающие строки clientsTable для уже активных [Peer], которые были созданы в приложении Amnezia. VPN-конфиг и контейнер не пересоздаются. Экспорт .conf для таких пользователей появится только после импорта их клиентского .conf, потому приватный ключ клиента хранится в приложении, а не на сервере.

Начиная с v1.2.37 парсер clientsTable поддерживает не только массив, но и object/map/nested-форматы разных установок Amnezia. Для диагностики источников есть GET /api/clients/source-report?profileId=...: показывает текущий контейнер, пути, количество [Peer], количество строк clientsTable, missing/table-only счётчики и короткие префиксы ключей без публикации полных ключей.

Начиная с v1.2.38 панель сама выбирает рабочие пути внутри контейнера: среди /opt/amnezia/awg/awg0.conf, /opt/amnezia/awg/wg0.conf, /opt/amnezia/wireguard/wg0.conf берётся конфиг с максимальным числом [Peer]; среди /opt/amnezia/awg/clientsTable и /opt/amnezia/wireguard/clientsTable берётся таблица с максимальным числом клиентов. Это закрывает установки, где приложение Amnezia создало старых клиентов в wg0.conf, а не в awg0.conf.

Начиная с v1.2.39 панель auto-detect делает не только для путей, но и для binary внутри контейнера. Если профиль указывает wgBinary=awg, а в контейнере есть только wg, команды show, pubkey, genkey, syncconf используют найденный binary. Это закрывает ошибку sh: awg: not found на контейнерах вида amneziawg.

Лендинг не поднимается (порт 80 занят)

При ошибке bind :80 используйте при установке SKIP_LANDING=1 или LANDING_PORT=8081 — админка на HOST_PORT (например 8080) от этого не зависит.

Публичная страница и админка

• http://IP:LANDING_PORT (часто 80) — статический nginx из каталога landing/: инструкция, переход в админку, напоминание написать администратору вашего сервера, дисклеймер. Ссылок на донат и автора репозитория здесь нет.
• http://IP:HOST_PORT (часто 8080) — сама панель (public/). Футер со ссылками автора (GitHub, Boosty и т.д.) только здесь, внизу после таблицы клиентов.

Файл landing/admin-port.js пересобирается установщиком и задаёт порт админки для кнопки на лендинге.

Cloudflare WARP: нужно ли ставить

Нет, если обычного VPN достаточно. WARP — дополнительная опция «выход в интернет через Cloudflare» для отмеченных в панели клиентов (IPv4 вида 10.8.x.x/32).

Задача	Действие
WARP не нужен	Ничего не устанавливайте; раздел в вебе с текстом «Не установлен» можно игнорировать.
Включить WARP	На VPS под root: bash scripts/warp-amnezia.sh install из каталога репозитория, затем настройка галочек в панели и «Применить» — см. README.
Полностью убрать WARP	./scripts/warp-amnezia.sh uninstall на хосте; учёт wgcf в /root/ при желании удалите вручную.

Скрытие разделов в панели (UI_HIDE_*)

Переменные контейнера amnezia-admin: UI_HIDE_SECTIONS (список users, warp, cascade, mtproto) или отдельно UI_HIDE_USERS, UI_HIDE_WARP, UI_HIDE_CASCADE, UI_HIDE_MTPROTO (1 / true). Подробности и пример — в таблице установки и разделе README про UI_HIDE_*.

• warp — скрывает блок WARP; POST /api/warp/* → 403.
• cascade — скрывает каскад; POST /api/clients/create-cascade → 403.
• users — скрывает таблицу «Пользователи» и отладку awg show; GET /api/clients и остальные операции с клиентами остаются (скрыт только UI таблицы).
• mtproto или UI_HIDE_MTPROTO — скрывает блок MTProto; GET/POST /api/mtproto/* → 403.

Конфигурации клиентов

• Старые строки без last_config — полный .conf с сервера собрать нельзя (нет приватного ключа). Используйте приложение Amnezia или блок «Новый клиент под каскад» (новый ключ на сервере).
• Экспорт по кнопкам — только если в clientsTable есть userData.last_config с полем config или client_priv_key.
• Импорт из приложения Amnezia — откройте блок «Импорт клиента», выберите нужный «Инстанс», вставьте клиентский .conf или JSON backup, где внутри есть такой .conf, и нажмите импорт. Если peer уже есть в awg0.conf, панель не создаёт дубль, а только восстанавливает/обновляет строку в clientsTable.

Экспорт: имя файла и прямая ссылка

Ответ GET /api/clients/export-config отдаёт заголовок Content-Disposition: attachment; filename="…". В Node.js значение заголовка должно быть в ASCII: кириллическое имя клиента в приложении не попадает в имя файла как есть — используется безопасная подстановка (латиница из имени или короткий префикс от clientId), чтобы не было ошибки вида Invalid character in header content. Содержимое .conf при этом остаётся полным UTF-8 текстом.

Прямая ссылка в браузере работает при активной cookie-сессии после входа или с ?token=…, если задан EXPORT_CONFIG_SECRET.

HTTP API (все маршруты под /, кроме статики)

Требуют cookie-сессии после POST /api/login, если не указано иное.

Метод	Путь	Назначение
GET	/health	Проверка живости; JSON { ok, version } — version из package.json образа
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/clients/import-config	{ "configText", "clientName?", "profileId?" } — импорт клиента из .conf или JSON backup с вложенным .conf
POST	/api/warp/host-setup	Установка/удаление WARP на хосте по SSH: { "rootPassword", "cmd": "install" | "uninstall" } (как синхронизация времени; каталог скрипта — WARP_SSH_INSTALL_DIR)
POST	/api/warp/start	Поднять WARP
POST	/api/warp/stop	Остановить WARP
POST	/api/warp/routing	Политика по клиентам
GET	/api/mtproto/status	Состояние MTProto‑контейнера и tg://proxy; ?withLogs=1 — хвост логов (logsFetched)
GET	/api/mtproto/logs	Хвост docker logs прокси
GET	/api/mtproto/tail	То же для прокси, обрезающего путь …/logs
POST	/api/mtproto/install	Установить/обновить контейнер (тело {})
POST	/api/mtproto/restart	Перезапустить контейнер
POST	/api/mtproto/remove	Удалить контейнер
GET	/api/server-time	Время и подсказки по поясам
GET	/api/time-sync-capabilities	Доступность синхронизации по SSH
POST	/api/sync-host-time	Запись времени на хост через SSH

Подробности переменных окружения — в таблице установки в README.