ghcr.io/Yeraze/meshmonitor:4.9

MeshMonitor

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

文档

完整文档请访问 meshmonitor.org

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

快速启动

在 60 秒内启动 MeshMonitor：

# 1. Create docker-compose.yml
cat
> docker-compose.yml custom-values.yaml << 'EOF'
env:
meshtasticNodeIp: "192.168.1.100"
meshtasticUseTls: "false"
EOF

helm install meshmonitor ./helm/meshmonitor -f custom-values.yaml

有关入口、TLS、持久化和完整值参考，请参见 Helm Chart README，或文档网站上的 Helm 部署指南。

代理认证

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

支持的代理

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

快速设置

services:
meshmonitor:
image: ghcr.io/yeraze/meshmonitor:latest
environment:
# Enable proxy authentication
- PROXY_AUTH_ENABLED=true
- PROXY_AUTH_AUTO_PROVISION=true

# Admin detection
- PROXY_AUTH_ADMIN_GROUPS=admins,mesh-admins
- PROXY_AUTH_ADMIN_EMAILS=admin@example.com

# Required: Trust the reverse proxy
- TRUST_PROXY=1

# Optional: Logout redirect
- PROXY_AUTH_LOGOUT_URL=https://auth.example.com/oauth2/sign_out

安全要求

[!IMPORTANT] 代理认证要求：

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

电子邮件唯一性注意事项

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

配置选项

# Core settings
PROXY_AUTH_ENABLED=false # Enable proxy auth (default: false)
PROXY_AUTH_AUTO_PROVISION=false # Auto-create users (default: false)

# Admin detection (at least one recommended)
PROXY_AUTH_ADMIN_GROUPS= # Comma-separated admin groups (case-insensitive match)
PROXY_AUTH_ADMIN_EMAILS= # Comma-separated admin emails (case-insensitive match)

# Normal-user group gate (optional, see below)
PROXY_AUTH_NORMAL_USER_GROUPS= # Comma-separated groups allowed to access (empty = all allowed)

# JWT configuration (for Cloudflare Access)
PROXY_AUTH_JWT_GROUPS_CLAIM=groups # Groups claim path (supports Auth0 custom namespaces)

# Custom headers (optional, for non-standard proxies)
PROXY_AUTH_HEADER_EMAIL= # Custom email header name
PROXY_AUTH_HEADER_GROUPS= # Custom groups header name

# Logout
PROXY_AUTH_LOGOUT_URL= # Redirect URL after logout

# Audit logging
PROXY_AUTH_AUDIT_LOGGING=true # Log auth events (default: 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 声明，管理员权限仍然有效。

参见：Cloudflare 应用程序令牌

JWT 组规范化

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

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

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

普通用户组限制

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

双层模型：

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

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

示例

Cloudflare Access + Auth0（带普通用户组限制）：

PROXY_AUTH_ENABLED=true
PROXY_AUTH_AUTO_PROVISION=true
PROXY_AUTH_JWT_GROUPS_CLAIM=https://mydomain.com/roles
PROXY_AUTH_ADMIN_GROUPS=admins
PROXY_AUTH_NORMAL_USER_GROUPS=meshmonitor-users
PROXY_AUTH_ADMIN_EMAILS=operator@example.com
PROXY_AUTH_LOGOUT_URL=https://yourteam.cloudflareaccess.com/cdn-cgi/access/logout
TRUST_PROXY=1
COOKIE_SECURE=true

oauth2-proxy：

PROXY_AUTH_ENABLED=true
PROXY_AUTH_AUTO_PROVISION=true
PROXY_AUTH_ADMIN_EMAILS=admin@example.com,superuser@example.com
PROXY_AUTH_LOGOUT_URL=https://auth.example.com/oauth2/sign_out
TRUST_PROXY=1

用户迁移

启用代理认证后，如果现有本地用户的电子邮件匹配，首次登录时将自动迁移：

• authMethod 更新为 'proxy'
• 密码清除（与 OIDC 迁移行为相同）
• 管理员状态基于组更新

[!IMPORTANT] 未经管理员干预，迁移不可逆转。迁移后的用户若不重置密码，无法恢复为本地认证。

开发

先决条件

• Node.js 20+
• Docker（推荐）或本地 Node.js 环境
• 至少一个 mesh 源 — Meshtastic 设备（WiFi/以太网，或通过桥接的串口/BLE）、MeshCore 设备或 MQTT 代理

本地开发

# 克隆包含子模块的仓库
git clone --recurse-submodules https://github.com/Yeraze/meshmonitor.git
cd meshmonitor

# 安装依赖
npm install

# 配置环境
cp .env.example .env
# 编辑 .env 以设置第一个源（MESHTASTIC_NODE_IP / MESHTASTIC_TCP_PORT）；其他节点稍后通过仪表盘 → 源添加

# 启动开发服务器
npm run dev:full

这将启动 React 开发服务器（端口5173）和 Express API 服务器（端口3001）。

可用脚本

开发：

• npm run dev - 启动 React 开发服务器
• npm run dev:server - 启动 Express API 服务器
• npm run dev:full - 启动两个开发服务器
• npm run build - 构建生产环境的 React 应用
• npm run build:server - 构建生产环境的 Express 服务器

测试与质量：

• npm run test - 以监视模式运行测试
• npm run test:run - 运行所有测试一次
• npm run test:coverage - 生成覆盖率报告
• npm run lint - 运行 ESLint
• npm run typecheck - 运行 TypeScript 编译器检查

技术栈

前端：

• React 19（使用 TypeScript）
• Vite 7（构建工具）
• CSS3（使用 Catppuccin 主题）
• 翻译支持由 Weblate 社区协作提供

后端：

• 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 - Emacs 聊天客户端，使用 REST API v1。支持频道和私信、送达确认、表情反应、轮询。
• MeshMonitor Chat for iOS - 原生 iOS 聊天客户端，使用 REST API v1。通过您的 MeshMonitor 服务器支持频道和私信。

致谢

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

星标历史

---

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

本应用在 Claude Code 的帮助下开发。