# QoderCloud

**Repository Path**: zhongjack/qoder-cloud

## Basic Information

- **Project Name**: QoderCloud
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-07
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IoT Cloud Platform

一个使用 Go 语言构建的高性能、高可用、可扩展的物联网云平台，支持百万级设备连接、实时数据处理和智能告警系统。

## 🏗️ 架构概述

### 核心服务
- **设备管理服务**: 设备生命周期管理、设备影子
- **认证服务**: JWT/OAuth2 认证、RBAC 授权
- **遥测服务**: 时序数据采集和存储
- **命令服务**: 远程设备控制和命令调度
- **规则引擎**: 实时数据处理和告警系统
- **API 网关**: RESTful APIs，支持限流和负载均衡

### 技术栈
- **后端**: Go + Gin 框架
- **数据库**: PostgreSQL (元数据), Redis (缓存), InfluxDB (时序数据)
- **消息队列**: Apache Kafka
- **MQTT Broker**: EMQX 集成
- **部署**: Docker + Kubernetes
- **监控**: Prometheus + Grafana

## 🚀 快速开始

### 前置要求
- Go 1.21+
- Docker & Docker Compose
- PostgreSQL 15+
- Redis 7+
- InfluxDB 2.7+
- Apache Kafka
- EMQX MQTT Broker

### 安装步骤

1. **克隆仓库**
```bash
git clone <repository-url>
cd iot-cloud-platform
```

2. **安装依赖**
```bash
go mod tidy
```

3. **配置环境变量**
```bash
cp config/config.yaml config/config.local.yaml
# 编辑 config.local.yaml 设置您的配置
```

4. **使用 Docker Compose 启动**
```bash
docker-compose up -d
```

5. **启动平台**
```bash
go run cmd/main.go
```

### 使用 Kubernetes 部署

```bash
# 创建命名空间和基础设施
kubectl apply -f k8s/infrastructure.yaml

# 部署应用
kubectl apply -f k8s/deployment.yaml

# 检查部署状态
kubectl get pods -n iot-platform
```

## 📡 API 文档

### 认证
- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/register` - 用户注册
- `POST /api/v1/auth/refresh` - 刷新令牌
- `POST /api/v1/auth/logout` - 用户登出

### 设备管理
- `POST /api/v1/devices` - 注册新设备
- `GET /api/v1/devices` - 设备列表
- `GET /api/v1/devices/{id}` - 获取设备详情
- `PUT /api/v1/devices/{id}` - 更新设备
- `DELETE /api/v1/devices/{id}` - 删除设备
- `GET /api/v1/devices/{id}/shadow` - 获取设备影子
- `PUT /api/v1/devices/{id}/shadow` - 更新设备影子

### 遥测数据
- `POST /api/v1/telemetry` - 提交遥测数据
- `POST /api/v1/telemetry/batch` - 批量提交遥测数据
- `GET /api/v1/telemetry/{deviceId}` - 获取设备遥测历史
- `GET /api/v1/telemetry/{deviceId}/latest` - 获取最新遥测数据
- `GET /api/v1/telemetry/{deviceId}/aggregated` - 获取聚合数据
- `GET /api/v1/telemetry/{deviceId}/summary` - 获取数据摘要

### 命令控制
- `POST /api/v1/commands/{deviceId}` - 向设备发送命令
- `GET /api/v1/commands/{deviceId}` - 获取命令历史
- `GET /api/v1/commands/{commandId}/status` - 获取命令状态

## 🔧 配置说明

详细配置选项请参考 `config/config.yaml`：

```yaml
server:
  port: 8080
  mode: development # development, production
  host: localhost

database:
  host: localhost
  port: 5432
  user: postgres
  password: password
  dbname: iot_platform
  sslmode: disable

mqtt:
  broker: tcp://localhost:1883
  client_id: iot-platform
  username: ""
  password: ""

kafka:
  brokers:
    - localhost:9092
  topics:
    telemetry: telemetry-data
    commands: device-commands
    alerts: system-alerts
```

## 🏢 核心特性

### 高并发与低延迟
- 支持百万级设备并发连接
- MQTT 消息处理延迟 < 100ms
- 使用连接池和缓存优化性能

### 高可用性
- 微服务架构，无单点故障
- 数据库主从复制
- Redis 集群模式
- Kafka 分区容错

### 安全性
- JWT 令牌认证
- RBAC 权限控制
- TLS/SSL 加密传输
- API 限流保护

### 可扩展性
- Kubernetes 水平扩缩容
- 数据库分片支持
- 微服务独立部署

## 📊 监控与运维

### 健康检查
```bash
curl http://localhost:8080/health
```

### 监控指标
- **Prometheus**: http://localhost:9090
- **Grafana**: http://localhost:3000 (admin/admin)
- **EMQX Dashboard**: http://localhost:18083 (admin/public)

### 日志管理
```bash
# 查看应用日志
docker-compose logs -f iot-platform

# 查看 Kubernetes 日志
kubectl logs -f deployment/iot-platform-app -n iot-platform
```

## 🧪 测试

### 运行单元测试
```bash
go test ./...
```

### 运行集成测试
```bash
go test -tags=integration ./...
```

### 性能测试
```bash
# 使用 Apache Bench 测试 API
ab -n 1000 -c 100 http://localhost:8080/health

# 使用 MQTT 客户端测试设备连接
mosquitto_pub -h localhost -p 1883 -t "devices/test-device/telemetry" -m '{"temperature": 25.5}'
```

## 🔄 设备接入示例

### MQTT 客户端接入
```python
import json
import time
import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, rc):
    print(f"Connected with result code {rc}")
    # 订阅命令主题
    client.subscribe("devices/your-device-id/commands")

def on_message(client, userdata, msg):
    print(f"Received command: {msg.payload.decode()}")
    # 处理命令并发送响应
    response = {
        "command_id": "command-id-from-payload",
        "status": "success",
        "message": "Command executed successfully"
    }
    client.publish("devices/your-device-id/responses", json.dumps(response))

# 创建 MQTT 客户端
client = mqtt.Client()
client.username_pw_set("your-device-name", "your-device-secret")
client.on_connect = on_connect
client.on_message = on_message

# 连接到 MQTT Broker
client.connect("localhost", 1883, 60)

# 发送遥测数据
while True:
    telemetry = {
        "timestamp": int(time.time()),
        "temperature": 25.5,
        "humidity": 60.0,
        "location": {
            "latitude": 39.9042,
            "longitude": 116.4074
        }
    }
    client.publish("devices/your-device-id/telemetry", json.dumps(telemetry))
    time.sleep(30)
```

### HTTP API 接入
```bash
# 1. 注册设备
curl -X POST http://localhost:8080/api/v1/devices \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_key": "your-product",
    "device_name": "sensor-001",
    "description": "Temperature sensor"
  }'

# 2. 提交遥测数据
curl -X POST http://localhost:8080/api/v1/telemetry \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "device-uuid",
    "data": {
      "temperature": 25.5,
      "humidity": 60.0
    }
  }'

# 3. 发送命令到设备
curl -X POST http://localhost:8080/api/v1/commands/device-uuid \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "set_temperature",
    "payload": {
      "method": "SET",
      "parameters": {
        "target_temp": 22.0
      }
    }
  }'
```

## 🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交变更 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Pull Request

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 📞 支持

如有问题或建议，请：
- 提交 [Issue](https://github.com/your-repo/iot-cloud-platform/issues)
- 发送邮件至 support@iot-platform.com
- 查看 [Wiki](https://github.com/your-repo/iot-cloud-platform/wiki) 文档

---

⭐ 如果这个项目对您有帮助，请给个星标支持！