# 物联网基站管理系统

## 项目概述

这是一个基于Go语言的物联网基站管理系统，支持多种通信协议（MQTT、CoAP、LoRaWAN），提供设备管理、数据处理、实时监控和智能告警等功能。

## 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   IoT设备       │    │   数据网关       │    │   管理平台       │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ 传感器节点   │ │◄──►│ │ MQTT适配器   │ │◄──►│ │ 设备管理     │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ 执行器节点   │ │◄──►│ │ CoAP适配器   │ │◄──►│ │ 数据处理     │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ LoRa节点     │ │◄──►│ │ LoRa适配器   │ │◄──►│ │ 告警系统     │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 功能特性

### 多协议支持
- MQTT协议支持
- CoAP协议支持
- LoRaWAN协议支持
- HTTP RESTful API
- WebSocket实时通信

### 设备管理
- 设备注册与认证
- 设备状态监控
- 远程配置管理
- OTA固件更新
- 设备故障诊断

### 数据处理
- 实时数据采集
- 数据清洗与预处理
- 时序数据存储
- 数据聚合与统计
- 历史数据分析

### 监控与告警
- 实时监控仪表板
- 自定义告警规则
- 多级告警机制
- 多渠道通知
- 告警抑制与恢复

## 技术栈

### 后端技术
- **语言**: Go 1.19+
- **Web框架**: Gin
- **消息队列**: NATS
- **时序数据库**: InfluxDB
- **关系数据库**: PostgreSQL
- **缓存**: Redis
- **监控**: Prometheus + Grafana

### 通信协议
- **MQTT**: Eclipse Paho
- **CoAP**: go-coap
- **LoRaWAN**: ChirpStack
- **HTTP**: RESTful API
- **WebSocket**: 实时通信

### 前端技术
- **框架**: React
- **图表库**: Chart.js
- **UI组件**: Ant Design
- **实时通信**: WebSocket

### 部署技术
- **容器化**: Docker
- **编排**: Docker Compose
- **CI/CD**: GitLab CI
- **监控**: Prometheus + Grafana

## 快速开始

### 环境要求
- Go 1.19+
- Docker & Docker Compose
- Node.js 16+ (前端开发)
- Git

### 安装步骤

1. **克隆项目**
```bash
git clone https://github.com/your-username/iot-base-station.git
cd iot-base-station
```

2. **启动依赖服务**
```bash
# 启动基础服务（不包括应用）
docker-compose up -d postgres influxdb redis nats mqtt

# 等待服务就绪
docker-compose ps
```

3. **安装Go依赖**
```bash
go mod download
go mod tidy
```

4. **初始化数据库**
```bash
# 创建PostgreSQL数据库
docker-compose exec postgres psql -U postgres -c "CREATE DATABASE iot_base_station;"

# 运行数据库迁移
go run cmd/migrate/main.go up
```

5. **运行服务**
```bash
# 方式1：分别运行（推荐用于开发）
# 终端1：启动主服务器
CONFIG_PATH=config/config.dev.yaml go run cmd/server/main.go

# 终端2：启动数据网关
CONFIG_PATH=config/config.dev.yaml go run cmd/gateway/main.go

# 终端3：启动监控服务
CONFIG_PATH=config/config.dev.yaml go run cmd/monitor/main.go

# 方式2：使用Docker Compose（推荐用于测试）
docker-compose up -d
```

6. **运行设备模拟器（可选）**
```bash
# 新终端窗口
go run simulations/main.go -broker=tcp://localhost:1883 -count=5 -interval=30s
```

7. **访问应用**
- 管理平台: http://localhost:8080
- API文档: http://localhost:8080/swagger/index.html
- 监控面板: http://localhost:3000 (Grafana)

## 本地开发调试

详细的本地开发调试指南请参考：[本地开发调试文档](docs/local-development.md)

### 快速调试步骤

1. **创建开发配置**
```bash
cp config/config.yaml config/config.dev.yaml
# 编辑config/config.dev.yaml，设置debug模式
```

2. **使用热重载**
```bash
# 安装Air热重载工具
go install github.com/cosmtrek/air@latest

# 启动热重载
air -c .air.toml
```

3. **调试API**
```bash
# 注册测试设备
curl -X POST http://localhost:8080/api/v1/devices \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试温度传感器",
    "type": "temperature_sensor",
    "protocol": "mqtt"
  }'

# 获取设备列表
curl -X GET http://localhost:8080/api/v1/devices
```

4. **测试MQTT连接**
```bash
# 订阅主题
docker-compose exec mqtt mosquitto_sub -h localhost -t "iot/data/+/+"

# 发布测试数据
docker-compose exec mqtt mosquitto_pub -h localhost -t "iot/data/test/temperature" -m '{"temperature": 25.5}'
```

## 项目结构

