iegomez/mosquitto-go-auth

Mosquitto Go Auth 镜像文档

镜像概述

本镜像为集成了mosquitto-go-auth插件的Mosquitto MQTT broker。mosquitto-go-auth是一个用Go语言编写的认证与授权插件，通过cgo与Mosquitto交互，支持多种后端存储，为MQTT broker提供用户认证、超级用户检查和访问控制列表（ACL）验证功能。插件兼容Mosquitto 2.0及以上版本，适用于需要灵活认证授权机制的MQTT部署场景。

核心功能与特性

多后端支持

插件实现了以下后端，每个后端均支持用户认证、超级用户检查和ACL验证，并包含完整测试：

• 文件（Files）：基于静态文件的认证与授权
• 关系型数据库：PostgreSQL、MySQL、SQLite3
• 分布式存储：Redis、MongoDB
• API与协议：HTTP、gRPC、JWT（本地数据库或远程API模式）
• 其他：Javascript解释器、自定义后端（实验性）

高级特性

• 缓存机制：支持内存缓存（go-cache）或Redis缓存，可配置缓存过期时间、抖动值及刷新策略，减少后端负载
• 哈希算法：支持PBKDF2（默认）、Bcrypt、Argon2ID三种密码哈希算法，可全局或按后端配置
• 日志控制：可设置日志级别（debug/info/warn/error等）及输出目标（stderr/stdout/文件）
• 前缀路由：支持用户名前缀（如prefix_username），指定特定后端处理认证请求
• 重试机制：支持后端请求重试，应对负载均衡场景下的实例故障

使用场景

• IoT设备管理：通过JWT或HTTP后端验证设备身份，结合ACL控制设备消息发布/订阅权限
• 多租户系统：使用PostgreSQL/MySQL后端隔离不同租户的用户数据与权限
• 分布式部署：通过Redis缓存或gRPC后端实现跨节点认证状态共享
• 调试与本地测试：使用Files或SQLite3后端快速配置静态认证规则

使用方法与配置说明

基础配置

镜像启动需挂载Mosquitto配置文件（通常为mosquitto.conf），并在配置中指定插件路径及后端。示例配置片段：

conf
# 加载插件
auth_plugin /etc/mosquitto/go-auth.so

# 启用的后端（按优先级排序）
auth_opt_backends files,postgres,jwt

# 通用缓存配置
auth_opt_cache true
auth_opt_cache_type redis
auth_opt_auth_cache_seconds 30
auth_opt_acl_cache_seconds 30

# 哈希算法配置（全局）
auth_opt_hasher bcrypt
auth_opt_hasher_cost 10

核心配置选项

缓存配置

哈希配置

支持PBKDF2、Bcrypt、Argon2ID，以Bcrypt为例：

conf
auth_opt_hasher bcrypt
auth_opt_hasher_cost 12  # 计算强度（4-31）

日志配置

conf
auth_opt_log_level info  # 日志级别：debug/info/warn/error/fatal/panic
auth_opt_log_dest file   # 输出目标：stderr/stdout/file
auth_opt_log_file /var/log/mosquitto/auth.log  # 文件路径（仅file模式）

后端配置示例

Files后端

通过静态文件实现认证与授权：

conf
auth_opt_files_password_path /etc/mosquitto/passwords.txt  # 密码文件路径
auth_opt_files_acl_path /etc/mosquitto/acls.txt            # ACL文件路径

密码文件格式（PBKDF2哈希示例）：

user1:PBKDF2$sha512$100000$salt$hash
user2:PBKDF2$sha512$100000$salt$hash

ACL文件格式（遵循Mosquitto语法）：

user user1
topic write sensor/temp
topic read sensor/humidity

user user2
topic read sensor/#

PostgreSQL后端

通过数据库查询实现认证：

conf
auth_opt_pg_host postgres
auth_opt_pg_port 5432
auth_opt_pg_user dbuser
auth_opt_pg_password dbpass
auth_opt_pg_dbname mqtt_auth
auth_opt_pg_userquery "SELECT password FROM users WHERE username = $1"  # 用户查询
auth_opt_pg_aclquery "SELECT topic FROM acls WHERE username = $1 AND access = $2"  # ACL查询

Docker部署示例

单容器部署

bash
docker run -d \
  --name mosquitto-go-auth \
  -p 1883:1883 \  # MQTT端口
  -v $(pwd)/mosquitto.conf:/etc/mosquitto/mosquitto.conf \
  -v $(pwd)/passwords.txt:/etc/mosquitto/passwords.txt \
  -v $(pwd)/acls.txt:/etc/mosquitto/acls.txt \
  eclipse-mosquitto:2.0  # 假设基础镜像为eclipse-mosquitto:2.0，需预安装插件

Docker Compose（含PostgreSQL后端）

yaml
version: '3'
services:
  mosquitto:
    image: docker.xuanyuan.run/eclipse-mosquitto:2.0
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto.conf:/etc/mosquitto/mosquitto.conf
    depends_on:
      - postgres
    environment:
      - AUTH_PLUGIN_PATH=/etc/mosquitto/go-auth.so

  postgres:
    image: docker.xuanyuan.run/postgres:13
    environment:
      - POSTGRES_USER=dbuser
      - POSTGRES_PASSWORD=dbpass
      - POSTGRES_DB=mqtt_auth
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

注意事项

• 安全警告：debug日志级别会泄露敏感信息（如密码、哈希），生产环境必须使用info及以上级别。
• 缓存策略：启用cache_refresh可能导致权限撤销延迟，建议结合cache_seconds合理设置过期时间。
• 后端优先级：多个后端启用时，按auth_opt_backends配置顺序依次检查，首个通过验证的后端生效。

许可证

插件遵循MIT许可证，Mosquitto遵循EPL/EDL许可证。详细信息参见https://github.com/iegomez/mosquitto-go-auth%E3%80%82