Meshyface

Meshyface — это чат-ориентированная панель управления Meshtastic, которая работает как один Python-сервис и предоставляет одностраничный веб-интерфейс по HTTP.

Текущая функциональность приложения

Текущий интерфейс предоставляет:

• Чат и прямые разговоры с узлами
• Рабочее пространство сети: карта, обзор, связи, маршруты, датчики, Топ-10, детали узлов и история по запросу
• Рабочее пространство консоли: вывод пакетов/логов в реальном времени
• Рабочее пространство приложений: Игры и вкладка Файлы (при включённой передаче файлов)
• Рабочее пространство настроек: панели радио, устройства, подключения, местоположения, каналов, тикеров, списков, внешнего вида и о программе
• История на SQLite, поиск, сводки, сохранение темы и сохранение пользовательских правил телеметрии

Рабочее пространство консоли

Рабочее пространство консоли — это управляющая поверхность в стиле терминала для пакетного трафика, поиска по истории и утилит сети.

• Введите имя команды, чтобы открыть подсказки автодополнения. Используйте Tab или Enter для принятия, ArrowRight для принятия призрачного суффикса, и ArrowUp / ArrowDown для перемещения по всплывающему окну.
• Команды, принимающие цель-узел, показывают подробные предложения узлов с именем, ID, эмодзи, тегом, статусом, прыжками, GPS, временем последнего приёма, портами и номером узла. Обычный текст сужает поиск по именам и тегам узлов; ! сужает по ID узла.
• live транслирует пакетный трафик до нажатия Ctrl+C или q. Используйте live grep <текст>, live rg <текст>, live filter=<текст> или просто live <текст>, чтобы транслировать только соответствующие группы пакетов. Фильтры уровня и детализации всё ещё применяются, например live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <текст> и rg <текст> ищут в сохранённой истории пакетов/чата с окнами контекста, лимитами, фильтрами источника пакетов/чата и фильтрами области сводки/пакета.
• /search <текст> фильтрует видимый вывод консоли из приглашения, не запуская поиск по сохранённой истории.

Скриншоты

Карта сети в реальном времени

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

Обзор сети

Вид истории для количества узлов, статуса онлайн, новых узлов и отчётов о местоположении.

Топология связей

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

Трассировка маршрута

Вид трассировки для источника, назначения, ближайших связей и деталей пакетов по прыжкам.

История датчиков

Диаграмма телеметрии, сравнивающая историю датчиков для нескольких узлов.

Карточки статуса

Верхние карточки: активность радио, количество узлов, пакеты, связи, батарея и использование каналов.

Настройка тем

Темы могут преобразить всю панель управления с помощью пользовательских цветов, градиентов, прозрачности, размытия, шрифтов, частиц или фона с живой картой. Эти примеры палитр — пользовательские темы; выберите любой превью, чтобы открыть полноразмерный скриншот.

Сигнальный зелёный	Неоновый малиновый	Реле Авроры

Общие внешние виды узлов

Узлы Meshyface могут обмениваться компактными пакетами внешнего вида, содержащими рецепт темы узла и необязательный призрак или водяной знак. Настройте и просмотрите свой узел в Настройки > Внешний вид > Внешний вид узла, включите Делиться внешним видом узла, затем используйте Транслировать внешний вид для публикации.

• Пакеты внешнего вида используют настроенный канал отправки профилей и наследуют настройку лимита прыжков радио; Meshyface не накладывает отдельный лимит прыжков.
• Полученные внешние виды могут стилизовать идентичности узлов в чате, списках, деталях узлов, картах, графиках, датчиках и тикерах без замены собственной темы принимающей панели.
• Отключение Делиться внешним видом узла отключает обе стороны функции. Оно останавливает трансляции и обходит путь получения профилей до того, как входящие полезные нагрузки внешнего вида будут декодированы, кэшированы или сохранены; кэшированные общие внешние виды очищаются, и ни один полученный внешний вид не отображается.
• Когда история включена, полученные профили и локальная настройка обмена сохраняются в базе данных SQLite истории.
• Общие внешние виды — это косметические метаданные. Полученный внешний вид не меняет настройки радио, каналы или сохранённый пакет темы панели.

Архитектура системы

