ghcr.io/Yeraze/meshmonitor:4.14.1-rc5-main

MeshMonitor

一款全面的Web应用程序，用于从单一仪表板监控离网 mesh 网络（Meshtastic、MeshCore 和 MQTT）。基于 React、TypeScript 和 Node.js 构建，采用美观的 Catppuccin Mocha 深色主题，并支持多数据库（SQLite、PostgreSQL、MySQL）。

Documentation

完整文档请访问 meshmonitor.org

• 入门指南 - 安装与快速启动
• 常见问题（FAQ） - 常见问题与故障排除
• 配置 - 详细配置选项
• 开发 - 贡献与开发环境设置

部署选项

MeshMonitor 支持多种部署方式：

• 🐳 Docker（推荐）- 预构建多架构镜像，支持自动升级

  • Docker Compose 指南
  • 支持平台：amd64、arm64、armv7

• ☸️ Kubernetes / Helm - 适用于生产集群的 Helm 图表

  • Helm Chart README — 完整安装、配置值、入口和 TLS 参考
  • Helm 部署指南 — 文档站点上的快速入门
  • 支持 ArgoCD/Flux 的 GitOps 就绪方案

• 📦 Proxmox LXC - 适用于 Proxmox VE 的轻量级容器

  • Proxmox LXC 指南
  • 提供预构建模板
  • 社区支持的替代方案

• 🔧 手动部署 - 直接 Node.js 部署（裸机）

  • 裸机（Node.js）部署指南
  • 适用于开发或自定义设置

[!NOTE] SQLite 默认路径为 /data/meshmonitor.db（Docker 约定）。裸机安装必须将 DATABASE_PATH 设置为可写位置，或为运行时用户创建 /data/ 目录。

• 🖥️ 桌面应用 - 适用于 Windows 和 macOS 的原生应用
  • 从 GitHub Releases 下载
  • 作为系统托盘应用运行
  • 提供 Windows（.exe）和 macOS（.dmg）安装程序

代理认证

MeshMonitor 支持通过反向代理头进行认证，可与 Cloudflare Access、oauth2-proxy、Authelia、Traefik ForwardAuth 及类似解决方案无缝集成单点登录（SSO）。

支持的代理

• Cloudflare Access - 基于 JWT 的认证，支持自定义角色声明
• oauth2-proxy - 标准 OAuth2 代理，支持电子邮件/组头
• 通用代理 - 可配置的基于头的认证

快速设置

services:
meshmonitor:
image: ghcr.io/yeraze/meshmonitor:latest
environment:
# 启用代理认证
- PROXY_AUTH_ENABLED=true
- PROXY_AUTH_AUTO_PROVISION=true

# 管理员检测
- PROXY_AUTH_ADMIN_GROUPS=admins,mesh-admins
- PROXY_AUTH_ADMIN_EMAILS=admin@example.com

# 必需：信任反向代理
- TRUST_PROXY=1

# 可选：登出重定向
- PROXY_AUTH_LOGOUT_URL=https://auth.example.com/oauth2/sign_out

安全要求

[!IMPORTANT] 代理认证要求：

1. MeshMonitor 不可直接访问（使用 Docker 网络、防火墙规则或 ***）
2. TRUST_PROXY 已配置为信任您的反向代理
3. 您的代理在转发请求前验证认证

从 v4.13 版本开始，TRUST_PROXY 默认值为 false；当 MeshMonitor 运行在任何反向代理之后时，您必须设置 TRUST_PROXY=1（或适当的跳数/子网），否则客户端 IP 解析、速率限制和审计日志都将显示代理的 IP。

电子邮件唯一性注意事项

[!IMPORTANT] 数据库模式中不强制电子邮件唯一性。如果多个用户共享相同的电子邮件地址，将使用第一个匹配项。确保您的代理为每个用户提供唯一的电子邮件地址。

配置选项

# 核心设置
PROXY_AUTH_ENABLED=false # 启用代理认证（默认：false）
PROXY_AUTH_AUTO_PROVISION=false # 自动创建用户（默认：false）

