# magistrala

**Repository Path**: kdisi_admin/magistrala

## Basic Information

- **Project Name**: magistrala
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Magistrala 物联平台

<div align="center">

**Abstract Machines** 出品的现代化可扩展 IoT 平台框架

[![Build Status](https://github.com/absmach/magistrala/actions/workflows/build.yaml/badge.svg?branch=main)](https://github.com/absmach/magistrala/actions/workflows/build.yaml)
[![Go Report Card](https://goreportcard.com/badge/github.com/absmach/magistrala)](https://goreportcard.com/report/github.com/absmach/magistrala)
[![Coverage](https://codecov.io/gh/absmach/magistrala/graph/badge.svg?token=nPCEr5nW8S)](https://codecov.io/gh/absmach/magistrala)
[![License](https://img.shields.io/badge/license-Apache%20v2.0-blue.svg)](LICENSE)

[English](README.md) | 中文

</div>

---

## 项目简介

Magistrala 是一个开源的 IoT（物联网）平台，专为需要全面掌控消息、设备管理和数据管道的工程师设计。

平台基于 [FluxMQ](https://github.com/absmach/fluxmq) 构建 —— 一个同时支持消息队列和事件流的现代消息代理。Magistrala 在其周围提供一切所需：**身份认证**、**访问控制**、**设备接入**、**数据处理** 和 **可观测性**。

IoT 系统通常涉及消息代理、数据库、规则引擎和各种定制服务。Magistrala 并非要让这些组件消失，而是提供一个统一的框架，将它们整合为一个具备一致的**身份模型**、**访问控制**、**消息模型** 和 **可观测性**的整体系统。

**Magistrala 是什么：**
- 事件驱动的 IoT 中间件平台
- 设备、用户和数据的统一控制平面
- 构建可扩展 IoT 系统的基础设施

**Magistrala 不是：**
- 不仅仅是 MQTT Broker
- 不是黑盒 SaaS 服务
- 不绑定单一云厂商或供应商

---

## 核心概念

Magistrala 的设计围绕少数几个核心概念，大多数工程师已经熟悉，可以立即上手：

| 概念 | 说明 |
|------|------|
| **User** | 平台用户，支持多租户域名隔离 |
| **Client** | 设备或应用程序实体（也称 Device） |
| **Channel** | 消息通道，用于组织和控制消息流 |
| **Message** | 设备与应用之间的消息，支持 SENML 格式 |
| **Domain** | 多租户域名，用于隔离不同组织/环境 |
| **Policy** | 基于 SpiceDB 的细粒度访问控制策略 |

### 数据模型关系

```
Domain (域名)
├── Users (用户)
│   └── Credentials (用户名/密码)
│   └── Tags, Metadata
├── Clients (设备/客户端)
│   ├── Identity + Secret (设备凭证)
│   └── Connected Channels
└── Channels (通道)
    └── Connected Clients
    └── Route (路由标识)
```

你可以保持简单：
- 连接设备 → 发送消息 → 存储数据

也可以深入：
- 定义复杂访问控制策略
- 构建事件驱动数据管道
- 集成自定义处理和自动化逻辑

---

## 技术架构

### 服务组件

Magistrala 由多个微服务组成，通过 Docker Compose 部署：

| 服务 | 端口 | 说明 |
|------|------|------|
| `auth` | 9001 | 认证服务，支持 JWT/X.509/PAT 多重认证 |
| `users` | 9002 | 用户管理，注册/登录/密码重置 |
| `domains` | 9003 | 多租户域名管理，角色/邀请 |
| `groups` | 9004 | 设备分组，层级结构 |
| `channels` | 9005 | 消息通道管理，连接管理 |
| `clients` | 9006 | 设备/客户端生命周期管理 |
| `certs` | 9019 | X.509 证书管理 |
| `alarms` | - | 告警管理，触发器 |
| `reports` | - | 报表服务 |
| `re` | - | 规则引擎，消息处理与路由 |
| `bootstrap` | - | 设备引导配置 |
| `provision` | - | 设备配置服务 |
| `journal` | 9021 | 审计日志 |
| `notifications` | - | 通知服务（Email/Slack/Webhook） |
| `postgres-writer/reader` | 5432 | PostgreSQL 数据读写 |
| `timescale-writer/reader` | 5432 | TimescaleDB 时序数据 |
| `fluxmq` | 9081-9083 | 消息代理集群 (AMQP/MQTT) |

### 协议支持

| 协议 | 用途 | 说明 |
|------|------|------|
| **MQTT** | 设备连接 | QoS 0/1/2 支持 |
| **HTTP** | REST API | JSON 格式 |
| **WebSocket** | 实时通信 | 双向通信 |
| **CoAP** | 轻量设备 | 适用于受限设备 |
| **AMQP** | 内部通信 | 服务间消息传递 |
| **gRPC** | 服务间通信 | 高性能 RPC |

### 技术栈

- **语言**: Go 1.26
- **数据库**: PostgreSQL + TimescaleDB
- **消息代理**: FluxMQ (RabbitMQ/AMQP 0-9-1)
- **缓存**: Redis
- **访问控制**: SpiceDB (Authzed) - ABAC + RBAC
- **可观测性**: Prometheus + OpenTelemetry + Jaeger
- **部署**: Docker + Kubernetes

### 消息代理配置

Magistrala 支持灵活的消息代理组合：

| MQTT Broker | Message Broker | Event Store |
|-------------|---------------|-------------|
| RabbitMQ | NATS | NATS / Redis |
| RabbitMQ | RabbitMQ | RabbitMQ / Redis |
| NATS | RabbitMQ | RabbitMQ / Redis |
| NATS | NATS | NATS / Redis |

---

## 主要特性

### 身份与安全

- 多租户域名隔离 (Domain)
- 用户、角色、组织层级
- 细粒度访问控制 (ABAC + RBAC)
- 双向 TLS (X.509) 和 JWT 认证
- **个人访问令牌 (PAT)**，支持作用域和撤销
- 支持邀请码注册

### 设备连接

- MQTT/HTTP/WebSocket/CoAP 原生支持
- 统一的认证授权模型
- 设备凭证 (Identity + Secret)
- 适用于云服务和受限设备

### 数据处理

- **规则引擎 (Rules Engine)**：消息处理、路由、转换
- **告警 (Alarms)**：基于条件触发
- **报表 (Reports)**：数据聚合报表
- 定时任务：基于时间的自动化工作流
- 事件驱动架构

### 可观测性

- **审计日志 (Journal)**：记录所有操作
- **Prometheus** 指标采集
- **OpenTelemetry** 分布式追踪
- **Jaeger** 链路追踪

### 开发者工具

- **Go SDK** (`pkg/sdk`)
- **CLI 工具** (`cmd/cli`)
- **OpenAPI 文档** (`apidocs/`)
- gRPC API 支持

---

## 快速开始

### 环境要求

- Docker & Docker Compose
- Go 1.26+ (本地开发)
- Make

### 使用 Docker 启动

```bash
git clone https://github.com/absmach/magistrala.git
cd magistrala
make run_latest
```

访问地址：
- UI: http://localhost
- Users API: http://localhost:9002
- Auth API: http://localhost:9001
- Channels API: http://localhost:9005
- Clients API: http://localhost:9006
- Domains API: http://localhost:9003

### 本地开发

```bash
# 编译所有服务
make all

# 构建 Docker 镜像
make dockers

# 运行开发模式
make rundev
```

### 使用 CLI

```bash
make cli
./build/cli health <service>
```

### 运行测试

```bash
# 需要先设置 USER_TOKEN
export USER_TOKEN=<your-token>
make test_api_users
```

---

## 目录结构

```
magistrala/
├── cmd/                    # 各服务的入口点 (main.go)
│   ├── auth/               # 认证服务入口
│   ├── users/              # 用户服务入口
│   ├── clients/            # 客户端服务入口
│   ├── channels/           # 通道服务入口
│   ├── domains/            # 域名服务入口
│   └── ...
├── pkg/                    # 可复用的包
│   ├── authn/              # 认证中间件
│   ├── authz/              # 授权中间件
│   ├── sdk/                # Go SDK
│   ├── server/             # HTTP/gRPC/CoAP 服务器
│   ├── postgres/           # PostgreSQL 连接
│   ├── messaging/          # 消息相关
│   ├── events/             # 事件存储
│   └── ...
├── internal/               # 内部共享代码
├── api/                    # gRPC API 定义
├── apidocs/                # OpenAPI 文档
├── docker/                 # Docker Compose 配置
│   ├── docker-compose.yaml # 主配置文件
│   ├── .env                # 环境变量
│   └── ssl/                # TLS 证书
├── scripts/                # 脚本工具
├── users/                  # 用户服务实现
├── auth/                   # 认证服务实现
├── clients/                # 设备/客户端服务实现
├── channels/               # 通道服务实现
├── domains/                # 域名服务实现
├── notifications/          # 通知服务实现
├── certs/                  # 证书服务实现
├── re/                     # 规则引擎实现
├── alarms/                # 告警服务实现
├── reports/                # 报表服务实现
├── bootstrap/              # 设备引导服务
├── provision/              # 配置服务
├── journal/                # 审计日志服务
└── fluxmq/                 # 消息代理集成
```

---

## API 使用示例

### 用户注册与登录

```bash
# 注册用户
curl -X POST "http://localhost:9002/users" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "credentials": { "username": "ada", "secret": "changeMe123" },
    "email": "ada@example.com"
  }'

# 登录获取 Token
curl -X POST "http://localhost:9002/users/tokens/issue" \
  -H "Content-Type: application/json" \
  -d '{ "identity": "ada@example.com", "secret": "changeMe123" }'
```

### 创建设备

```bash
curl -X POST "http://localhost:9006/<domainID>/clients" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "temperature-sensor",
    "tags": ["sensor", "temp"],
    "credentials": { "identity": "sensor-001", "secret": "secret123" },
    "status": "enabled"
  }'
```

### 创建通道并连接设备

```bash
# 创建通道
curl -X POST "http://localhost:9005/<domainID>/channels" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "sensor-data", "status": "enabled" }'

# 连接设备到通道
curl -X POST "http://localhost:9005/<domainID>/channels/connect" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_ids": ["<channelID>"],
    "client_ids": ["<clientID>"],
    "types": ["publish", "subscribe"]
  }'
```

### 使用 PAT (个人访问令牌)

```bash
# 创建 PAT
curl -X POST "http://localhost:9001/pats" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-pat", "duration": "24h" }'

# 使用 PAT 进行 API 请求
curl -X GET "http://localhost:9006/<domainID>/clients" \
  -H "Authorization: Bearer pat_<encoded>_<secret>"
```

---

## SDK 使用示例

```go
import "github.com/absmach/magistrala/pkg/sdk"

// 初始化 SDK
cfg := sdk.Config{
    UsersURL:    "http://localhost:9002",
    AuthURL:     "http://localhost:9001",
    ClientsURL:  "http://localhost:9006",
    ChannelsURL: "http://localhost:9005",
    DomainsURL:  "http://localhost:9003",
}

cli := sdk.NewSDK(cfg)

// 创建设备
client := sdk.Client{
    Name: "my-device",
    Tags: []string{"sensor"},
}
err := cli.Clients.Create("domain-id", client)

// 获取设备列表
clients, err := cli.Clients.List("domain-id", sdk.Page{Offset: 0, Limit: 10})
```

---

## 环境变量配置

各服务通过环境变量配置，主要前缀：

| 前缀 | 说明 |
|------|------|
| `MG_AUTH_*` | 认证服务配置 |
| `MG_USERS_*` | 用户服务配置 |
| `MG_CLIENTS_*` | 客户端服务配置 |
| `MG_CHANNELS_*` | 通道服务配置 |
| `MG_DOMAINS_*` | 域名服务配置 |
| `MG_SPICEDB_*` | 权限数据库配置 |
| `MG_JAEGER_*` | 链路追踪配置 |

### 关键配置

```bash
# 认证服务
MG_AUTH_HTTP_PORT=9001
MG_AUTH_GRPC_PORT=8181
MG_AUTH_SECRET_KEY=your-secret-key
MG_AUTH_ACCESS_TOKEN_DURATION=1h
MG_AUTH_REFRESH_TOKEN_DURATION=24h

# 数据库
MG_AUTH_DB_HOST=localhost
MG_AUTH_DB_PORT=5432
MG_AUTH_DB_NAME=auth

# SpiceDB 权限
MG_SPICEDB_HOST=localhost
MG_SPICEDB_PORT=50051
MG_SPICEDB_PRE_SHARED_KEY=12345678

# 消息代理
MG_MESSAGE_BROKER_URL=amqp://guest:guest@localhost:5682/
MG_ES_TYPE=es_fluxmq
MG_ES_URL=amqp://guest:guest@localhost:5682/
```

---

## 贡献代码

欢迎提交 Pull Request！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

### 开发流程

1. Fork 项目仓库
2. 创建特性分支 `MG-[issue-number]`
3. 提交前签署 DCO (Developer Certificate of Origin)
4. 使用 interactive rebase 整理提交
5. Push 到你的 Fork 并提交 Pull Request

---

## 许可证

Apache-2.0