# emqx-agent

**Repository Path**: numen06/emqx-agent

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-16
- **Last Updated**: 2025-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EMQX 认证与授权管理系统

> 基于 Python FastAPI 的灵活 MQTT 认证与授权管理系统，支持四维度 ACL 规则引擎

[![Python](https://img.shields.io/badge/Python-3.7+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 📑 目录

- [系统架构](#-系统架构)
- [快速开始](#-快速开始)
- [核心功能](#-核心功能)
- [ACL 规则示例](#-acl-规则示例)
- [EMQX 配置](#-emqx-配置)
- [项目结构](#-项目结构)
- [Web 管理界面](#-web-管理界面)
- [测试](#-测试)
- [环境变量配置](#-环境变量配置)
- [核心特性](#-核心特性)
- [故障排查](#-故障排查)

## 📐 系统架构

### 核心概念

```
┌─────────────────────────────────────┐
│        系统管理员 (Admin)            │
│      (环境变量配置)                  │
└─────────────────────────────────────┘
              ↓ 管理后台 (Web UI)
┌─────────────────────────────────────┐
│       多维度认证授权系统              │
│                                     │
│  ┌────────────────────────────┐    │
│  │   MQTT 用户管理             │    │
│  │   • 用户名+密码认证          │    │
│  │   • 超级用户权限             │    │
│  └────────────────────────────┘    │
│                                     │
│  ┌────────────────────────────┐    │
│  │   ACL 规则引擎 (四维度)      │    │
│  │   • Username (支持正则)      │    │
│  │   • Password (可选)          │    │
│  │   • ClientID (支持正则)      │    │
│  │   • Topic (MQTT通配符)       │    │
│  │   组合匹配 + 优先级排序       │    │
│  └────────────────────────────┘    │
│                                     │
│  ┌────────────────────────────┐    │
│  │   认证日志系统               │    │
│  │   • 认证/授权记录            │    │
│  │   • 自动清理                 │    │
│  └────────────────────────────┘    │
└─────────────────────────────────────┘
              ↑ HTTP 回调
┌─────────────────────────────────────┐
│          EMQX Broker                │
│  认证: POST /auth                   │
│  授权: POST /authorize              │
└─────────────────────────────────────┘
```

## 🚀 快速开始

### 安装依赖

```bash
pip3 install -r requirements.txt
```

### 启动服务

```bash
# 直接启动
python3 app/app.py

# 或使用脚本
./run.sh
```

### 访问系统

```
http://localhost:8000
```

**默认管理员**：
- 用户名: `admin`
- 密码: `admin123`

⚠️ **生产环境请务必修改！**

## 📊 核心功能

### 1. MQTT 用户管理

**用途**：创建 MQTT 用户账号，用于标准的用户名+密码认证。

**特性**：
- 密码 bcrypt 加密存储
- 支持超级用户权限（is_superuser）
- 账户激活/禁用状态管理

**API 示例**：

通过 Web 管理界面操作，或使用管理员API：

```bash
# 通过管理员设置 API 创建用户
# 注意：MQTT用户管理集成在系统管理API中
# 具体 API 详见 /docs
```

### 2. ACL 规则管理 (四维度授权)

**API**: `/api/acl-rules`

这是系统的核心功能，支持灵活的四维度组合匹配：

| 维度 | 说明 | 正则支持 | 必填 |
|------|------|----------|------|
| **username** | MQTT 用户名 | ✅ | ❌ |
| **password** | MQTT 密码 | ❌ | ❌ |
| **clientid** | MQTT 客户端ID | ✅ | ❌ |
| **topic** | MQTT 主题 | ✅ (MQTT通配符) | ✅ |

**支持的操作**：
- `publish` - 发布权限
- `subscribe` - 订阅权限
- `all` - 所有权限

**支持的权限**：
- `allow` - 允许
- `deny` - 拒绝

**授权策略**：
- ⚡ **无规则时默认放行**：当系统中没有任何ACL规则时，默认允许所有操作
- 📋 **有规则时按优先级匹配**：按优先级（从高到低）依次匹配，返回第一个匹配的规则结果
- ❓ **无匹配时返回 ignore**：有规则但都不匹配时，返回 `ignore` 状态

### 3. 认证日志管理

**API**: `/api/auth-logs`

自动记录所有认证和授权事件，支持：
- 认证成功/失败记录
- 授权允许/拒绝记录
- IP 地址追踪
- 自动清理旧日志（可配置保留数量和天数）

## 🛡️ ACL 规则示例

**API**: `/api/acl-rules`

基于四个维度创建灵活的访问控制规则。

### 规则类型

#### 1. 纯主题规则（最宽松）
```bash
curl -X POST "http://localhost:8000/api/acl-rules" \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "$SYS/#",
    "action": "all",
    "permission": "deny",
    "priority": 100,
    "description": "禁止所有人访问系统主题"
  }'
```

#### 2. 用户级规则
```bash
curl -X POST "http://localhost:8000/api/acl-rules" \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin_user",
    "topic": "#",
    "action": "all",
    "permission": "allow",
    "priority": 100,
    "description": "管理员拥有所有主题权限"
  }'
```

#### 3. 客户端级规则（支持正则）
```bash
curl -X POST "http://localhost:8000/api/acl-rules" \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "clientid": "sensor.*",
    "clientid_regex": true,
    "topic": "sensor/#",
    "action": "publish",
    "permission": "allow",
    "priority": 50,
    "description": "所有传感器设备只能发布到sensor主题"
  }'
```

#### 4. 组合规则（最严格）
```bash
curl -X POST "http://localhost:8000/api/acl-rules" \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user001",
    "clientid": "device001",
    "topic": "device/001/#",
    "action": "all",
    "permission": "allow",
    "priority": 80,
    "description": "特定用户使用特定设备访问特定主题"
  }'
```

#### 5. 基于密码的免认证规则
```bash
curl -X POST "http://localhost:8000/api/acl-rules" \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "password": "device-token-123",
    "clientid": "iot-device-.*",
    "clientid_regex": true,
    "topic": "iot/#",
    "action": "all",
    "permission": "allow",
    "priority": 60,
    "description": "IoT设备使用共享密码免用户名认证"
  }'
```

### 匹配规则说明

1. **优先级匹配**：按 `priority` 从高到低匹配，第一个匹配的规则生效
2. **正则表达式**：`username_regex` 和 `clientid_regex` 启用正则匹配
3. **MQTT 通配符**：`topic` 支持 `#` (多级) 和 `+` (单级) 通配符
4. **维度组合**：所有指定的维度都必须匹配才生效（AND 逻辑）
5. **默认拒绝**：无匹配规则时默认拒绝访问

## 📡 EMQX 配置

### Dashboard 配置

#### 认证配置

1. 访问控制 → 认证 → 创建
2. 类型：Password-Based → HTTP Server
3. URL：`http://localhost:8000/auth`
4. 请求体：
```json
{
  "username": "${username}",
  "password": "${password}",
  "clientid": "${clientid}"
}
```

#### 授权配置

1. 访问控制 → 授权 → 创建
2. 类型：HTTP Server
3. URL：`http://localhost:8000/authorize`
4. 请求体：
```json
{
  "username": "${username}",
  "clientid": "${clientid}",
  "topic": "${topic}",
  "action": "${action}"
}
```

### 配置文件方式

```hocon
# 认证
authentication = [
  {
    mechanism = password_based
    backend = http
    method = post
    url = "http://localhost:8000/auth"
    body {
      username = "${username}"
      password = "${password}"
      clientid = "${clientid}"
    }
    headers {
      "Content-Type" = "application/json"
    }
  }
]

# 授权
authorization {
  sources = [
    {
      type = http
      method = post
      url = "http://localhost:8000/authorize"
      body {
        username = "${username}"
        clientid = "${clientid}"
        topic = "${topic}"
        action = "${action}"
      }
      headers {
        "Content-Type" = "application/json"
      }
    }
  ]
  no_match = deny
}
```

## 📁 项目结构

```
emqx-agent/
├── app/                      # 应用主目录
│   ├── models/              # 数据模型（SQLAlchemy）
│   │   ├── mqtt_user.py     # MQTT 用户（用户名+密码认证）
│   │   ├── acl_rule.py      # ACL 规则（四维度授权）
│   │   └── auth_log.py      # 认证授权日志
│   ├── schemas/             # Pydantic 数据模式
│   │   ├── auth.py          # 认证授权请求/响应
│   │   ├── acl_rule.py      # ACL规则CRUD
│   │   ├── auth_log.py      # 日志查询
│   │   └── common.py        # 通用响应
│   ├── api/                 # API 路由
│   │   ├── auth.py          # EMQX 认证授权接口
│   │   ├── acl_rules.py     # ACL 规则管理
│   │   ├── auth_logs.py     # 认证日志管理
│   │   └── admin_settings.py # 系统管理设置
│   ├── core/                # 核心功能
│   │   ├── security.py      # 密码加密、Basic Auth
│   │   └── acl_matcher.py   # ACL 匹配引擎（正则+通配符）
│   ├── static/              # Web 管理界面
│   │   ├── login.html       # 登录页面
│   │   ├── index.html       # 管理后台
│   │   ├── css/             # 样式文件
│   │   └── libs/            # JS库（Bootstrap、MQTT.js）
│   ├── config.py            # 配置管理（环境变量）
│   ├── database.py          # 数据库连接和初始化
│   └── app.py               # FastAPI 应用入口
├── run.sh                   # 启动脚本
├── requirements.txt         # Python 依赖
├── Dockerfile               # Docker 镜像构建
├── emqx-config-example.conf # EMQX 配置示例
└── README.md                # 本文档
```

## 🎨 Web 管理界面

访问 `http://localhost:8000`，自动跳转到登录页面。

登录后可访问管理后台 `/admin`，包含以下功能：

1. **系统概览** - 统计信息和快速链接
2. **MQTT 用户管理** - 用户增删改查
3. **ACL 规则管理** - 四维度规则配置
4. **认证日志** - 实时查看认证授权记录
5. **系统设置** - 管理员密码修改等
6. **API 文档** - Swagger UI 文档链接

界面基于 Bootstrap 5 构建，响应式设计，支持移动端访问。

## 🧪 测试

### 1. 测试认证接口

```bash
# 测试用户认证（假设已创建 test_user）
curl -X POST "http://localhost:8000/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test_user",
    "password": "test123",
    "clientid": "test-client"
  }'

# 预期响应：{"result":"allow","is_superuser":false}
```

### 2. 测试授权接口

```bash
# 测试主题授权
curl -X POST "http://localhost:8000/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test_user",
    "clientid": "test-client",
    "topic": "test/topic",
    "action": "publish"
  }'

# 预期响应：{"result":"allow"} 或 {"result":"deny"}
```

### 3. 测试管理 API

```bash
# 获取所有 ACL 规则
curl -X GET "http://localhost:8000/api/acl-rules" \
  -u admin:admin123

# 查看认证日志
curl -X GET "http://localhost:8000/api/auth-logs?limit=10" \
  -u admin:admin123
```

## 📖 API 文档

- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

## 🔐 环境变量配置

创建 `.env` 文件：

```bash
# 系统管理员配置
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_secure_password

# 数据库配置
DATABASE_URL=sqlite:///./emqx_auth.db

# 服务器配置
HOST=0.0.0.0
PORT=8000

# 日志配置
LOG_LEVEL=INFO

# 认证日志清理配置（可选）
MAX_AUTH_LOG_COUNT=10000    # 最大保留日志数量
MAX_AUTH_LOG_DAYS=30        # 最大保留天数

# 安全配置（可选）
SECRET_KEY=your-secret-key-here
```

**注意**：
- 生产环境必须修改 `ADMIN_PASSWORD`
- `SECRET_KEY` 用于未来的 Token 认证功能
- 认证日志会自动清理，防止数据库过大

## 🐳 Docker 部署

```bash
# 构建
docker build -t emqx-auth .

# 运行
docker run -d -p 8000:8000 \
  -e ADMIN_PASSWORD=your_password \
  emqx-auth
```

## 🔑 核心特性

✅ **灵活的四维度授权**  
支持 username、password、clientid、topic 任意组合

✅ **正则表达式支持**  
username 和 clientid 支持正则匹配，批量管理设备

✅ **MQTT 通配符**  
topic 支持 `#` 和 `+` 通配符

✅ **优先级机制**  
规则按优先级排序，精确控制匹配顺序

✅ **双重认证模式**  
支持标准的用户名+密码认证，也支持基于 ACL 的免密码认证

✅ **实时日志记录**  
自动记录所有认证授权事件，支持审计和问题排查

✅ **自动日志清理**  
防止日志表无限增长，可配置保留策略

✅ **Web 管理界面**  
Bootstrap 5 响应式界面，操作简单直观

✅ **RESTful API**  
完整的 REST API 支持自动化管理

✅ **生产就绪**  
使用 SQLAlchemy ORM，支持 SQLite/MySQL/PostgreSQL

## 🆘 故障排查

### 1. 无法启动服务

```bash
# Windows - 检查端口占用
netstat -ano | findstr :8000

# Linux/Mac - 检查端口占用
lsof -i :8000

# 检查 Python 环境
python --version  # 需要 Python 3.7+
pip list | grep fastapi
```

### 2. 管理员登录失败

```bash
# 测试管理员凭证（默认 admin/admin123）
curl -u admin:admin123 http://localhost:8000/api/acl-rules

# 如果失败，检查环境变量
echo $ADMIN_USERNAME
echo $ADMIN_PASSWORD
```

### 3. EMQX 认证失败

**检查步骤**：
1. 在 Web 界面查看认证日志 `/api/auth-logs`
2. 确认 MQTT 用户已创建且状态为激活
3. 确认 ACL 规则配置正确
4. 检查 EMQX 配置中的回调 URL 是否正确

```bash
# 手动测试认证接口
curl -X POST "http://localhost:8000/auth" \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test","clientid":"client1"}'
```

### 4. EMQX 授权失败

```bash
# 手动测试授权接口
curl -X POST "http://localhost:8000/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "username":"test",
    "clientid":"client1",
    "topic":"test/topic",
    "action":"publish"
  }'

# 查看匹配到的规则（通过日志）
curl -u admin:admin123 "http://localhost:8000/api/auth-logs?limit=20"
```

### 5. 数据库问题

```bash
# 删除数据库重新初始化
rm emqx_auth.db
python app/app.py  # 会自动创建新数据库
```

## 📝 许可证

MIT License

## 🤝 技术支持

- **API 文档**: http://localhost:8000/docs
- **健康检查**: http://localhost:8000/health
- **系统信息**: http://localhost:8000/api/info
- **认证日志**: http://localhost:8000/api/auth-logs （需要管理员权限）

## 📋 使用场景

1. **IoT 设备管理**：使用 clientid 正则批量管理大量设备
2. **多租户系统**：不同用户访问不同主题命名空间
3. **分级权限**：通过优先级实现复杂的权限继承
4. **临时访问**：使用密码维度实现 Token 式访问
5. **审计合规**：完整的认证授权日志记录

## 🔄 版本历史

**v2.0.0** (2025-10-17)
- ✅ 重构为四维度 ACL 规则系统
- ✅ 新增认证日志功能
- ✅ 新增正则表达式支持
- ✅ 优化 Web 管理界面
- ✅ 改进 API 文档

**v1.x**
- 基础的三维度管理系统

---

**当前版本**: v2.0.0  
**状态**: ✅ 生产就绪  
**更新时间**: 2025-10-17  
**技术栈**: Python 3.7+ • FastAPI • SQLAlchemy • Bootstrap 5