ITADN
MeshAddicts/meshinfo
代码 动态 Issues67 合并请求182 版本37
MeshAddicts/meshinfo · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

MeshInfo

一个用于可视化和监控 Meshtastic 网状网络的实时 Web 应用程序。

Docker Image GitHub Release GitHub commit activity License: GPL v3

概述

MeshInfo 连接到一个或多个接收 Meshtastic 流量的 MQTT 代理，并提供一个现代化的 Web UI 用于探索您的 mesh。它实时解码 protobuf 和 JSON 消息，将所有内容存储在 PostgreSQL 中，并通过 FastAPI 后端和 React 前端提供服务。

参见实时实例：Central Valley Mesh, Georgia State Mesh

功能

  • 交互式地图 -- 在 OpenStreetMap 或 Mapbox 上显示带有硬件图标的节点位置
  • RF 覆盖 / 最佳邻居 -- 基于真实地形使用 ITM (Longley-Rice) 进行逐像素 RF 覆盖预测，并结合来自 USGS 土地覆盖的逐像素 ITU-R 杂波损耗。参见 RF-MODEL.md.
  • 聊天 -- 查看和搜索跨频道的网状文本消息，支持 CSV/JSON 导出
  • 节点浏览器 -- 按状态、硬件、角色等条件浏览所有节点
  • 网络图 -- 通过邻接热力图和弧线图可视化网状拓扑
  • 邻居视图 -- 检查邻居关系和信号质量 (SNR)
  • 遥测 -- 每个节点的设备指标、环境传感器和电源数据
  • 路由跟踪 -- 节点间逐跳路径可视化
  • MQTT 日志 -- 用于调试的原始网状流量实时流
  • Discord 集成 -- 将网状消息和位置更新桥接到 Discord 频道
  • 节点增强 -- 从 MeshInfo 网络发现服务增强节点数据
  • 反向地理编码 -- 将节点坐标解析为人类可读的位置
  • 多主题 MQTT -- 在 UI 中通过基于标签的过滤订阅多个 MQTT 主题
  • 频道感知聊天 -- 支持固件 2.5+ 的频道哈希，具有可配置的频道视图

架构

MQTT Broker(s)  -->  MeshInfo Backend (Python / FastAPI / uvicorn)
                          |
                     PostgreSQL 18
                          |
                     MeshInfo Frontend (React 19 / TypeScript / Vite)
                          |
                     Caddy (reverse proxy, automatic HTTPS)

所有组件均作为由 Docker Compose 编排的 Docker 容器运行。

支持的消息类型

  • neighborinfo -- 邻居列表和 SNR 数据
  • nodeinfo -- 硬件、固件和角色信息
  • position -- GPS 坐标和海拔
  • telemetry -- 设备、环境和电源指标
  • text -- 聊天消息
  • traceroute -- 逐跳路由数据

快速开始

前提条件

  • Docker 和 Docker Compose
  • 一个接收 Meshtastic 流量的 MQTT 代理（或使用公共代理，如 mqtt.meshtastic.org）

1. 克隆并配置

git clone https://github.com/MeshAddicts/meshinfo.git
cd meshinfo

# Backend config
cp config.toml.sample config.toml
# Edit config.toml -- set your MQTT broker, topics, mesh name, and node ID

# Frontend config
cp frontend/.env.sample frontend/.env
# Edit frontend/.env if you want to use Mapbox instead of OpenStreetMap

# MQTT broker config
cp mosquitto/config/mosquitto.conf.sample mosquitto/config/mosquitto.conf
# Edit mosquitto.conf -- add bridge connections to MQTT brokers for your region

# Reverse proxy
cp Caddyfile.sample Caddyfile
# Edit Caddyfile -- set your domain (FQDN) and email for automatic TLS

2. 开始

docker compose up -d

MeshInfo 将在 https://your-domain（如果使用本地设置，则为 http://localhost）可用。

3. 更新

git pull && docker compose pull && docker compose down && docker compose up -d

PostgreSQL 主版本升级： 如果某个版本将 postgres 镜像 升级到新的主版本（例如 16 → 18），请在最终 up -d 之前执行一次性迁移 before docker compose pull 然后 bash scripts/migrate-postgres.sh。 参见 POSTGRES.md。

配置

主配置文件为 config.toml。主要部分：

部分用途
[broker]MQTT 连接、主题、通道哈希、解码器
[server]节点 ID、基础 URL、时区、增强、图设置
[storage.postgres]PostgreSQL 连接和池设置
[mesh]网络名称、区域、坐标、外部工具链接
[integrations.*]Discord 桥接、反向地理编码

