Meshyface

Meshyface 是一个以聊天优先的 Meshtastic 仪表盘，作为单个 Python 服务运行，并通过 HTTP 提供单页 Web UI。

当前应用界面

当前 UI 提供：

• 聊天及直接点对点对话
• 网络工作区，包含地图、概览、链路、路由、传感器、Top 10 排名、节点详情以及按需历史
• 控制台工作区，用于实时数据包/日志输出
• 应用工作区，包含游戏以及（启用文件传输时）文件选项卡
• 设置工作区，包含无线电、设备、连接、位置、频道、滚动消息、列表、外观以及关于窗格
• 基于 SQLite 的历史记录、搜索、汇总、主题持久化以及自定义遥测规则持久化

控制台工作区

控制台工作区是一个终端风格的控制面板，用于数据包流量、历史搜索和网格实用命令。

• 输入命令名称可打开自动补全建议。使用 Tab 或 Enter 接受，ArrowRight 接受幽灵后缀，ArrowUp / ArrowDown 在弹出菜单中移动。
• 接受节点目标的命令会显示丰富的节点建议，包含名称、ID、表情符号、标签、状态、跳数、GPS、最后听到状态、端口和节点编号。普通文本按节点名称和标签筛选；! 按节点 ID 筛选。
• live 实时显示数据包流量，直到 Ctrl+C 或 q。使用 live grep <text>、live rg <text>、live filter=<text> 或直接 live <text> 仅显示匹配的实时数据包组。层和详细程度过滤器仍然适用，例如 live rg TEXT_MESSAGE_APP -vv --layer=2。
• grep <text> 和 rg <text> 搜索已保留的数据包/聊天历史，支持上下文窗口、限制、数据包/聊天源过滤器以及摘要/数据包范围过滤器。
• /search <text> 从提示符过滤当前控制台输出，而不启动保留历史搜索。

截图

实时网络地图

地图视图，显示节点位置、链路、公共路径、集群和信号热力图。

网络概览

节点数量、在线状态、新节点和位置报告的历史视图。

链路拓扑

拓扑视图，显示从所选根节点观察到的链路。

路由追踪

源、目标、附近链路以及每跳数据包详情的追踪视图。

传感器历史

遥测图表，比较多个节点的传感器历史。

状态卡片

顶部卡片，显示无线电活动、节点数量、数据包、链路、电池和频道使用情况。

主题定制

主题可以重塑整个仪表盘，使用自定义颜色、渐变、透明度、模糊、字体、粒子效果或实时地图背景。以下示例调色板是自定义主题；点击任一预览可打开其全分辨率截图。

信号绿	霓虹品红	极光中继

共享节点外观

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 以持久化状态。
• 工作站推送部署：将本地检出的代码通过 SSH 复制到目标主机。
• Proxmox 运行时拓扑：为 VM/LXC 安装选择 TCP 或 USB 无线电位置。
• 离线地图包：为无网络或低连接仪表盘添加详细的本地地图数据。

数据和存储

共享历史数据库

--history-db 是最终磁盘上的 SQLite 文件名。仪表盘不再添加已连接无线电后缀，因此插入仪表盘的任何无线电都会贡献到同一个持久化的数据包、聊天、节点和汇总历史中。

历史模式

• 默认模式将聊天、数据包、连接事件、节点分析、格式错误文本记录、环境指标和摘要汇总持久化到 SQLite。
• --no-history 禁用持久存储，仅保留实时内存缓冲区。
• 启用历史记录时，摘要汇总也会在仪表盘运行时在后台采样。

主题和本地设置

• 主题预设选择持久化到 mesh_dashboard_theme_settings.json，或通过 --theme-settings-file 指定的文件。
• 自定义遥测规则存储在历史 SQLite 数据库中。

维护命令

用于检查或修复本地仪表盘数据的操作命令记录在 docs/maintenance.md 中。

链路视图语义

