# Meshtastic MQTT Server

Meshtastic MQTT Server 是一个面向 Meshtastic MQTT 数据的本地服务：内置 MQTT broker，接收并校验 Meshtastic MQTT payload，同时提供 Web 管理与地图前端，用于查看节点、消息、位置、遥测、转发状态和管理配置。

本文档重点说明部署与运行方式，不展开代码实现细节。

## 后端功能

后端提供 MQTT broker、Meshtastic 数据校验、数据入库、Web API 和管理后台能力，主要功能包括：



- 用户管理：支持创建管理员用户、修改管理员密码。
- 屏蔽规则管理：支持设置节点屏蔽、IP 屏蔽和屏蔽词；屏蔽词可设置匹配方式、是否区分大小写、启用状态和原因。
- 消息拦截：命中被屏蔽节点、被屏蔽 IP 或屏蔽词的消息会被拒绝，并写入丢弃记录。
- MQTT 转发管理：支持配置多个 MQTT 转发器，设置源端、目标端、TLS、认证信息、转发 topic、方向、QoS、retain，并可查看转发运行状态或重启转发器。
- 运行时设置：支持动态设置无法解密的加密 MQTT 包是否允许继续转发。
- 地图源管理：支持配置地图瓦片源、默认地图源、启用状态、最大缩放级别、attribution 和是否通过后端代理地图瓦片。
- 地图瓦片代理与缓存：可通过后端代理地图瓦片请求，并使用本地目录缓存。
- 帮助内容管理：支持在管理后台编辑 Markdown 帮助内容，并提供预览与展示。
- 数据库支持：支持 SQLite 和 MySQL。
- Meshtastic payload 校验：在消息转发前校验 Meshtastic MQTT 数据包，无效数据会被拒绝并记录。
- 数据解析与存储：解析并保存节点信息、地图上报、文本消息、位置、遥测、路由、traceroute 等数据。



## 运行环境

### 后端

- Go：`1.25.0` 或更高版本
- 默认监听：
  - MQTT：`0.0.0.0:1883`
  - Web：`0.0.0.0:8080`

### 前端

- Node.js：满足 Vite 8 要求
  - `^20.19.0`，或
  - `>=22.12.0`
- npm：随 Node.js 安装即可

建议生产环境使用当前 LTS 版本的 Node.js，并确保版本满足上述要求。

## 快速部署

### Linux 一键部署

在 Linux 下进入项目目录后，直接执行：

```bash
sudo bash install.sh
```

安装脚本会自动拉取最新代码、安装前端依赖、构建前端、编译后端、安装到 `/opt/mesh_mqtt_go`，并创建和启动 `mesh_mqtt_go` systemd 服务。

### 手动构建前端

```bash
cd meshmap_frontend
npm install
npm run build
cd ..
```

构建完成后，前端静态文件会生成到项目根目录的 `dist`，也就是从 `meshmap_frontend` 目录看是 `../dist`。

### 手动构建后端

```bash
go build -o meshtastic_mqtt_server .
```

### 手动启动

```bash
./meshtastic_mqtt_server -web-static-dir ./dist
```

首次启动时，程序会自动生成默认配置文件。

默认配置路径：

- Linux：`/etc/mesh_mqtt_go/config.yaml`
- Windows：`./win/etc/mesh_mqtt_go/config.yaml`

默认数据路径：

- Linux SQLite：`/srv/mesh_mqtt_go/mesh_mqtt_go.db`
- Windows SQLite：`./win/etc/mesh_mqtt_go/mesh_mqtt_go.db`

默认地图瓦片缓存目录：

- Linux：`/srv/mesh_mqtt_go`
- Windows：`./win/srv/mesh_mqtt_go`

## 常用启动参数

```bash
./meshtastic_mqtt_server \
  -host 0.0.0.0 \
  -port 1883 \
  -web-host 0.0.0.0 \
  -web-port 8080 \
  -web-static-dir ./dist
```

常用参数说明：

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `-host` | MQTT broker 监听地址 | `0.0.0.0` |
| `-port` | MQTT broker 监听端口 | `1883` |
| `-psk` | Meshtastic channel PSK，Base64 格式 | `AQ==` |
| `-tls` | 启用 MQTT TLS | `false` |
| `-tls-cert` | MQTT TLS 证书文件 | 空 |
| `-tls-key` | MQTT TLS 私钥文件 | 空 |
| `-db-driver` | 数据库类型：`sqlite` 或 `mysql` | `sqlite` |
| `-sqlite-path` | SQLite 数据库文件路径 | 见默认数据路径 |
| `-mysql-dsn` | MySQL DSN | 空 |
| `-web` | 启用 Web 服务 | `true` |
| `-web-host` | Web 服务监听地址 | `0.0.0.0` |
| `-web-port` | Web 服务监听端口 | `8080` |
| `-web-socket-path` | Web Unix Socket 路径，Windows 不支持 | Linux 默认 `/opt/mesh_mqtt_go/web.sock` |
| `-web-static-dir` | 前端静态文件目录 | `./dist` |
| `-web-map-tile-cache-dir` | 地图瓦片缓存目录 | 见默认地图瓦片缓存目录 |
| `-admin-username` | Web 管理员用户名 | `admin` |

