# GopherHub

**Repository Path**: Lin-carp/gopher-hub

## Basic Information

- **Project Name**: GopherHub
- **Description**: mqtt设备管理服务端，包含设备的授权，规则引擎，权限管理，后期会配套linux设备的管理系统，利用该平台进行命令下发
- **Primary Language**: Go
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GopherHub (plugin skeleton)

This is a runnable Go skeleton for a plugin-based service framework.

## What you get

- `core/`: minimal plugin framework + in-process pub/sub event bus
- `plugins/httpserver`: HTTP service plugin (receives HTTP requests and publishes events)
- `plugins/httpconsumer`: subscriber plugin (subscribes to HTTP events and processes request data)
- `plugins/mqttmochi`: MQTT broker plugin (embeds mochi-mqtt broker for IoT device management)
- `plugins/mqttconsumer`: MQTT consumer plugin (subscribes to MQTT events, prints device data, and writes to InfluxDB)
- `plugins/deviceauth`: Device authentication plugin (manages device registration and activation using SQLite)
- `cmd/server`: bootstrap that loads plugins and handles graceful shutdown

## Run

```bash
go run ./cmd/server
```

### 打包为 Linux (Ubuntu) 可执行文件

在 **Windows** 上可交叉编译出 Ubuntu 常见的 **x86_64 (amd64)** 单文件，无需在 Linux 上安装 Go。

**PowerShell：**

```powershell
cd <项目根目录>

$env:GOOS = "linux"
$env:GOARCH = "amd64"
$env:CGO_ENABLED = "0"

go build -trimpath -ldflags="-s -w" -o dist/gopherhub-linux-amd64 ./cmd/server
```

**CMD：**

```cmd
set GOOS=linux
set GOARCH=amd64
set CGO_ENABLED=0
go build -trimpath -ldflags="-s -w" -o dist/gopherhub-linux-amd64 ./cmd/server
```

将生成的 `dist/gopherhub-linux-amd64` 拷贝到 Ubuntu，赋予执行权限后运行：

```bash
chmod +x gopherhub-linux-amd64
./gopherhub-linux-amd64
```

请同时部署 **`config.yaml`**以及已有的 **`devices.db`**（若需要保留数据），与工作目录或你指定的配置路径一致。

**CPU 架构：**

| 目标环境 | `GOARCH` |
|---------|----------|
| 常见 PC / 云服务器 Ubuntu | `amd64` |
| ARM64（部分云主机、树莓派 64 位等） | `arm64` |

构建 ARM64 时把上面命令里的 `GOARCH` 改为 `arm64`，输出文件名可改为例如 `gopherhub-linux-arm64`。

**说明：** 本项目使用 `modernc.org/sqlite`（纯 Go），`CGO_ENABLED=0` 即可；`-ldflags="-s -w"` 用于减小体积。若需保留调试符号做性能分析，可去掉该 ldflags。

The server will start:
- HTTP API server on `http://localhost:8080`
- MQTT broker on `tcp://localhost:1883` (embedded mochi-mqtt)
- SQLite database for device authentication (`devices.db`)

### Test HTTP API


Send a request:

```bash
curl -X POST "http://localhost:8080/ingest?source=demo" -H "Content-Type: application/json" -d "{\"hello\":\"world\"}"
```

Watch the server logs: the `httpconsumer` plugin will print the received request details.

### Test MQTT Broker

The embedded mochi-mqtt broker is ready to accept MQTT connections on `tcp://localhost:1883`. 

#### Connection Parameters

- **Broker Address**: `tcp://localhost:1883`
- **Authentication**: Anonymous (no username/password required)
- **Client ID**: Any unique string (e.g., "my-device-001")

#### Using Command Line Tools (mosquitto)

**Publish device telemetry:**
```bash
mosquitto_pub -h localhost -p 1883 -t "devices/device123/telemetry" -m '{"temperature":25.5,"humidity":60}'
```

**Publish device status:**
```bash
mosquitto_pub -h localhost -p 1883 -t "devices/device123/status" -m '{"online":true}'
```

**Subscribe to device commands:**
```bash
mosquitto_sub -h localhost -p 1883 -t "devices/device123/command"
```

#### Using Go Test Demo

Run the comprehensive test demo:

```bash
go run examples/mqtt_test_demo.go
```

This demo will:
- Connect to the MQTT broker
- Subscribe to device commands
- Publish device status (online)
- Publish telemetry data every 5 seconds

See `examples/README.md` for more details and other examples.

### Device Authentication

The system includes a complete device registration and activation flow:

1. **Device Registration**: When a device first connects, it's automatically registered in the `pending_devices` table
2. **Device Activation**: Administrators can view pending devices and activate them via HTTP API
3. **Communication Control**: Only activated devices can send telemetry data

**API Endpoints:**
- `GET /api/devices/pending` - List pending devices
- `GET /api/devices/activated` - List activated devices  
- `POST /api/devices/activate` - Activate a device

**Example:**
```bash
# View pending devices
curl http://localhost:8080/api/devices/pending

# Activate a device
curl -X POST http://localhost:8080/api/devices/activate \
  -H "Content-Type: application/json" \
  -d '{"device_id": "device123", "activated_by": "admin"}'
```

See `docs/DEVICE_AUTH.md` for detailed documentation.

#### Using Python Client (paho-mqtt)

```python
import paho.mqtt.client as mqtt

broker = "localhost"
port = 1883
client_id = "python-client-001"

def on_connect(client, userdata, flags, rc):
    print(f"Connected with result code {rc}")
    client.subscribe("devices/+/command")

def on_message(client, userdata, msg):
    print(f"Received: {msg.topic} -> {msg.payload.decode()}")

client = mqtt.Client(client_id)
client.on_connect = on_connect
client.on_message = on_message
client.connect(broker, port, 60)
client.loop_forever()
```

#### Topic Structure

- **Device Telemetry**: `devices/{deviceId}/telemetry` - 设备上报遥测数据
- **Device Status**: `devices/{deviceId}/status` - 设备状态更新
- **Device Commands**: `devices/{deviceId}/command` - 服务器下发命令到设备

The MQTT plugin will automatically:
- Subscribe to `devices/+/telemetry` and `devices/+/status` topics
- Convert MQTT messages to EventBus events
- Publish commands from EventBus to MQTT topics