Wanhua-Platform 监控服务器项目文档
项目概述
Wanhua-Platform 是一个物联网监控后端服务器（Monitoring Server），提供完整的设备监控、数据存储和API服务。该平台集成了HTTP API、MQTT Broker WebHook和存储服务，为物联网应用提供全方位的后端支持。
技术栈
- 开发语言: Go 1.18
- Web框架: Gin v1.8.1
- 数据库: MongoDB v1.9.1
- 消息队列: MQTT (Eclipse Paho v1.4.1)
- 实时通信: LiveKit Protocol v1.5.7
- 日志: Uber Zap v1.24.0
- 配置管理: Viper v1.12.0
- 地理计算: golang-geo, blevesearch/geo
项目结构
wanhua-platform/
├── cert/ # SSL证书
│ ├── wanhua-cert.pem # SSL证书文件
│ └── wanhua-key.pem # SSL密钥文件
├── conf/ # 配置文件
│ └── app.yaml # 应用配置
├── license/ # EMQX许可证
│ ├── emqx.key
│ └── emqx.lic
├── models/ # 数据模型
│ ├── alarm.go # 告警模型
│ ├── command.go # 指令模型
│ ├── event.go # 事件模型
│ ├── geofence.go # 地理围栏模型
│ ├── group.go # 分组模型
│ ├── latest_location.go # 最新位置模型
│ ├── location.go # 位置模型
│ ├── txt_message.go # 文本消息模型
│ ├── user.go # 用户模型
│ └── models.go # 模型基础
├── pkg/ # 公共包
│ ├── app/ # 应用工具
│ ├── mqtt/ # MQTT客户端
│ ├── setting/ # 配置管理
│ └── util/ # 工具函数
├── routers/ # 路由
│ ├── api/ # API路由
│ └── route.go # 路由配置
├── service/ # 业务服务
│ ├── command_service/ # 指令服务
│ ├── emqx_service/ # EMQX服务
│ ├── event_service/ # 事件服务
│ ├── geo_fence_service/ # 地理围栏服务
│ ├── group_service/ # 分组服务
│ ├── latest_location_service/ # 最新位置服务
│ ├── location_service/ # 位置服务
│ ├── qvs_service/ # 视频服务
│ └── user_service/ # 用户服务
├── stuff/ # 工具脚本
│ ├── start-alone/ # 独立启动脚本
│ ├── build-image.sh # 构建镜像
│ ├── save-image.sh # 保存镜像
│ └── view-log.sh # 查看日志
├── vendor/ # 依赖包
├── docker-compose.yaml # 开发环境编排
├── docker-compose-prod.yaml # 生产环境编排
├── Dockerfile # Docker镜像构建
├── emqx.conf # EMQX配置
├── main.go # 主程序入口
├── start.sh # 启动脚本
├── stop.sh # 停止脚本
├── go.mod
├── go.sum
└── README.md
核心功能
1. HTTP API服务
- 用户管理接口
- 设备管理接口
- 位置查询接口
- 告警管理接口
- 指令下发接口
- 事件查询接口
2. MQTT WebHook
- EMQX Broker集成
- 设备上下线监控
- 消息订阅/发布
- 实时数据接收
- 事件触发处理
3. 位置服务
- 实时位置更新
- 历史轨迹查询
- 地理围栏管理
- 位置告警
- 地理计算
4. 数据存储
- MongoDB数据持久化
- 位置数据存储
- 事件日志存储
- 用户数据管理
- 告警记录存储
5. 分组管理
- 设备分组
- 用户分组
- 权限管理
- 组织架构
6. 视频服务
- 视频流管理（QVS）
- 实时视频监控
- 视频回放
- 视频存储
数据模型
核心模型
- User: 用户信息
- Location: 位置数据
- LatestLocation: 最新位置
- Geofence: 地理围栏
- Alarm: 告警信息
- Event: 事件记录
- Command: 指令数据
- TxtMessage: 文本消息
- Group: 分组信息
配置说明
服务器配置
mode: release
web:
listen_port: 9999
read_timeout: 60
write_timeout: 60
cert: "./cert/wanhua-cert.pem"
key: "./cert/wanhua-key.pem"
数据库配置
- MongoDB: 主要数据存储
- 连接延迟启动: 40秒（等待依赖服务）
MQTT配置
- 集成 EMQX Broker
- 支持 WebHook 回调
- 企业版许可证支持
部署方式
开发环境
使用 Docker Compose 启动：
docker-compose up -d
生产环境
使用生产配置启动：
docker-compose -f docker-compose-prod.yaml up -d
独立部署
- 启动MongoDB和MQTT Broker:
./setup-dev
- 运行服务器:
go run main.go
或使用脚本：
./start.sh # 启动
./stop.sh # 停止
服务端口
- HTTPS API: 9999
- HTTP API: 7777
- MQTT: 根据EMQX配置
主要依赖
| 依赖包 | 版本 | 用途 |
|---|---|---|
| gin | v1.8.1 | Web框架 |
| mongo-driver | v1.9.1 | MongoDB驱动 |
| paho.mqtt | v1.4.1 | MQTT客户端 |
| zap | v1.24.0 | 日志库 |
| viper | v1.12.0 | 配置管理 |
| golang-geo | v0.7.0 | 地理位置计算 |
| livekit | v1.5.7 | 实时通信协议 |
| gin-contrib/cors | v1.3.1 | 跨域支持 |
应用场景
-
设备监控
- 实时位置追踪
- 设备状态监控
- 告警管理
-
地理围栏
- 区域管理
- 越界告警
- 轨迹分析
-
视频监控
- 实时视频流
- 视频回放
- 视频存储
-
事件管理
- 事件记录
- 事件查询
- 事件分析
系统特点
-
双端口服务
- HTTPS (9999): 安全API访问
- HTTP (7777): 内部服务通信
-
EMQX集成
- WebHook支持
- 企业版功能
- 高性能消息处理
-
延迟启动
- 等待依赖服务就绪
- 40秒启动延迟
- 确保服务稳定
-
完整的服务层
- 清晰的分层架构
- 独立的业务服务
- 易于维护扩展
系统要求
- Go: 1.18+
- Docker: 20.10.21+
- Docker Compose: v2.12.2+
- MongoDB: 4.0+
- EMQX: 4.0+
开发指南
环境准备
- 安装 Go 1.18+
- 安装 Docker 和 Docker Compose
- 配置 MongoDB
- 配置 EMQX
本地开发
- 修改
conf/app.yaml配置 - 启动依赖服务
- 运行
go run main.go - 访问 API 接口
添加新功能
- 在
models/添加数据模型 - 在
service/添加业务逻辑 - 在
routers/api/添加路由 - 更新 API 文档
Docker镜像管理
构建镜像
./stuff/build-image.sh
保存镜像
./stuff/save-image.sh
查看日志
./stuff/view-log.sh
安全建议
- 使用有效的SSL证书
- 修改默认配置
- 启用访问控制
- 配置防火墙规则
- 定期备份数据
- 监控系统日志
- 更新EMQX许可证
监控与维护
- 使用 Zap 结构化日志
- 支持日志级别配置
- 提供日志查看脚本
- 容器化部署便于监控
CORS支持
项目集成了 CORS 中间件，支持跨域请求，便于前端应用集成。
版本信息
- 当前版本: 1.0
- Go版本要求: 1.18+
- 运行模式: release
- API协议: HTTPS/HTTP
文档生成日期: 2025-12-27