ghcr.io/Yeraze/meshmonitor:4.0.0-beta6-main
ghcr.io
ghcr.iolinux/amd644.0.0-beta6-main大小: 未知更新于 2026年4月22日
MeshMonitor
一款全面的Web应用程序，用于通过IP监控Meshtastic mesh网络。基于React、TypeScript和Node.js构建，采用美观的Catppuccin Mocha深色主题，并支持多数据库（SQLite、PostgreSQL、MySQL）。
文档
完整文档请访问 meshmonitor.org
- 入门指南 - 安装和快速启动
- FAQ - 常见问题和故障排除
- 配置 - 详细配置选项
- 开发 - 贡献和开发环境设置
快速启动
60秒内启动MeshMonitor：
# 1. 创建 docker-compose.yml
cat
> docker-compose.yml << 'EOF'
services:
meshmonitor:
image: ghcr.io/yeraze/meshmonitor:latest
ports:
- "8080:3001"
volumes:
- meshmonitor-data:/data
environment:
- MESHTASTIC_NODE_IP=192.168.1.100 # 更改为您的节点IP
restart: unless-stopped
volumes:
meshmonitor-data:
EOF
# 2. 启动MeshMonitor
docker compose up -d
# 3. 打开 http://localhost:8080
默认登录信息：admin / changeme（首次登录后请更改！）
有关详细的安装说明、配置选项和部署场景，请参阅入门指南。
代理认证
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] 代理认证要求：
- MeshMonitor 不得直接访问（使用Docker网络、防火墙规则或***）
- 配置 TRUST_PROXY 以信任您的反向代理
- 您的代理在转发请求前验证身份认证
电子邮件唯一性注意事项
[!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集成配置为包含它们时才存在。如果您的PROXY_AUTH_JWT_GROUPS_CLAIM（例如[***]
要验证：使用浏览器开发工具中的Cf-Access-Jwt-Assertion头，在jwt.io解码实际请求JWT，确认组声明存在及其格式。Cloudflare通常将IdP自定义声明放在custom对象下（例如custom["[***]"]）；官方示例可能显示更扁平的布局——您的解码令牌是您租户的实际依据。
备用方案：将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] 迁移在没有管理员干预的情况下是不可逆的。迁移后的用户无法恢复为本地认证，除非重置密码。
部署选项
MeshMonitor支持多种部署方法：
-
🐳 Docker（推荐）- 预构建的多架构镜像，支持自动升级
- Docker Compose指南
- 平台：amd64、arm64、armv7
-
☸️ Kubernetes - 适用于生产集群的Helm图表
- Helm Chart
- 支持ArgoCD/Flux的GitOps就绪
-
📦 Proxmox LXC - 适用于Proxmox VE的轻量级容器
- Proxmox LXC指南
- 提供预构建模板
- 社区支持的替代方案
-
🔧 手动 - 直接Node.js部署
- 手动安装指南
- 适用于开发或自定义设置
-
🖥️ 桌面应用 - 适用于Windows和macOS的原生应用
- 从GitHub Releases下载
- 作为系统托盘应用运行
- 提供Windows（.exe）和macOS（.dmg）安装程序
主要功能
- 实时Mesh监控 - 节点发现、遥测和消息跟踪
- 现代UI - Catppuccin主题，支持消息反应和线程
- 交互式地图 - 节点位置和网络拓扑可视化
- 多数据库支持 - SQLite（默认）、PostgreSQL和MySQL（通过Drizzle ORM）
- 通知 - Web Push和Apprise集成，支持100+服务
- 认证 - 本地、OIDC/SSO和反向代理认证，带RBAC
- 安全监控 - 加密密钥分析和漏洞检测
- 设备配置 - 完整的节点配置UI
- 虚拟节点服务器 - 为Meshtastic Python客户端提供远程TCP访问
- REST API - v1 API，带Bearer令牌认证，用于外部集成
- MeshCore支持 - 可选的MeshCore mesh网络监控
- Docker就绪 - 预构建的多架构镜像
- 一键自升级 - 从UI自动升级，带备份和回滚
- 系统备份与恢复 - 完整的灾难恢复，带自动备份
完整功能列表和技术细节，请访问meshmonitor.org。
开发
先决条件
- Node.js 20+
- Docker（推荐）或本地Node.js环境
- 具有WiFi/以太网连接的Meshtastic设备
本地开发
# 克隆带子模块的仓库
git clone --recurse-submodules https://github.com/Yeraze/meshmonitor.git
cd meshmonitor
# 安装依赖
npm install
# 配置环境
cp .env.example .env
# 编辑.env，设置Meshtastic节点的IP地址
# 启动开发服务器
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工作流
快速开始：
- Fork仓库
- 创建功能分支（git checkout -b feature/amazing-feature）
- 进行更改并添加测试
- 本地运行测试（npm run test:run）
- 使用规范提交信息提交（feat: add amazing feature）
- 推送并创建拉取请求
许可证
本项目采用BSD-3-Clause许可证 - 详见LICENSE文件。
社区与支持
- ：加入我们的 - 与社区聊天并获取帮助
- GitHub Issues：报告错误和请求功能
- 文档：meshmonitor.org
第三方客户端
- meshmonitor-chat.el - Emacs聊天客户端，使用REST API v1。支持频道和私信、送达确认、表情反应、轮询。
致谢
- Meshtastic - 开源mesh网络
- Catppuccin - 舒缓的 pastel 主题
- React - 前端框架
- Drizzle ORM - TypeScript ORM
- better-sqlite3 - SQLite驱动
Star History
MeshMonitor - 优雅地监控您的mesh网络。🌐✨
本应用程序在Claude Code的帮助下开发。
项目仓库 README（补充）
MeshMonitor
https://github.com/Yeraze/meshmonitor/actions/workflows/ci.yml/badge.svg](https://github.com/Yeraze/meshmonitor/actions/workflows/ci.yml) https://github.com/Yeraze/meshmonitor/actions/workflows/pr-tests.yml/badge.svg](https://github.com/Yeraze/meshmonitor/actions/workflows/pr-tests.yml) !https://github.com/Yeraze/meshmonitor/pkgs/container/meshmonitor !https://github.com/Yeraze/meshmonitor/pkgs/container/meshmonitor !https://github.com/Yeraze/meshmonitor/blob/main/LICENSE ![Translation Status]([***]
一款全面的Web应用程序，用于通过IP监控Meshtastic mesh网络。基于React、TypeScript和Node.js构建，采用美观的Catppuccin Mocha深色主题，并支持多数据库（SQLite、PostgreSQL、MySQL）。
!MeshMonitor界面
!MeshMonitor界面
文档
完整文档请访问 meshmonitor.org
- 入门指南 - 安装和快速启动
- FAQ - 常见问题和故障排除
- 配置 - 详细配置选项
- 开发 - 贡献和开发环境设置
快速启动
60秒内启动MeshMonitor：
# 1. 创建 docker-compose.yml
cat
> docker-compose.yml << 'EOF'
services:
meshmonitor:
image: ghcr.io/yeraze/meshmonitor:latest
ports:
- "8080:3001"
volumes:
- meshmonitor-data:/data
environment:
- MESHTASTIC_NODE_IP=192.168.1.100 # 更改为您的节点IP
restart: unless-stopped
volumes:
meshmonitor-data:
EOF
# 2. 启动MeshMonitor
docker compose up -d
# 3. 打开 http://localhost:8080
默认登录信息： admin / changeme（首次登录后请更改！）
有关详细的安装说明、配置选项和部署场景，请参阅 入门指南。
代理认证
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] 代理认证要求：
- MeshMonitor 不得直接访问（使用Docker网络、防火墙规则或***）
TRUST_PROXY配置为信任您的反向代理- 您的代理在转发请求前验证身份认证
电子邮件唯一性注意事项
[!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集成配置为包含它们时才存在。如果您的PROXY_AUTH_JWT_GROUPS_CLAIM（例如https://your-domain/roles）在Cf-Access-Jwt-Assertion头中缺失，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] 迁移在没有管理员干预的情况下是不可逆的。 迁移后的用户无法恢复为本地认证，除非重置密码。
部署选项
MeshMonitor支持多种部署方法：
-
🐳 Docker（推荐）- 预构建的多架构镜像，支持自动升级
- Docker Compose指南
- 平台：amd64、arm64、armv7
-
☸️ Kubernetes - 适用于生产集群的Helm图表
- Helm Chart
- 支持ArgoCD/Flux的GitOps就绪
-
📦 Proxmox LXC - 适用于Proxmox VE的轻量级容器
- Proxmox LXC指南
- 提供预构建模板
- 社区支持的替代方案
-
🔧 手动 - 直接Node.js部署
- 手动安装指南
- 适用于开发或自定义设置
-
🖥️ 桌面应用 - 适用于Windows和macOS的原生应用
- 从https://github.com/Yeraze/meshmonitor/releases%E4%B8%8B%E8%BD%BD
- 作为系统托盘应用运行
- 提供Windows（.exe）和macOS（.dmg）安装程序
主要功能
- 实时Mesh监控 - 节点发现、遥测和消息跟踪
- 现代UI - Catppuccin主题，支持消息反应和线程
- 交互式地图 - 节点位置和网络拓扑可视化
- 多数据库支持 - SQLite（默认）、PostgreSQL和MySQL（通过Drizzle ORM）
- 通知 - Web Push和Apprise集成，支持100+服务
- 认证 - 本地、OIDC/SSO和反向代理认证，带RBAC
- 安全监控 - 加密密钥分析和漏洞检测
- 设备配置 - 完整的节点配置UI
- 虚拟节点服务器 - 为Meshtastic Python客户端提供远程TCP访问
- REST API - v1 API，带Bearer令牌认证，用于外部集成
- MeshCore支持 - 可选的MeshCore mesh网络监控
- Docker就绪 - 预构建的多架构镜像
- 一键自升级 - 从UI自动升级，带备份和回滚
- 系统备份与恢复 - 完整的灾难恢复，带自动备份
完整功能列表和技术细节，请访问 meshmonitor.org。
开发
先决条件
- Node.js 20+
- Docker（推荐）或本地Node.js环境
- 具有WiFi/以太网连接的Meshtastic设备
本地开发
# 克隆带子模块的仓库
git clone --recurse-submodules https://github.com/Yeraze/meshmonitor.git
cd meshmonitor
# 安装依赖
npm install
# 配置环境
cp .env.example .env
# 编辑.env，设置Meshtastic节点的IP地址
# 启动开发服务器
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- 运行ESLintnpm 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工作流
快速开始：
- Fork仓库
- 创建功能分支（
git checkout -b feature/amazing-feature） - 进行更改并添加测试
- 本地运行测试（
npm run test:run） - 使用规范提交信息提交（
feat: add amazing feature） - 推送并创建拉取请求
许可证
本项目采用BSD-3-Clause许可证 - 详见LICENSE文件。
社区与支持
- ****：加入我们的 - 与社区聊天并获取帮助
- GitHub Issues：报告错误和请求功能
- 文档：meshmonitor.org
第三方客户端
- meshmonitor-chat.el - Emacs聊天客户端，使用REST API v1。支持频道和私信、送达确认、表情反应、轮询。
致谢
- Meshtastic - 开源mesh网络
- Catppuccin - 舒缓的pastel主题
- React - 前端框架
- Drizzle ORM - TypeScript ORM
- https://github.com/WiseLibs/better-sqlite3 - SQLite驱动
Star History
oldzhang
运维工程师
Linux服务器
5
"Docker访问体验非常流畅，大镜像也能快速完成下载。"