Samassi 对讲机项目文档
项目概述
Samassi 是一个专为对讲机设备设计的物联网管理平台，提供团队管理、设备通信、位置服务等核心功能。该项目支持对讲机设备和移动应用的统一管理，实现了设备与用户的无缝协作。
技术栈
- 开发语言: Go 1.22.2
- Web框架: Kataras Iris v12.2.10
- 数据库:
- MySQL (GORM ORM)
- MongoDB
- Redis
- 消息队列: MQTT (Eclipse Paho)
- 对象存储: MinIO
- 第三方服务: 阿里云 OpenAPI (短信、号码认证)
- 日志: Uber Zap
- 配置管理: Viper
- 坐标转换: yanmengfei/coord
项目结构
samassi/
├── cmd/ # 命令行入口
│ └── server/ # 主服务器程序
├── config/ # 配置文件
│ ├── config.yaml # 主配置文件
│ ├── server.key # SSL密钥
│ └── server.pem # SSL证书
├── docs/ # 文档目录
│ ├── db/ # 数据库文档
│ ├── folder/ # 其他文档
│ └── document.md # 项目文档
├── internal/ # 内部业务逻辑
│ └── server/ # 服务器核心逻辑
├── pkg/ # 公共包
│ ├── aliopenapi/ # 阿里云OpenAPI集成
│ ├── db/ # 数据库操作
│ ├── email/ # 邮件服务
│ ├── httpclient/ # HTTP客户端
│ ├── log/ # 日志管理
│ ├── map/ # 地图相关功能
│ ├── mqtt/ # MQTT通信
│ ├── routines/ # 协程管理
│ └── util/ # 工具函数
├── script/ # 部署脚本
│ └── prod-samassi/ # 生产环境部署脚本
├── .dockerignore
├── .gitignore
├── go.mod
├── go.sum
└── README.md
核心功能
1. 团队管理系统
创建团队
支持三种创建方式：
-
设备通过MQTT指令创建团队
- 设备创建团队数量限制
- 旧团队无成员时自动回收
-
调用API - 设备创建团队
- 设备创建团队数量限制
- 旧团队无成员时自动回收
-
调用API - APP用户创建团队
- APP创建团队数量限制
- 创建者自动成为群主
加入团队
支持三种加入方式：
-
设备通过MQTT指令加入团队
- 旧团队无成员时自动回收
-
调用API - 设备加入团队
- 旧团队无成员时自动回收
-
调用API - APP用户加入团队
- APP加入团队数量限制
- 团内无群主时自动成为群主
退出团队
-
调用API - 设备退出团队
- 团队无成员时自动回收
-
调用API - APP用户退出团队
- 团队无成员时自动回收
- 群主退出时，群主角色转移给最早加入的APP用户
团队回收机制
-
七天单人/单设备回收
- 团队内七天只有一个人或单个设备
- 系统自动回收并弹窗提示
-
一个月静默回收
- 团队长时间处于静默状态（一个月）
- 系统自动回收并弹窗提示
2. 设备通信
- 基于MQTT的对讲机通信
- 实时语音数据传输
- 设备状态同步
- 指令下发与响应
3. 位置服务
- 设备实时定位
- 位置信息上报
- 地理围栏
- 轨迹记录
- 坐标系转换（支持多种坐标系）
4. 用户管理
- 用户注册与认证
- 短信验证（阿里云短信服务）
- 号码认证（阿里云号码认证）
- 用户权限管理
5. 数据存储
- 团队信息存储
- 设备数据存储
- 用户数据管理
- 历史记录查询
配置说明
服务器配置
server:
host: "0.0.0.0"
port: "2443"
logLevel: "debug"
jwtSignKey: "sercrethatmaycontainch@r32length"
jwtExpirationPeriod: 72
数据库配置
- MongoDB: 存储设备数据、团队信息和日志
- MySQL: 存储用户、权限等结构化数据
- Redis: 缓存、会话管理和实时数据
MQTT配置
mqtt:
broker: "mqtts://my-emqx-container:8883"
clientID: "iot-platform-client_id"
username: "super-emqx"
password: "9Mwov7ns9J7"
业务规则
团队管理规则
-
创建限制
- 设备创建团队有数量限制
- APP用户创建团队有数量限制
- 创建新团队时检查旧团队状态
-
加入限制
- APP用户加入团队有数量限制
- 加入新团队时处理旧团队
-
角色管理
- 每个团队有一个群主
- 群主退出时自动转移
- 优先转移给APP用户
-
自动回收
- 无成员团队立即回收
- 单人团队7天后回收
- 静默团队30天后回收
通知机制
- 团队回收时弹窗提示
- 角色变更时通知用户
- 重要操作实时推送
主要依赖
| 依赖包 | 版本 | 用途 |
|---|---|---|
| iris | v12.2.10 | Web框架 |
| gorm | v1.25.9 | ORM框架 |
| mongo-driver | v1.15.0 | MongoDB驱动 |
| go-redis | v9.5.1 | Redis客户端 |
| paho.mqtt | v1.4.3 | MQTT客户端 |
| minio-go | v7.0.69 | 对象存储 |
| zap | v1.27.0 | 日志库 |
| viper | v1.18.2 | 配置管理 |
| alibabacloud-go | v2.x | 阿里云SDK |
| golang-geo | v0.7.0 | 地理位置计算 |
| coord | v0.1.0 | 坐标转换 |
阿里云服务集成
短信服务 (dysmsapi)
- 用户注册验证
- 密码重置
- 重要通知
号码认证服务 (dypnsapi)
- 一键登录
- 号码验证
- 安全认证
部署方式
生产环境部署
使用 script/prod-samassi/ 目录下的脚本进行生产环境部署
Docker支持
项目包含 .dockerignore 文件，支持容器化部署
依赖服务
- MySQL 数据库
- MongoDB 数据库
- Redis 缓存
- EMQX MQTT Broker
- MinIO 对象存储
应用场景
-
对讲机团队通信
- 工地施工团队
- 安保巡逻团队
- 物流配送团队
-
设备管理
- 对讲机设备注册
- 设备状态监控
- 设备位置追踪
-
混合团队协作
- 对讲机设备 + 手机APP
- 实时语音通信
- 位置共享
系统特点
-
灵活的团队管理
- 支持设备和用户混合组队
- 智能的团队回收机制
- 自动化的角色管理
-
多端支持
- 对讲机设备端
- 移动应用端
- Web管理端
-
实时通信
- MQTT低延迟通信
- 实时位置更新
- 即时消息推送
-
智能化管理
- 自动团队回收
- 智能角色转移
- 数量限制保护
安全建议
- 修改所有默认密码和密钥
- 配置阿里云访问凭证
- 启用 HTTPS/MQTTS 加密
- 实施访问频率限制
- 定期备份数据库
- 监控异常行为
版本信息
- 当前版本: 1.0
- Go版本要求: 1.22.2+
- 运行模式: debug/release
联系方式
文档生成日期: 2025-12-27