链路 子视图是拓扑视图，而非数据包路由回放。

• 历史 模式从存储在 SQLite 中的链路历史绘制。
• 实时 模式仅从当前会话的链路观察绘制。
• 编号环显示从当前根节点出发，基于观察到的链路图进行广度优先搜索的最短图距离。
• 这些环编号不是字面上的 Meshtastic 转发跳数，也不是实时数据包追踪。
• 当可用时，数据包跳数元数据仍作为数据包跳数值在节点或边详情中单独显示。

当前根节点是图形围绕的中心节点。选择不同的节点会更改根节点，并重新计算从该节点出发的编号距离环。

配置参考

连接和传输

• --mesh-host <ip-or-dns>：TCP 无线电主机
• --mesh-tcp-port <port>：TCP 无线电端口，默认 4403
• --mesh-port <path>：串行设备路径
• --default-gateway-host <host>：如果未提供 --mesh-host 且串行仍在默认路径上时的备用 TCP 主机
• --default-gateway-port <port>：用于 --default-gateway-host 的备用 TCP 端口
• --no-default-gateway：除非明确设置 --mesh-host，否则强制使用串行

相关环境变量：

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT 用于默认串行路径

HTTP、UI 和安全

• --http-host <host>：绑定主机，默认 0.0.0.0
• --http-port <port>：绑定端口，默认 8877
• --refresh-ms <ms>：浏览器轮询间隔，默认 3000
• --packet-limit <n>：最近实时数据包缓冲区大小，默认 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets：在原始 JSON 面板中显示私钥/密码/PSK
• --debug-mode / --no-debug-mode：暴露仅调试的仪表盘界面，例如高级网络诊断
• --private-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。软件面板显示此单一修订版本而不是包版本。GitHub 合并/squash 提交主题会自动检测；未合并的预览部署可以显式设置 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 <bytes>：每个文件的限制，默认 65536，限制在 1024-524288

传输使用私密端口 258 上的测试版 MF_FILE_V2 协议，并且与先前的文本消息传输不兼容。当目标具有可用的检测跳数时，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 <path>：基础 SQLite 数据库路径
• --history-max-rows <n>：默认 200000
• --history-retention-days <days>：默认 30，使用 0 禁用按时间修剪
• --history-event-max-rows <n>：仅追加的数据包事件上限，默认 200000
• --history-event-retention-days <days>：默认 30
• --history-rollup-retention-days <days>：默认 365
• --no-history：纯内存模式
• --seed-from-node-db：从已连接无线电的 NodeDB 引导实时跟踪器

相关环境变量：

• MESH_DASH_HISTORY_DB

主题

• --theme-presets <json>：可选的自定义主题预设文件
• --theme-preset <name>：选定的预设名称
• --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。命令行令牌可能在进程列表中被看到，并保留在 shell 历史中。
• 内置的 Join Meshyface 频道预设使用故意公开的共享 Meshyface PSK，以实现本软件用户之间的互操作性。不要将该公共频道用于私有流量。
• --show-secrets 会在原始 JSON 面板中暴露敏感值；不要在共享显示器上随意启用。
• 原始数据包数据库下载可能会暴露消息和遥测内容。在共享主机上，要求使用 API 令牌并启用 --no-allow-tokenless-raw-packet-download。
• 文件传输会消耗大量网格空中时间。除非你明确接受了这一权衡，否则保持禁用。

测试和覆盖率

运行标准测试套件：

python -m pytest

像 CI 一样运行 Ruff：

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

在提交 PR 前运行本地 GUI 响应式基准测试：

scripts/run_gui_responsiveness_local.sh

覆盖率故意排除了移植的 Zork 引擎包，但独立的 Zork 和路由测试仍然运行。GitHub Actions 将相同的覆盖率报告作为建议 PR 评论和产物发布。CI 低于 80% 会失败。本地门禁比 CI 高 5 个百分点。