Skip to content

命名空间

从 EMQX 5.9.0 开始,命名空间功能允许用户在单个 EMQX 集群中逻辑地分组 MQTT 客户端,并对其应用流量限制。该功能使得多个客户端组(如业务单元、应用程序或客户)能够共享相同的基础设施,同时保持逻辑上的隔离,从而支持可扩展的部署。

提示

尽管该功能遵循多租户设计原则,但在 EMQX 5.9 中,该功能被称为命名空间

什么是命名空间

命名空间是 EMQX 企业版中用于对 MQTT 客户端进行逻辑隔离和资源管理的一种机制。它允许用户在共享一个 EMQX 集群的前提下,将不同业务或租户的客户端划分到不同的命名空间中,实现连接、消息、配额等方面的隔离控制。

命名空间通过特殊的客户端属性 tns(租户命名空间)来标识,该属性可以从客户端连接的元数据中提取,例如用户名或服务器名称指示符(SNI)。

典型应用场景包括:企业内部多个业务共用集群、租户级资源隔离管理、集中化接入控制等。

命名空间可以用于实现以下目标:

  • 客户端与消息的逻辑隔离

    命名空间可作为区分不同租户的依据,用于实现客户端 ID 和消息主题的命名隔离。但请注意,启用命名空间后不会自动获得客户端 ID 覆盖、主题前缀等隔离效果,用户需根据实际需要手动配置,详见隔离机制

  • 租户级配额与连接控制

    可以限制每个命名空间下的客户端连接数和消息发布速率,防止单一租户过度占用资源。

  • 日志增强与运维追踪

    日志中将自动添加命名空间标识字段,便于识别和定位某个租户下的客户端行为。

  • 按命名空间进行资源使用监控

    支持基于命名空间统计连接数量、发布速率等指标,为运维和容量规划提供支持。

隔离机制

EMQX 拥有极高的灵活性,在命名空间功能实现之前,就已支持多种隔离方式,命名空间功能提供了统一的租户标识字段(client_attrs.tns),使客户端 ID、主题挂载点等配置能够围绕统一的租户信息组织和管理。

但需要注意,隔离策略仍需用户根据业务需求手动配置生效,系统不会自动启用客户端 ID 或主题的隔离功能。

  • 客户端 ID 覆盖 若希望不同命名空间中的客户端使用相同的客户端 ID 连接 EMQX,可设置客户端 ID 覆盖规则。例如: mqtt.clientid_override="concat([client_attrs.tns, '-', clientid])",此规则会将命名空间作为前缀添加到客户端 ID 中,避免冲突。

  • 使用挂载点进行主题隔离

    若不同命名空间的客户端需要发布或订阅相同的主题名称,而又不希望互相影响,可使用挂载点自动添加命名空间前缀:

    listener.{TYPE}.{NAME}.mountpoint="${client_attrs.tns}/",该设置会为主题名称添加命名空间前缀。

截至 5.9 版本,命名空间仅适用于 MQTT 客户端,Dashboard 和 REST API 尚未基于命名空间进行隔离。EMQX 计划在未来版本中实现统一的管理命名空间与 MQTT 命名空间,详情请参见多租户功能路线图

启用命名空间

要启用命名空间功能,首先需要告知 EMQX 如何确定客户端属于哪个命名空间。这是通过设置特殊的 tns(租户命名空间)客户端属性来完成的。

通过配置文件启用命名空间

您可以从连接的元数据中提取 tns 属性,例如客户端的用户名、SNI 或其他字段。

例如,使用客户端的用户名作为命名空间标识符,您可以使用以下配置:

hcl
mqtt.client_attrs_init = [{expression = username, set_as_attr = tns}]

通过 Dashboard 启用命名空间

您也可以通过 Dashboard 启用命名空间。

  1. 管理 -> MQTT 配置 -> 通用标签页,找到客户端属性
  2. 点击添加,并填写以下信息:
    • 属性tns
    • 属性表达式:如使用客户端的用户名作为命名空间标识符,可以填写 username,也可以使用其他变量。更多关于属性表达式的使用方法,参考设置客户端属性
  3. 点击保存修改

多租户功能路线图

  • 将管理命名空间与 MQTT 命名空间统一。
  • 实现规则、动作/数据源和连接器的隔离。
  • 实现内置数据库身份认证的隔离。
  • 实现内置数据库权限认证的隔离。
  • 实现保留消息配额的隔离。
  • 实现 Prometheus 指标的隔离。

下一步

现在您已了解命名空间的基本概念及其功能,可以继续以下几个步骤,开始在 EMQX 中使用命名空间功能:

  • 创建命名空间 了解如何通过 Dashboard 或 REST API 显式创建命名空间,或基于客户端元数据自动创建命名空间。
  • 配置与管理命名空间 学习如何通过 Dashboard 或 REST API 设置速率限制、会话配额等命名空间相关配置。
  • 快速体验命名空间功能 通过 MQTTX 实践操作,快速体验命名空间在客户端隔离、主题隔离等场景中的应用效果。