管理员密码与会话密钥建议通过环境变量传入：

```bash
export MESH_ADMIN_PASSWORD='change-me'
export MESH_ADMIN_SESSION_SECRET='replace-with-a-long-random-string'
./meshtastic_mqtt_server
```

## 配置文件示例

程序会自动生成并补全配置文件，也可以手动维护 `config.yaml`：

```yaml
mqtt:
  host: 0.0.0.0
  port: 1883
  tls:
    enabled: false
    cert_file: ""
    key_file: ""

meshtastic:
  psk: AQ==

database:
  driver: sqlite
  sqlite:
    path: /srv/mesh_mqtt_go/mesh_mqtt_go.db
  mysql:
    dsn: ""

web:
  enabled: true
  host: 0.0.0.0
  port: 8080
  socket_path: ""
  static_dir: ./dist
  map_tile_cache_dir: /srv/mesh_mqtt_go
  admin:
    username: admin
    password: admin
    session_secret: ""
    session_secure: false
```

> 生产环境请修改默认管理员密码，并设置足够长、随机的 `session_secret`。如果通过 HTTPS 访问 Web 管理后台，建议将 `session_secure` 设置为 `true`。

## 使用 SQLite 部署

SQLite 是默认数据库，适合单机部署：

```bash
mkdir -p /srv/mesh_mqtt_go
./meshtastic_mqtt_server \
  -db-driver sqlite \
  -sqlite-path /srv/mesh_mqtt_go/mesh_mqtt_go.db \
  -web-map-tile-cache-dir /srv/mesh_mqtt_go
```

## 使用 MySQL 部署

如果需要使用 MySQL，启动时指定数据库驱动和 DSN：

```bash
./meshtastic_mqtt_server \
  -db-driver mysql \
  -mysql-dsn 'user:password@tcp(127.0.0.1:3306)/meshtastic?charset=utf8mb4&parseTime=True&loc=Local'
```

## 启用 MQTT TLS

准备证书和私钥后启动：

```bash
./meshtastic_mqtt_server \
  -tls \
  -tls-cert /path/to/server.crt \
  -tls-key /path/to/server.key
```

## 访问服务

启动后可访问：

- Web 前端：`http://服务器地址:8080/`
- 健康检查：`http://服务器地址:8080/api/health`
- MQTT broker：`服务器地址:1883`

Web 管理后台默认账号：

- 用户名：`admin`
- 密码：`admin`

生产环境请务必修改默认密码。

## systemd 部署示例

以下示例假设：

- 后端可执行文件位于 `/opt/mesh_mqtt_go/meshtastic_mqtt_server`
- 前端静态文件位于 `/opt/mesh_mqtt_go/dist`
- 数据与缓存目录位于 `/srv/mesh_mqtt_go`
- 配置文件位于 `/etc/mesh_mqtt_go/config.yaml`

创建服务文件 `/etc/systemd/system/mesh_mqtt_go.service`：

```ini
[Unit]
Description=Meshtastic MQTT Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/mesh_mqtt_go
ExecStart=/opt/mesh_mqtt_go/meshtastic_mqtt_server -web-static-dir /opt/mesh_mqtt_go/dist
Environment=MESH_ADMIN_PASSWORD=change-me
Environment=MESH_ADMIN_SESSION_SECRET=replace-with-a-long-random-string
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
```

启用并启动服务：

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now mesh_mqtt_go
sudo systemctl status mesh_mqtt_go
```

查看日志：

```bash
sudo journalctl -u mesh_mqtt_go -f
```

## 生产环境建议

- 修改默认管理员密码。
- 设置随机且足够长的 `MESH_ADMIN_SESSION_SECRET`。
- 使用反向代理提供 HTTPS。
- 如果 Web 管理后台通过 HTTPS 访问，启用安全 Cookie。
- 根据实际情况开放防火墙端口：
  - MQTT：`1883`
  - MQTT TLS：自定义端口或仍使用 `1883`
  - Web：`8080` 或反向代理端口
- 定期备份数据库文件或 MySQL 数据库。
- 为地图瓦片缓存目录预留足够磁盘空间。

## 开源协议

本项目采用 MIT License 开源。详见项目许可证文件。