# 管理员检测（建议至少配置一项）
PROXY_AUTH_ADMIN_GROUPS= # 逗号分隔的管理员组（不区分大小写匹配）
PROXY_AUTH_ADMIN_EMAILS= # 逗号分隔的管理员电子邮件（不区分大小写匹配）

# 普通用户组限制（可选，见下文）
PROXY_AUTH_NORMAL_USER_GROUPS= # 允许访问的逗号分隔组（为空则允许所有）

# JWT 配置（适用于 Cloudflare Access）
PROXY_AUTH_JWT_GROUPS_CLAIM=groups # 组声明路径（支持 Auth0 自定义命名空间）

# 自定义头（可选，适用于非标准代理）
PROXY_AUTH_HEADER_EMAIL= # 自定义电子邮件头名称
PROXY_AUTH_HEADER_GROUPS= # 自定义组头名称

# 登出
PROXY_AUTH_LOGOUT_URL= # 登出后的重定向 URL

# 审计日志
PROXY_AUTH_AUDIT_LOGGING=true # 记录认证事件（默认：true）

Cloudflare Access JWT 子集令牌

Cloudflare Access 应用 JWT 包含完整身份的子集——通常是 email､aud､iss､sub｡自定义 OIDC 声明（例如 Auth0 角色声明）仅在 IdP 集成配置为包含它们时才会出现｡如果 Cf-Access-Jwt-Assertion 头中缺少您的 PROXY_AUTH_JWT_GROUPS_CLAIM（例如 https://your-domain/roles），MeshMonitor 将看到空组，基于组的管理员权限将永远不会触发｡

验证方法： 使用浏览器开发者工具中的 Cf-Access-Jwt-Assertion 头，在 jwt.io 解码真实请求的 JWT，确认组声明存在及其格式｡Cloudflare 通常将 IdP 自定义声明放在 custom 对象下（例如 custom["https://your-domain/roles"]）；官方示例可能显示更扁平的结构——您的解码令牌是您租户的实际依据｡

备用方案： 将 PROXY_AUTH_ADMIN_EMAILS 设置为操作员电子邮件允许列表｡MeshMonitor 不区分大小写地匹配电子邮件，因此即使应用 JWT 省略了自定义 IdP 声明，管理员功能仍然可用｡

参见：https://developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/application-token/

JWT 组规范化

MeshMonitor 规范化 JWT 中的组声明，以处理不同的 IdP 格式：

• 字符串数组（["admin", "user"]）——原样使用
• 单个字符串（"admin"）——包装为数组
• 角色对象（[{ "name": "admin" }, { "name": "user" }]）——提取 .name 属性

这可处理 Auth0 登录后操作中发出角色对象而非纯字符串的情况｡所有组匹配（管理员组、普通用户组）均不区分大小写｡

普通用户组限制

PROXY_AUTH_NORMAL_USER_GROUPS 在反向代理的 URL 级访问控制之上，添加了应用层组检查作为第二道限制｡

双层模型：

配置后，仅允许组中包含此列表中至少一个值的用户（或管理员）访问｡通过代理但缺少匹配组的用户将收到 403 FORBIDDEN_PROXY_GROUP 错误｡

为空时（默认），允许所有代理认证用户访问——反向代理是唯一的限制｡

核心功能