```
iot-base-station/
├── README.md                 # 项目说明
├── go.mod                    # 依赖管理
├── config/                   # 配置文件
│   ├── config.yaml          # 应用配置
│   └── devices.yaml         # 设备配置
├── cmd/                      # 应用入口
│   ├── server/              # 主服务器
│   │   └── main.go
│   ├── gateway/             # 数据网关
│   │   └── main.go
│   └── monitor/             # 监控服务
│       └── main.go
├── internal/                 # 内部包
│   ├── config/              # 配置管理
│   │   └── config.go
│   ├── device/              # 设备管理
│   │   ├── device.go
│   │   └── manager.go
│   ├── protocol/            # 协议实现
│   │   ├── mqtt/
│   │   ├── coap/
│   │   └── lora/
│   ├── storage/             # 数据存储
│   │   ├── influxdb.go
│   │   └── postgresql.go
│   ├── analytics/           # 数据分析
│   │   ├── processor.go
│   │   └── aggregator.go
│   └── notification/        # 通知服务
│       ├── alert.go
│       └── notifier.go
├── pkg/                      # 公共包
│   ├── mqtt/                # MQTT客户端
│   │   └── client.go
│   ├── coap/                # CoAP客户端
│   │   └── client.go
│   ├── lora/                # LoRaWAN客户端
│   │   └── client.go
│   ├── database/            # 数据库连接
│   │   └── connection.go
│   └── security/            # 安全模块
│       └── auth.go
├── web/                      # Web界面
│   ├── static/              # 静态资源
│   └── templates/           # 模板文件
├── scripts/                  # 脚本文件
│   ├── setup.sh             # 环境设置
│   └── deploy.sh            # 部署脚本
├── docs/                     # 文档
│   ├── api.md               # API文档
│   ├── architecture.md      # 架构文档
│   └── deployment.md        # 部署文档
├── tests/                    # 测试文件
├── simulations/              # 模拟器
│   ├── devices/             # 设备模拟器
│   └── network/             # 网络模拟器
└── docker-compose.yml        # Docker配置
```

## API文档

### 设备管理API

#### 注册设备
```http
POST /api/v1/devices
Content-Type: application/json

{
  "name": "温度传感器01",
  "type": "temperature_sensor",
  "protocol": "mqtt",
  "metadata": {
    "location": "机房A",
    "model": "DHT22"
  }
}
```

#### 获取设备列表
```http
GET /api/v1/devices?page=1&page_size=10&type=temperature_sensor
```

#### 获取设备详情
```http
GET /api/v1/devices/{device_id}
```

#### 更新设备配置
```http
PUT /api/v1/devices/{device_id}/config
Content-Type: application/json

{
  "report_interval": 30,
  "threshold": {
    "min": 10,
    "max": 35
  }
}
```

### 数据查询API

#### 获取实时数据
```http
GET /api/v1/data/realtime?device_id={device_id}&metric=temperature
```

#### 获取历史数据
```http
GET /api/v1/data/history?device_id={device_id}&metric=temperature&start=2023-01-01T00:00:00Z&end=2023-01-02T00:00:00Z
```

### 告警管理API

#### 创建告警规则
```http
POST /api/v1/alerts/rules
Content-Type: application/json

{
  "name": "温度过高告警",
  "description": "当温度超过35度时触发告警",
  "condition": "temperature > 35",
  "severity": "warning",
  "actions": [
    {
      "type": "email",
      "config": {
        "to": ["admin@example.com"]
      }
    }
  ]
}
```

## 开发指南

### 添加新协议支持

1. 在`internal/protocol/`目录下创建新协议目录
2. 实现`ProtocolAdapter`接口
3. 在网关服务中注册新适配器
4. 添加配置选项
5. 编写测试用例

```go
// 协议适配器接口
type ProtocolAdapter interface {
    Name() string
    Start() error
    Stop() error
    HandleMessage(msg Message) error
}

// 新协议实现示例
type CustomProtocolAdapter struct {
    config CustomProtocolConfig
}

func (c *CustomProtocolAdapter) Name() string {
    return "custom"
}

func (c *CustomProtocolAdapter) Start() error {
    // 实现启动逻辑
}

func (c *CustomProtocolAdapter) Stop() error {
    // 实现停止逻辑
}

func (c *CustomProtocolAdapter) HandleMessage(msg Message) error {
    // 实现消息处理逻辑
}
```

### 添加新数据处理规则

1. 在`internal/analytics/`目录下创建规则文件
2. 实现`ProcessingRule`接口
3. 在数据处理器中注册新规则
4. 添加配置选项
5. 编写测试用例

```go
// 处理规则接口
type ProcessingRule interface {
    Name() string
    Apply(data Message) (ProcessedData, error)
}

// 新规则实现示例
type CustomProcessingRule struct {
    config CustomRuleConfig
}

func (c *CustomProcessingRule) Name() string {
    return "custom_rule"
}

func (c *CustomProcessingRule) Apply(data Message) (ProcessedData, error) {
    // 实现数据处理逻辑
}
```

## 部署指南

### Docker部署

1. **构建镜像**
```bash
docker build -t iot-base-station .
```

2. **使用Docker Compose部署**
```bash
docker-compose up -d
```

3. **查看服务状态**
```bash
docker-compose ps
```

### Kubernetes部署

1. **创建命名空间**
```bash
kubectl create namespace iot-base-station
```

2. **部署应用**
```bash
kubectl apply -f k8s/
```

3. **查看部署状态**
```bash
kubectl get pods -n iot-base-station
```

## 监控与运维

### 系统监控

- **应用指标**: Prometheus + Grafana
- **日志收集**: ELK Stack
- **链路追踪**: Jaeger
- **健康检查**: 自定义健康检查端点

### 告警配置

- **系统告警**: 资源使用率、服务可用性
- **业务告警**: 设备离线、数据异常
- **安全告警**: 异常访问、认证失败

## 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 联系方式

如有问题或建议，请提交 Issue 或联系项目维护者

---

**注意**: 这是一个学习项目，不建议直接用于生产环境。在生产环境中使用前，请确保进行充分的安全评估和性能测试。