flowchart LR
  Browser["Browser<br/>single-page UI"]
  CDN["Vendored browser assets<br/>Leaflet + leaflet.heat + particles.js"]
  Tiles["Basemap provider<br/>OpenStreetMap tile service"]
  Server["ThreadingHTTPServer<br/>HTML shell + JSON API"]
  Assets["Python template assembly<br/>meshdash/html* + meshdash/assets/*"]
  State["State loaders<br/>live snapshot + history readers"]
  Services["Write services<br/>chat, settings, tools, games, optional files"]
  Tracker["DashboardTracker<br/>live receive path + in-memory buffers"]
  History["HistoryStore / SQLite (WAL)<br/>chat, packets, rollups, settings"]
  Radio["Meshtastic interface<br/>serial or TCP"]
  Mesh["Meshtastic radio / mesh"]
  Atlas["Bundled offline atlas<br/>reference basemap fallback"]

  Browser -->|GET /| Server
  Browser -->|GET /api/*| Server
  Browser -->|POST write APIs| Server
  Browser --> CDN
  Browser --> Tiles
  Browser -->|fallback basemap data| Atlas
  Server --> Assets
  Server --> State
  Server --> Services
  State <--> Tracker
  State <--> History
  Services <--> History
  Services <--> Radio
  Radio <--> Mesh
  Radio -->|receive callbacks| Tracker

Установка

Начните с предварительных требований и зависимостей, затем выберите один путь установки:

• Ручной запуск на переднем плане: клонируйте в любое место и запустите панель напрямую.
• Рекомендуемый сервис systemd: клонируйте в /opt/meshyface для постоянного хоста с обновлением через GitHub.
• Docker: запустите ту же точку входа приложения в контейнере с монтированием /data для постоянного состояния.
• Развёртывание с рабочей станции через push: скопируйте локальную копию на целевой хост по SSH.
• Топология выполнения Proxmox: выберите размещение радио через TCP или USB для установки в VM/LXC.
• Офлайн-пакеты карт: добавьте подробные локальные данные карт для изолированных или слабосвязанных панелей.

Данные и хранение

Общая база данных истории

--history-db — это имя файла SQLite на диске. Панель больше не добавляет суффикс подключённого радио, поэтому любое радио, подключённое к панели, вносит вклад в одну и ту же сохранённую историю пакетов, чата, узлов и сводок.

Режимы истории

• Режим по умолчанию сохраняет в SQLite чат, пакеты, события подключения, аналитику узлов, записи о некорректном тексте, метрики окружения и сводки.
• --no-history отключает постоянное хранилище и оставляет только буферы в памяти в реальном времени.
• Сводки также собираются в фоне, когда панель запущена и история включена.

Тема и локальные настройки

• Выбор предустановленной темы сохраняется в mesh_dashboard_theme_settings.json по умолчанию, или в файл, указанный через --theme-settings-file.
• Пользовательские правила телеметрии сохраняются в базе данных SQLite истории.

Команды обслуживания

Эксплуатационные команды для проверки или восстановления локальных данных панели описаны в docs/maintenance.md.

Семантика представления связей

Подпредставление Связи — это вид топологии, а не воспроизведение маршрутов пакетов.

• Режим История использует сохранённую историю связей в SQLite.
• Режим В реальном времени использует только наблюдения связей текущего сеанса.
• Пронумерованные кольца показывают кратчайшее расстояние в графе от текущего корня с помощью поиска в ширину по наблюдаемому графу связей.
• Эти номера колец не являются буквальными прыжками пересылки Meshtastic и не являются трассировкой пакетов в реальном времени.
• Метаданные прыжков пакетов, если доступны, показываются отдельно в деталях узла или ребра как значения прыжков пакетов.

Текущий корень — это узел, вокруг которого центрирован граф. Выбор другого узла меняет корень и пересчитывает пронумерованные кольца расстояний от этого узла.

Справочник по конфигурации

Подключение и транспорт

• --mesh-host <ip-адрес-или-dns>: хост TCP-радио
• --mesh-tcp-port <порт>: порт TCP-радио, по умолчанию 4403
• --mesh-port <путь>: путь к последовательному устройству
• --default-gateway-host <хост>: резервный TCP-хост, если --mesh-host не указан и последовательный порт всё ещё на пути по умолчанию
• --default-gateway-port <порт>: резервный TCP-порт для --default-gateway-host
• --no-default-gateway: принудительно использовать последовательный порт, если --mesh-host явно не указан

Связанные переменные окружения:

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT для пути последовательного порта по умолчанию

HTTP, UI и безопасность

• --http-host <хост>: хост привязки, по умолчанию 0.0.0.0
• --http-port <порт>: порт привязки, по умолчанию 8877
• --refresh-ms <мс>: интервал опроса браузера, по умолчанию 3000
• --packet-limit <n>: размер буфера недавних живых пакетов, по умолчанию 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets: отображать приватные ключи/пароли/PSK в панелях сырого JSON
• --debug-mode / --no-debug-mode: открывать отладочные поверхности панели, такие как расширенная диагностика сети

Связанные переменные окружения:

• MESH_DASH_PRIVATE_MODE
• MESH_DASH_API_TOKEN
• MESH_DASH_GAMES_ENABLE
• MESH_DASH_VERSION
• MESH_DASH_GIT_COMMIT
• MESH_DASH_PR_NUMBER

Идентификация времени выполнения берётся из 12-символьного коммита git, за которым следует необязательный номер запроса на слияние, например abc123456789 · PR #43. Панель Программное обеспечение отображает эту единственную ревизию вместо версии пакета. Темы коммитов слияния/squash GitHub определяются автоматически; для непротестированных превью-развёртываний можно явно установить MESH_DASH_PR_NUMBER.

/api/revision — каноническая конечная точка идентификации. Её поля revision и build_ref сообщают версию времени выполнения, в то время как commit и pr_number остаются доступными как структурированные поля. /api/version остаётся устаревшей конечной точкой, и её поле version сохраняет метаданные релиза/пакета. MESH_DASH_VERSION также зарезервировано для явной упаковки релиза и не отображается в панели.

Передача файлов

• --file-transfer-enable: включить приложение Файлы; требует --accept-file-transfer-traffic-disclaimer
• --file-transfer-auto-accept: принимать прямые входящие передачи без подтверждения в браузере
• --file-transfer-max-bytes <байты>: лимит на файл, по умолчанию 65536, ограничен 1024-524288

Передачи используют бета-протокол MF_FILE_V2 на частном порту 258 и несовместимы с предыдущим транспортом текстовых сообщений. Когда у цели есть пригодное обнаруженное количество прыжков, Meshyface использует это количество плюс один, ограниченное настроенным лимитом прыжков радио. Данные о прыжках старше одного часа возвращаются к настроенному лимиту. Приложение Файлы отображает выбранный лимит и его источник.

Связанные переменные окружения:

• MESH_DASH_FILE_TRANSFER_ENABLE
• MESH_DASH_FILE_TRANSFER_AUTO_ACCEPT
• MESH_DASH_FILE_TRANSFER_MAX_BYTES
• MESH_DASH_ACCEPT_FILE_TRANSFER_TRAFFIC_DISCLAIMER

История и аналитика

• --history-db <путь>: базовый путь к БД SQLite
• --history-max-rows <n>: по умолчанию 200000
• --history-retention-days <дни>: по умолчанию 30, используйте 0 для отключения удаления по возрасту
• --history-event-max-rows <n>: лимит событий пакетов только на добавление, по умолчанию 200000
• --history-event-retention-days <дни>: по умолчанию 30
• --history-rollup-retention-days <дни>: по умолчанию 365
• --no-history: режим только в памяти

Связанные переменные окружения:

• MESH_DASH_HISTORY_DB

Темы

• --theme-presets <json>: необязательный файл пользовательских предустановок темы
• --theme-preset <имя>: имя выбранной предустановки
• --theme-settings-file <json>: файл сохраняемого выбора темы времени выполнения

Встроенные предустановки:

• default (безопасный синий Meshyface, частицы отключены)
• custom (демонстрационная тема с включёнными частицами и фоновыми эффектами)

Свежие установки по умолчанию используют default, если сохранённый файл настроек темы или MESH_DASH_THEME_PRESET не выбирают другую предустановку.

Связанные переменные окружения:

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

Безопасность

• Эта панель предназначена для доверенных сред LAN/VPN.
• Не выставляйте её напрямую в публичный интернет без обратного прокси и контроля доступа.
• Используйте --private-mode и/или токен API для более строгого контроля путей записи.
• Предпочитайте MESH_DASH_API_TOKEN вместо --api-token на общих или многопользовательских хостах. Токен командной строки может быть виден в списках процессов и сохранён в истории оболочки.
• Встроенная предустановка канала Join Meshyface использует намеренно публичный общий PSK Meshyface для совместимости между пользователями этого программного обеспечения. Не используйте этот публичный канал для частного трафика.
• --show-secrets раскрывает конфиденциальные значения в панелях сырого JSON; не включайте его без необходимости на общих дисплеях.
• Загрузки базы данных сырых пакетов могут раскрывать содержимое сообщений и телеметрии. На общих хостах требуйте токен API и используйте --no-allow-tokenless-raw-packet-download.
• Передача файлов может потреблять значительное эфирное время сети. Держите её отключённой, если вы явно не приняли этот компромисс.

Тестирование и покрытие

Запустите обычный набор тестов:

python -m pytest

Запустите Ruff так же, как CI:

scripts/run_ruff_local.sh

Запустите отчёт о покрытии приложения для ознакомления:

python -m pytest \
  --cov=meshdash \
  --cov=mesh_dashboard \
  --cov=mesh_connection \
  --cov-report=term

Запустите локальный шлюз покрытия с более строгим минимумом 85%:

scripts/run_coverage_local.sh

Запустите локальный тест отзывчивости GUI перед PR:

scripts/run_gui_responsiveness_local.sh

Покрытие намеренно исключает портированный пакет движка Zork из оценки, но автономный Zork и тесты маршрутизации всё равно запускаются. GitHub Actions публикует тот же отчёт о покрытии в виде комментария и артефакта PR. CI падает ниже 80%. Локальный шлюз остаётся на 5 процентных пунктов выше CI.