参见 config.toml.sample 以获取所有选项及其内联文档。

有关 PostgreSQL 的详细信息，参见 POSTGRES.md。

有关 Coverage 和 Scan 工具的传播模型（ITM + ITU-R 杂波），参见 RF-MODEL.md。要启用逐像素的土地覆盖感知预测，请运行一次性瓦片烘焙：

docker compose --profile bake run --rm landcover-bake

Bake 会自动从 MRLC 下载 NLCD，进行解压，并将瓦片写入 output/landcover/。一次性操作约需 15–90 分钟，无需手动下载。有关子区域或离线选项，请参阅 scripts/README-landcover.md。

实时覆盖地图

一个可选的始终最新的地图图层，显示您 mesh 中每个最近听到的节点的预测 RF 覆盖范围——类似于运营商覆盖地图，随着节点的加入和离开自动重新烘焙。启用需两步：

  1. 在 config.toml 中，设置 [coverage] enabled = true。
  2. 启动 worker：docker compose --profile coverage up -d --build coverage-worker

首次烘焙根据 mesh 大小和 CPU 情况，耗时从几分钟到几十分钟不等；之后的每次重新烘焙都是增量的（几秒到几分钟）。在地图上通过 Coverage 按钮切换该图层；悬停（或在移动端长按）可查看哪些节点覆盖某一点。有关其工作原理、小型服务器的调优以及故障排除，请参阅 frontend/coverage-worker/README.md。

Caddy / 反向代理

包含的 Caddyfile.sample 将 /api/* 和 /v1/* 路由到后端，其余所有请求路由到前端。当您在 80/443 端口使用公共 FQDN 时，Caddy 会自动配置 Let's Encrypt 证书。

如果您使用其他反向代理，请将 /api/* 和 /v1/* 指向后端容器（端口 9000），将 / 指向前端容器（端口 80）。

维护模式

当您需要将堆栈下线时——例如为了升级 PostgreSQL——Caddy 可以提供一个带有品牌标识的维护页面，而不是一个损坏的网站。Caddy 和该页面本身在整个过程中保持运行，因此访客会看到一个干净的“我们很快回来”的落地页，而不是连接错误。

scripts/maintenance.sh on       # show the maintenance page
# ... perform the upgrade ...
scripts/maintenance.sh off      # back to normal
scripts/maintenance.sh status   # check current state

在 Windows 上，请改用 PowerShell 端口 — scripts\maintenance.ps1 on|off|status。

该切换操作会创建/删除标志文件 public/maintenance/ON。Caddy 会在每个请求时检查该文件，因此立即生效 — 无需重新加载或重启。启用期间，所有路径（包括 /api/*）都会返回带有 HTTP 503 和 Retry-After 头的页面。该页面每 60 秒自动刷新一次，因此一旦您将其关闭，访客将自动跳转到实时站点。

典型的数据库升级流程如下：

scripts/maintenance.sh on
docker compose stop meshinfo postgres
# ... upgrade / migrate ...
docker compose up -d meshinfo postgres
scripts/maintenance.sh off

通过编辑 public/maintenance/index.html 来自定义外观——它是一个独立的单文件。

地图提供商

MeshInfo 支持两种地图提供商，配置位于 frontend/.env：

不使用 Docker 运行

后端

需要 Python 3.14+ 和一个正在运行的 PostgreSQL 18 实例。

pip install -r requirements.txt
# Edit config.toml with storage.postgres.host = "localhost"
python main.py

前端

需要 Node.js 24 LTS（最低 22.22.2）和 Yarn 4（通过 Corepack 管理 — 无需手动安装）。

cd frontend
cp .env.sample .env
yarn install
yarn dev

开发

有关开发环境配置、项目结构和贡献指南，请参阅 CONTRIBUTING.md。

构建本地 Docker 镜像

# Build everything with docker-compose in dev mode
docker compose -f docker-compose-dev.yml up --build --force-recreate

# Or build images individually
scripts/docker-build.sh 0.0.1-dev

发布

标记发布版本并推送。GitHub Actions 会为 amd64 和 arm64 构建并发布镜像到 ghcr.io/meshaddicts/meshinfo 和 ghcr.io/meshaddicts/meshinfo-spa。

git tag v0.0.0 && git push && git push --tags

API

MeshInfo 提供了一个供前端使用的 REST API。请参阅 API.md 获取端点文档。

Community

有问题、反馈或想要贡献？请加入我们的 Central Valley Mesh Discord。

如果你运行了一个公开的 MeshInfo 实例，我们很乐意了解——请在 Discord 中留言。

License

GNU General Public License v3.0