MeshCore-Posadmesh/posadmesh-docs/web-panel.md

# Веб-панель репитера

Эта страница предназначена для конечных пользователей, которые используют сборку PosadMesh `*_repeater_mqtt` с включённой локальной веб-панелью.

Здесь описано, как открыть панель, что делает каждый раздел и чего ожидать при работе с ней на компьютере или мобильном устройстве.

## С чего начать

Для обычного первого использования:

1. Подключите репитер к Wi-Fi.
2. Выполните `get wifi.status`, чтобы узнать его IP-адрес.
3. Откройте `https://<repeater-ip>/` в браузере.
4. Примите предупреждение о самоподписанном сертификате.
5. Войдите с паролем администратора репитера.
6. Используйте панель для настройки или диагностики.
7. По завершении выполните `set web off`, если репитеру нужен максимальный запас heap для MQTT.

Большинству пользователей панель нужна только для первой настройки, редких изменений параметров и диагностики. Оставляйте её включённой только тогда, когда доступ из браузера стоит дополнительного расхода памяти.

## Что это такое

Веб-панель репитера — это локальная страница настройки по HTTPS, которую репитер отдаёт напрямую по Wi-Fi.

Она предоставляет:

- локальную страницу администратора за паролем по адресу `/app`
- отдельную страницу статистики и трендов по адресу `/stats`
- быстрые команды `get` для типовых проверок репитера и MQTT
- панель CLI в стиле терминала для полного доступа к CLI репитера
- редактируемые настройки репитера
- редактируемые настройки MQTT
- просмотр исторической статистики с трендами, соседями и последними событиями

Рекомендации по эксплуатации:

- используйте её для первоначальной настройки, редких изменений конфигурации и диагностики
- по завершении предпочитайте `set web off` на MQTT-репитерах, которым нужен максимальный запас
- это оставляет больше внутреннего heap для работы MQTT/WSS, особенно в конфигурациях с двумя брокерами

## Типовые задачи

### Проверить Wi-Fi и MQTT

1. Откройте панель.
2. Нажмите `wifi.status` в Quick `get` Commands.
3. Нажмите `mqtt.status` в Quick `get` Commands.
4. Откройте `/stats` из верхней навигации для просмотра исторической статистики.

### Изменить имя устройства

1. Отредактируйте `Device Name`.
2. Нажмите `Save`.
3. Подтвердите сгенерированную команду и ответ в поле терминала CLI.

### Обновить владельца или email MQTT

1. Перейдите в `MQTT Settings`.
2. Введите новое значение.
3. Нажмите `Save`.
4. Используйте кнопку обновления, если хотите перечитать сохранённое значение из репитера.

## Обзор скриншотов

Скриншоты ниже показывают текущее разделение между более лёгкой страницей администратора `/app` и отдельной страницей статуса `/stats`.

### Скриншот `/app`