• 多协议、多源支持 - 从单一部署监控Meshtastic（TCP/串行/BLE）、MeshCore（USB/TCP）和MQTT broker，支持按源权限、调度器和虚拟节点
• 嵌入式MQTT Broker - 可选内置broker，支持与公共上游的双向桥接，以及主题/频道/端口号/地理过滤
• MQTT地理过滤 - 在MQTT桥接源上配置边界框后，报告位置超出边界框的节点将被自动忽略，其所有存储数据（消息、遥测数据、路由跟踪等）会被清除；当节点报告位置回到边界内时会自动重新出现。从未报告位置的节点始终允许通过（与早期版本不同，不再静默隐藏）。手动忽略的节点不会被自动取消忽略。修改边界框会对已存储的节点追溯应用规则。
• 分析与报告（4.2版本） - /reports路径下的跨源分析工作区；首个报告为太阳能监测分析，支持太阳能节点自动检测、发电量叠加、健康水平参考线和多日电池预测模拟
• 实时Mesh监控 - 跨所有已连接源的节点实时发现、遥测数据及消息跟踪
• 现代化UI - Catppuccin主题，支持消息反应和线程功能
• 交互式地图 - 跨所有源的统一节点位置和网络拓扑可视化
• 地形链路分析 - 地图分析中的两点地形高程、视距及菲涅尔区链路预算规划工具，支持按源自动检测频率/接收灵敏度和可配置的DEM数据源
• 3D地形视图 - 地图分析中的倾斜地形MapLibre GL视图，支持DEM/山体阴影渲染、可调整的夸张比例和可点击节点标记（在配置基于瓦片的高程源时可用）
• 多数据库支持 - 通过Drizzle ORM支持SQLite（默认）、PostgreSQL和MySQL
• 通知功能 - Web Push和Apprise集成，支持100+服务，包含节点不活跃和低电量警报
• 自动化功能 - 自动回复、定时公告、计时器和地理围栏触发器，带有丰富的消息模板；还包含空口利用率阈值，在Mesh繁忙时自动暂停机器人流量
• 认证功能 - 本地认证、OIDC/SSO及带RBAC的反向代理认证
• 安全监控 - 加密密钥分析和漏洞检测
• 设备配置 - 完整的节点配置界面
• 虚拟节点服务器 - 为Meshtastic移动/Python客户端提供远程TCP访问，以及MeshCore虚拟节点（通过WiFi将MeshCore应用连接到受管设备）
• REST API - 带Bearer令牌认证的v1 API，用于外部集成
• Docker就绪 - 预构建的多架构镜像
• 一键自升级 - 通过UI自动升级，包含备份和回滚功能
• 系统备份与恢复 - 带自动备份的完整灾难恢复

完整功能列表和技术详情，请访问 meshmonitor.org。

前端：

• React 19（搭配TypeScript）
• Vite 7（构建工具）
• CSS3（采用Catppuccin主题）
• 翻译支持由https://hosted.weblate.org/projects/meshmonitor/众包提供

后端：

• Node.js（搭配Express 5）
• TypeScript
• Drizzle ORM（支持SQLite、PostgreSQL和MySQL驱动）

DevOps：

• Docker（采用多阶段构建）
• Docker Compose（用于编排）
• GitHub Container Registry（用于镜像存储）

贡献指南

我们欢迎贡献！详情请参见我们的贡献指南，其中包括：

• 开发环境设置
• 测试要求
• 代码风格指南
• 拉取请求流程
• CI/CD工作流

快速开始：

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行修改并添加测试
4. 本地运行测试（npm run test:run）
5. 使用规范提交信息进行提交（feat: add amazing feature）
6. 推送并创建拉取请求

许可证

本项目采用BSD-3-Clause许可证授权 - 详情参见LICENSE文件。

社区与支持

• ****：加入我们的 - 与社区交流并获取帮助
• GitHub Issues：报告错误和请求功能
• 文档：meshmonitor.org

第三方客户端

• meshmonitor-chat.el - 使用REST API v1的Emacs聊天客户端。支持频道和私信、送达确认、表情反应、轮询。
• https://apps.apple.com/app/meshmonitor-chat/id6766212933 - 使用REST API v1的原生iOS聊天客户端。通过您的MeshMonitor服务器支持频道和私信。

致谢

• Meshtastic - 开源 mesh 网络
• Catppuccin - 柔和的 pastel 主题
• https://react.dev/ - 前端框架
• Drizzle ORM - TypeScript ORM
• https://github.com/WiseLibs/better-sqlite3 - SQLite 驱动

星标历史

---

MeshMonitor - 优雅地监控您的 mesh 网络。🌐✨

本应用在https://claude.ai/code的帮助下开发。