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](../README.md). |
| **Telegram MTProto‑прокси** | *Необязательно*, не часть AWG. Docker-контейнер официального образа **telegrammessenger/proxy**; установка из панели, ссылка **`tg://proxy`**, переменные **`MTPRO_*`** — см. основной [README](../README.md). |
| **Новый клиент под каскад** | Клиент в конфиге смотрит на **промежуточный узел** по Endpoint; peer и ключи создаются **на текущем VPS** и отдаются в `.conf`. На промежуточном сервере заранее нужен проброс порта DNAT UDP до WG этого VPS ([**kaskad_web_vpn**](https://github.com/andrey271192/kaskad_web_vpn) или свой проброс); в блоке см. текст и команду установки каскад-панели. |
| **Импорт клиента** | Перенос готового клиента из `.conf` или JSON backup Amnezia, если backup содержит текстовый конфиг. Панель восстанавливает строку в `clientsTable`, сохраняет `last_config` и добавляет peer только если его ещё нет в серверном конфиге. |
| **Пользователи** | Вкл/выкл peer, удаление, переименование, даты отключения; экспорт `.conf` если в записи есть `userData.last_config`. |

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

1. Проверьте переменную контейнера панели:
   ```bash
   docker inspect amnezia-admin --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^AWG_PROFILES='
   ```
2. Если строки нет, но `docker ps` показывает два контейнера вида `amnezia-awg*`, переустановите панель свежим установщиком из GitHub:
   ```bash
   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` через блок **«Импорт клиента»**.

## Лендинг не поднимается (порт 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](../README.md). |
| Полностью убрать 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](../README.md).