命名空间

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

提示

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

从 EMQX 6.1 起，命名空间相关能力在保持原有语义不变的基础上进行了增强，进一步简化了多租户隔离配置，并统一了主题隔离相关的行为。

什么是命名空间

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

命名空间通过特殊的客户端属性 tns（租户命名空间）来标识。该属性并非自动存在，而是需要通过配置从客户端连接的元数据中提取，例如用户名或服务器名称指示符（SNI）。

命名空间在被创建后即开始生效，无论该命名空间是通过 Dashboard 或 REST API 显式创建，还是基于命名空间来源在客户端连接时自动创建。

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

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

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

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

• 租户级配额与连接控制

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

• 日志增强与运维追踪

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

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

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

• 管理员用户隔离

  从 EMQX 6.0 起，命名空间机制也扩展到了 Dashboard、CLI 与 API 层面的用户管理，通过命名空间角色实现租户级权限控制：

  • 管理员用户可被指定为仅限访问特定命名空间的角色，例如：ns:team_a::administrator。
  • 命名空间用户仅能查看与操作其所属命名空间内的资源。
  • 尚未支持命名空间隔离的集群级配置项对命名空间用户为只读，仅全局管理员具备修改权限。
  • 这一机制在实现数据隔离的同时，也确保了管理权限的安全分离。

• 多租户统一管理

  系统管理员可以在同一个集群中统一管理多个命名空间，而每个租户在其独立的环境中进行操作，资源与权限完全隔离，互不影响。

隔离机制

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

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

• 客户端 ID 覆盖

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

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

  若不同命名空间的客户端需要发布或订阅相同的主题名称，而又不希望互相影响，可使用挂载点自动添加命名空间前缀。在 EMQX 6.0 及之前版本中，通常需要在监听器（Listener）级别配置挂载点，例如：listener.{TYPE}.{NAME}.mountpoint = "${client_attrs.tns}/" 在存在多个监听器的场景下，该方式需要在多个位置重复配置。

  从 EMQX 6.1 开始，支持将命名空间作为统一的主题挂载点。在成功识别命名空间后，EMQX 会在内部使用 {namespace}/ 作为主题前缀，实现与监听器挂载点等价的主题隔离效果，而无需在每个监听器上单独配置。

  为保持向后兼容性，默认情况下授权（ACL）检查不会包含挂载点前缀。从 EMQX 6.1 开始，你可以通过设置 authorization.include_mountpoint=true，让授权后端能够接收到带有挂载点前缀的主题。

多租户能力支持情况

命名空间是 EMQX 多租户能力的核心组成部分，自 5.9 引入，并在 6.1 中进一步增强。基于命名空间，EMQX 已逐步在多个子系统中实现多租户隔离能力，当前版本支持情况如下：

• 管理命名空间与 MQTT 命名空间统一（6.0）

  管理平面（Dashboard、CLI、API）与 MQTT 数据平面共享同一命名空间模型。

• 内置数据库身份认证的隔离（6.1）

  支持基于命名空间对内置数据库中的认证数据进行隔离。

• 内置数据库权限认证的隔离（6.1）

  授权规则可限定在指定命名空间范围内生效。

• Prometheus 指标隔离（6.1）

  支持按命名空间维度暴露和统计监控指标，便于多租户场景下的监控与运维。

• 保留消息配额隔离

  支持基于命名空间限制保留消息相关资源的使用。

此外，从 EMQX 6.0 起，规则、动作、Source 和连接器的命名空间隔离已全部实现，不再属于后续开发计划。

下一步

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

• 创建命名空间: 了解如何通过 Dashboard 或 REST API 显式创建命名空间，或基于客户端元数据自动创建命名空间。
• 配置与管理命名空间: 了解如何通过 Dashboard 或 REST API 设置速率限制、会话配额等命名空间相关配置。
• 命名空间全局设置：配置集群级别的命名空间行为，包括命名空间的解析方式、隔离机制、主题挂载点以及授权处理方式。
• 快速体验命名空间功能：通过 MQTTX 实践操作，快速体验命名空间在客户端隔离、主题隔离等场景中的应用效果。