![Обзор веб-панели репитера `/app`](./_assets/repeater_web_panel_app_light.png#only-light)
![Обзор веб-панели репитера `/app`](./_assets/repeater_web_panel_app_dark.png#only-dark)

### Скриншот `/stats`

![Обзор веб-панели репитера `/stats`](./_assets/repeater_web_panel_stats_light.png#only-light)
![Обзор веб-панели репитера `/stats`](./_assets/repeater_web_panel_stats_dark.png#only-dark)

## Требования

Вам потребуется:

- поддерживаемая сборка прошивки `*_repeater_mqtt`
- настроенный на репитере Wi-Fi
- репитер, подключённый к вашей локальной сети
- пароль администратора репитера

Некоторые ограниченные по ресурсам таргеты отключают веб-панель, чтобы уложиться в лимиты flash. Если ваша плата её не поддерживает, `get web.status` не покажет её как доступную.

## Как её открыть

1. Подключите репитер к Wi-Fi.
2. Узнайте его IP-адрес.
3. Откройте `https://<repeater-ip>/` в браузере.
4. Примите предупреждение браузера о самоподписанном сертификате.
5. Введите пароль администратора репитера.

Полезные команды CLI:

- `get wifi.status`: показывает состояние Wi-Fi, IP-адрес, канал и уровень сигнала при подключении.
- `get web.status`: показывает, запущена ли веб-панель и какой URL использовать.

Пример:

- `https://10.33.135.208/`

## Вход и безопасность

- панель использует тот же пароль администратора, что и CLI репитера
- соединение идёт по HTTPS, но сертификат самоподписанный
- браузеры будут предупреждать при первом подключении
- после входа панель открывает доступ к CLI репитера
- браузер сохраняет токен сессии при переключении между `/app` и `/stats`; страница переключает представления на месте до выхода, блокировки по бездействию или перезапуска устройства
- кратковременные пропадания Wi-Fi могут прервать загрузку страницы, но не должны требовать нового входа при перезапуске веб-панели
- после перезапуска или перепрошивки устройства приложение проверяет сохранённый токен перед загрузкой настроек и возвращается к экрану входа, если сессия устарела

Это предназначено для локального административного использования в доверенной сети, а не для открытого доступа из интернета.

## Примечания по производительности

Панель спроектирована так, чтобы загружаться мягче, чем более ранние версии. При входе она теперь запрашивает разделы последовательно, а не запрашивает сразу один большой bootstrap payload.

Даже с этим изменением панель по-прежнему использует HTTPS и внутренний heap. На платах с одним или двумя брокерами WSS MQTT открытие панели уменьшает запас MQTT на время активной сессии.

Рекомендуемая практика для развёртываний репитера:

- включайте панель для первоначальной настройки
- используйте её снова для редких проверок или диагностики
- отключайте её командой `set web off` по завершении, чтобы у MQTT было максимально возможное свободное место

## Навигация и действия

У веб-консоли теперь две основные страницы:

- `/app`: более лёгкое представление для управления и настройки
- `/stats`: текущий статус, тренды, соседи и последние события

Обе страницы используют одну и ту же верхнюю навигацию и служебные действия.

### `/app`

Страница `/app` — это основная область администрирования и настройки.

Она включает:

- переход к `App` и `Stats`
- `Advert`
- `Start OTA`
- `Reboot`
- переключатель темы
- `Logout`

Используйте `Start OTA` только тогда, когда собираетесь обновить прошивку.

Если браузер может получить манифест прошивки PosadMesh flasher, страница приложения сверяет версию релиза PosadMesh из `mqtt.client_version` с опубликованными релизами MeshCore-Posadmesh. Когда доступен более новый тег релиза PosadMesh, в верхней части страницы появляется уведомление об обновлении прошивки.

Для сборок, включающих `CLIENT_ENV`, уведомление может показывать `Update now`. Это скачивает соответствующий не объединённый `.bin` с зеркала прошивок PosadMesh flasher, показывает прогресс в баннере, загружает прошивку через веб-панель HTTPS и позволяет устройству перезагрузиться. Для этого требуются заголовки CORS на путях `/firmwares/` flasher.

### `/stats`

Страница `/stats` — это основное место для текущего статуса и исторического обзора.

Она включает:

- переход к `App` и `Stats`
- `Refresh`
- `Reboot`
- переключатель темы
- `Logout`

## Быстрые команды "get"

Этот раздел выполняет типовые команды только для чтения для:

- Wi-Fi
- MQTT

Они полезны для быстрых проверок без ввода в поле CLI. Быстрые действия MQTT включают `mqtt.status`, `mqtt.client_version`, `mqtt.iata`, `mqtt.owner` и `mqtt.email`.

## Выполнить команду CLI

Это небольшой терминал для CLI репитера.

- нажмите `Enter`, чтобы выполнить команду
- история команд отображается в поле терминала ниже
- кнопки сохранения в других частях страницы также показывают здесь сгенерированную команду и ответ
- `clock` доступна здесь, если вы хотите проверить текущее время платы репитера
- аутентифицированные сессии могут выполнять те же команды CLI, которые принимает репитер

Это позволяет легко увидеть, что именно панель отправила репитеру.

## Настройки репитера

В этот раздел входят:

- Device Name
- Clock UTC
- Latitude
- Longitude
- Guest Password
- Private Key
- Advert Interval
- Flood Interval
- Scoped Flood Max
- Unscoped Flood Max
- Owner Info

Примечания:

- `Latitude` и `Longitude` по умолчанию равны `0.0` как заполнители
- изменение приватного ключа требует перезагрузки для применения
- кнопки обновления загружают текущее значение из репитера
- кнопки сохранения немедленно отправляют соответствующую команду CLI

## Настройки радио и регионы

Раздел `Radio Settings` включает селектор community-пресета радио, режим path hash и работу с деревом регионов узла. Список регионов строится из уже разрешённых на узле регионов; нажатие `Save` разрешает выбранный регион вместе с его базовым регионом и сохраняет карту регионов командой `region save`.

## Информация

Этот раздел показывает:

- `Version`: версия прошивки с датой сборки
- `Client Version`: строка версии MQTT-клиента
- `Public Key`

## Режим Ghost Node

Режим Ghost Node — это удобное управление на странице `/app` для репитера, который должен оставаться в Wi-Fi и MQTT, но не должен активно вести себя как ещё один репитер поблизости.

Типичный сценарий использования:

- MQTT-MQTT-репитер в помещении или в одном месте с другим устройством, когда соседний репитер уже выполняет работу по RF-ретрансляции
- узел, который вы хотите использовать для передачи данных в MQTT, веб-статуса и диагностики, не добавляя при этом лишний трафик ретрансляции или advert-пакеты

Когда режим Ghost Node включён, он:

- отключает `repeat`
- устанавливает `advert.interval` в `0`
- устанавливает `flood.advert.interval` в `0`
- оставляет работающими локальную веб-панель и функции MQTT

Когда он отключён, панель восстанавливает предыдущие настройки repeat и advert, если она всё ещё знает их из текущей сессии браузера. Если нет, она возвращается к:

- `repeat on`
- `advert.interval 60`
- `flood.advert.interval 12`

Этот режим полезен, когда вы хотите, чтобы устройство наблюдало и публиковало данные, а не выступало дополнительным RF-репитером. Он не создаёт отдельную роль прошивки; это просто сгруппированный ярлык веб-панели для этих существующих настроек.

## Настройки MQTT

В этот раздел входят:

- `mqtt.iata`: выбирается из подготовленного списка восточного побережья/юго-востока.
- `mqtt.owner`: публичный ключ владельца.
- `mqtt.email`: контактный email владельца.
- Брокеры MQTT: переключатель **MeshCoreTel RU** и переключатель **Custom broker**, каждый включает или отключает свой брокер. Одновременно можно включить не более двух брокеров.
- поля custom MQTT `host:port`, транспорт TCP/WSS, имя пользователя и пароль.

`UNSET - To be configured` — значение по умолчанию для новых установок MQTT-репитера, пока не появится реальное сохранённое значение.

Примечания:

- когда `mqtt.iata` имеет значение `UNSET`, панель показывает в верхней части баннер с напоминанием задать его в MQTT Settings
- пока `mqtt.iata` имеет значение `UNSET`, включённые брокеры MQTT не пытаются подключиться
- текущие состояния серверов MQTT загружаются при открытии страницы
- вы можете включать или отключать каждый сервер MQTT из этой панели
- custom MQTT использует настроенные имя пользователя и пароль, а не аутентификацию JWT
- custom MQTT по умолчанию использует TCP; выберите WSS для MQTT через защищённые WebSockets с фиксированным websocket-путём `/mqtt` и корневым CA-бандлом x509 из ESP-IDF
- отключение подключённого сервера MQTT публикует retained-статус offline до отключения клиента
- изменение `mqtt.iata` с настроенного значения публикует retained-статус offline в старый топик статуса, перезапускает подключённых клиентов брокера и переподключается по новому пути топика
- одновременно можно включить не более двух брокеров MQTT

## Обзор `/stats`

Страница статистики загружается отдельно от `/app` и предназначена для того, чтобы основная страница администратора оставалась легче.

Страница `/stats` сейчас показывает:

- `Services`: MQTT, web, архив, число соседей и, когда смонтирована, ёмкость карты и архива
- необязательная сводная карточка `Environment` на всю ширину на платах, которые передают телеметрию GPS или параметров окружающей среды
- `Trends`: батарея, свободный heap, активность пакетов, сигнал, уровень шума и, когда GPS активен, спутники
- `Neighbours`: текущая таблица соседей с ID, SNR, давностью последнего приёма и давностью advert
- `Events`: текущие события загрузки/сессии

Запланированные ротации MQTT JWT показываются как события `mqtt_token_refreshed` вместо короткой пары `mqtt_disconnected` / `mqtt_connected`.

Для плат, которые предоставляют дополнительную телеметрию, необязательная сводная карточка `Environment` может показывать текущие значения, такие как состояние активности/fix GPS, широта, долгота, высота по GPS, напряжение, температура датчика, влажность, барометр, высота по давлению и температура MCU.

Метрики без текущего значения скрываются, а не отображаются строками-заполнителями, поэтому карточки различаются в зависимости от платы и текущего состояния датчиков.

Индикатор батареи `Core` предпочитает процент батареи, сообщаемый платой, когда таргет его предоставляет. На таких платах детализация индикатора показывает только текущее значение напряжения батареи в милливольтах. В противном случае он масштабирует отображаемый процент из настроенного для платы диапазона напряжения батареи и показывает этот диапазон в тексте детализации, а не предполагает фиксированную однобаночную сборку `3000-4200 mV`.

Графики трендов загружаются последовательно, а не одним большим payload:

1. сводка/статус
2. батарея
3. память
4. активность пакетов
5. сигнал
6. спутники, когда GPS активен

Это снижает потребление памяти как на стороне браузера, так и на стороне устройства по сравнению с предыдущим представлением статистики внутри страницы.

Если `web.stats` включён и архив на SD смонтирован, тренды могут восстановить архивные сводные точки после перезагрузки из последнего снимка SD. Недавние живые точки по-прежнему добавляются из истории в памяти.

### Ёмкость истории статистики

Выборки статистики собираются раз в минуту.

Текущие лимиты истории в памяти:

| Класс платы                       | Лимит выборок | Лимит событий | Примерная история выборок      |
| --------------------------------- | ------------: | ------------: | ------------------------------ |
| Без PSRAM                         |          `24` |           `8` | Только недавняя живая история  |
| Менее `4 MB` PSRAM                |         `240` |          `96` | Около `4` часов                |
| От `4 MB` до менее `8 MB` PSRAM   |         `480` |         `192` | Около `8` часов                |
| `8 MB` PSRAM или больше           |         `720` |         `288` | Около `12` часов               |

Когда `web.stats` включён, история статистики начинает собираться с момента загрузки или с момента его включения, даже если `/stats` ещё не открывалась. Платы без PSRAM используют меньший буфер только с живыми данными, показанный выше.

Восстановление из архива требует включённого `web.stats` и смонтированной SD-карты на платах, которые поддерживают путь архива PosadMesh.

Если доступ к архиву пропадает во время работы, репитер периодически повторяет монтирование SD, пока `web.stats` остаётся включённым.

Основное назначение SD-карты — позволить репитеру сохранять и восстанавливать историю статистики для `/stats`. Архив хранит быстрые файлы снимков `.latest` для быстрого восстановления и ежедневные файлы `.log` с датой в UTC для более долгой истории. Как дополнительная возможность, эти файлы также можно извлечь и просмотреть на компьютере для более глубокого ручного анализа.

На платах без PSRAM `/stats` всё ещё может показывать недавние графики, но история меньше и не обеспечивает такого же поведения с опорой на архив, как платы с поддержкой PSRAM.

Полезные команды CLI:

- `set web.stats on`
- `set web.stats off`
- `get web.stats.status`

## Использование на мобильных устройствах

Страница адаптивная и должна нормально работать на телефоне.

На мобильном:

- кнопки быстрых команд сворачиваются в двухколоночную раскладку
- верхняя навигация и группы действий остаются компактными и удобными для касания
- строки ввода остаются пригодными для взаимодействия касанием
- карточки трендов при необходимости перестраиваются в одноколоночные секции

## Дополнительные задачи

### Start OTA

1. Нажмите `Start OTA`.
2. Подтвердите действие.
3. Панель запускает OTA, ждёт, пока HTTP-слушатель OTA займёт порт `80`, а затем открывает возвращённый URL `http://.../update`.
4. Локальный HTTP-слушатель перенаправления на порту `80` освобождается, чтобы OTA мог занять этот порт.
5. Продолжите по обычному сценарию OTA.

Если репитер уже подключён к Wi-Fi, OTA использует существующий адрес в локальной сети. Если Wi-Fi не подключён, репитер запускает точку доступа `MeshCore-OTA` и возвращает вместо этого адрес OTA.
Если старый слушатель перенаправления не полностью освободил порт `80`, слушатель OTA повторяет попытки примерно до 30 секунд, после чего сдаётся.

Если более старая сборка отправляет вас на странное перенаправление после `start ota`, используйте веб-кнопку `Start OTA` для запуска обновления. В актуальных сборках эта проблема с перенаправлением исправлена.

### Purge SD

`Purge SD` отображается красным встроенным текстом рядом с `Archive Used` в карточке Services на `/stats`. Запрашивает подтверждение, а затем выполняет аутентифицированную команду `purge sd`.

Это удаляет файлы и каталоги из архива на смонтированной SD-карте, после чего заново создаёт пустой каталог архива `/stats` для продолжения записи во время работы. Это не стирает внутреннюю файловую систему репитера, идентичность, prefs, регионы, настройки радио или настройки MQTT.

### Использовать историческую статистику

1. При необходимости включите статистику командой `set web.stats on`.
2. Откройте `/stats` из верхней навигации.
3. Просмотрите `Services` для состояния архива и работы.
4. Просмотрите `Trends` для недавней истории графиков.
5. Используйте `Refresh`, чтобы перезагрузить страницу статистики.

## Диагностика

### Браузер предупреждает о сертификате

Это ожидаемо. Панель использует самоподписанный сертификат, созданный для локального использования.

### Я не могу открыть страницу

Проверьте:

- репитер подключён к Wi-Fi
- IP-адрес из `get wifi.status`
- `get web.status` сообщает, что панель запущена
- ваша плата/таргет прошивки поддерживает веб-панель

### Панель открывается, но вход не удаётся

Используйте пароль администратора репитера, а не гостевой пароль.

### MQTT становится нестабильным при входе

Веб-панель теперь загружает настройки раздел за разделом, чтобы снизить нагрузку при запуске, но HTTPS всё равно расходует внутренний heap.

Проверьте:

- включён ли один или два брокера MQTT
- `memory` до и после входа
- улучшается ли стабильность после `set web off`

Для стационарных установок, где время работы MQTT важнее доступа из браузера, используйте панель недолго, а затем снова отключите её.

### Открывается HTTP вместо HTTPS

Теперь репитер перенаправляет обычные запросы `http://` на локальный URL панели `https://`. Если после перенаправления браузер всё ещё показывает проблему с подключением, откройте `https://<repeater-ip>/` напрямую и сначала примите предупреждение о самоподписанном сертификате.

### Статистика или настройки не обновляются

Попробуйте:

- обновить вкладку браузера
- использовать `Refresh` на `/stats`
- выйти и войти снова
- проверить стабильность Wi-Fi с помощью `get wifi.status`

### `/stats` недоступна

Проверьте:

- `get web.status`
- `get web.stats.status`
- была ли применена команда `set web.stats on`

Если `web.stats` отключён, `/stats` останется отключённой, и запросы исторических графиков выполняться не будут.

## См. также

- [Пользовательские команды CLI](./custom-cli.md)
- [Скачать и прошить релизы](./releases.md)
- [Локальная сборка с uv](./local-builds.md)