EMQX 文档

简体中文

English

简体中文

English

Appearance

联系我们

命名空间 ​

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

提示

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

什么是命名空间 ​

命名空间是 EMQX 中用于分组 MQTT 客户端并应用隔离策略的逻辑边界。命名空间通过特殊的客户端属性 tns（租户命名空间）来标识，该属性可以从连接的元数据中提取，如用户名或服务器名称指示符（SNI）。

命名空间可以用于控制以下内容：

  • 通过自动主题前缀（挂载点）实现主题隔离
  • 每个命名空间的客户端数量限制和连接跟踪
  • 使用命名空间信息丰富日志元数据
  • 每个命名空间的速率限制

启用命名空间 ​

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

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

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

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

创建命名空间的方式 ​

创建命名空间有两种方式：显式创建和自动创建。

  1. 显式创建命名空间 通过 Dashboard 或 REST API，您可以手动显式创建命名空间。显式创建的命名空间可以被直接管理、编辑和删除。

    使用场景：适用于您希望明确控制哪些命名空间存在，并且需要对命名空间进行精细管理的情况。

  2. 通过 EMQX 提取 client_attrs.tns 自动创建命名空间 当客户端连接时，EMQX 可以根据客户端的 client_attrs.tns 属性自动创建命名空间。这种方式通常用于无需手动创建命名空间的场景，适用于大规模自动化的部署。

    使用场景：这种方法最适用于客户端连接被信任的环境，并且需要自动为每个租户或客户端创建独立命名空间的情况。

    注意

    自动创建的命名空间无法在 Dashboard 中进行编辑操作。它们只能通过配置文件或者从客户端的元数据中自动生成。

    注意

    只有当 multi_tenancy.allow_only_managed_namespaces = false 时，才启用自动命名空间创建。

通过这两种方式，您可以根据不同的需求灵活选择创建命名空间的方式。显式创建适用于需要严格控制的环境，而自动创建则适用于动态环境，减少了手动干预。

快速入门：为命名空间配置速率限制器 ​

您可以为每个命名空间配置速率限制器，以控制特定客户端组的流量和消息流。这些速率限制器与 EMQX 的现有速率限制器（针对区域和监听器）一起工作，具体取决于配置的速率限制器类型。

速率限制器类型 ​

在管理的命名空间中，有两种类型的速率限制器：

租户速率限制器：在命名空间（NS）内的所有客户端之间分配共享的 Token。当配置这种类型的限制器时，它与现有的区域级速率限制器一起工作，这意味着区域和命名空间租户速率限制器将同时应用于客户端。

客户端速率限制器：为每个命名空间内的每个客户端分配独有的 Token。当配置这种类型的限制器时，它会替代任何现有的监听器级速率限制器，即忽略监听器速率限制器，应用命名空间的客户端速率限制器。

两种限制器类型均可定义以下限制：

  • 消息速率限制：客户端或租户在指定时间内可以发布的最大消息数
  • 字节吞吐量限制：在指定时间内允许的最大消息有效 payload 大小

提示

有关详细信息，请参阅速率限制文档。

通过 REST API 配置命名空间示例 ​

本示例使用 REST API 对命名空间进行配置。假设您希望为 ns1 命名空间中的客户端配置一些特定的速率限制。您还希望限制该命名空间允许的最大并发会话数。

创建命名空间 ​

在应用任何配置之前，确保命名空间已显式创建：

bash
# 无需请求体
POST /mt/ns/ns1

重要提示

如果客户端在命名空间显式创建之前连接到该命名空间，它们将无法继承之后应用的配置，如速率限制器。要强制执行新设置，这些客户端必须手动断开并重新连接。

配置速率限制和会话限制 ​

一旦命名空间创建完成，使用以下命令应用配置：

PUT /mt/ns/ns1/config

请求体：

json
{
  "limiter": {
    "client": {
      "bytes": {
        "rate": "10MB/10s",
        "burst": "200MB/1m"
      },
      "messages": {
        "rate": "3000/1s",
        "burst": "40/30s"
      }
    },
    "tenant": {
      "bytes": {
        "rate": "20MB/10s",
        "burst": "300MB/1m"
      },
      "messages": {
        "rate": "5000/1s",
        "burst": "60/30s"
      }
    }
  },
  "session": {
    "max_sessions": 100
  }
}

此配置同时应用客户端特定和共享租户的速率限制，并设置该命名空间的最大会话数为 100。

禁用命名空间速率限制器 ​

如果您希望完全禁用速率限制，可以通过更新配置并将速率限制器类型设置为 "disabled" 来实现：

PUT /mt/ns/ns1/config

请求体：

json
{
  "limiter": {
    "client": "disabled",
    "tenant": "disabled"
  }
}

管理命名空间 ​

您可以通过 Dashboard 和 REST API 配置和管理命名空间的功能。

通过 Dashboard 管理命名空间 ​

在 Dashboard 左侧菜单中点击管理 ->命名空间。在命名空间页面中您可以查看、创建、编辑和删除命名空间，还可以管理连接到命名空间的客户端。

命名空间列表默认仅列出通过显式创建的命名空间。您可以选择关闭页面左上角的开关以列出所有显式创建的命名空间和通过 EMQX 提取 client_attrs.tns 自动创建的命名空间。

TIP

自动创建的命名空间无法在 Dashboard 上进行编辑操作。

创建命名空间 ​

  1. 点击命名空间页面右上角的创建。

  2. 在弹出的创建命名空间对话框中完成以下配置：

    • 命名空间：输入命名空间的名称。

    • 最大会话数：默认情况下，开关为关闭，表示最大会话数为 infinity（无限制）。如果启用开关，可以设置一个具体的数值，限制命名空间允许的最大会话数，防止过多的客户端在一个命名空间内占用过多资源。设置最大会话数时，要根据实际的集群容量来进行合理配置，避免因设置过低导致连接被拒绝。

    • 租户速率限制：该配置用于对整个命名空间内所有客户端进行统一流量控制。例如，多个客户共享同一个基础设施时，租户速率限制可以确保每个租户都能获得公平的带宽。默认情况下，开关为关闭。如启用，您可以设置以下速率限制：

      TIP

      有关该配置项的详细说明，请参阅 Dashboard 中的帮助提示。

      • 数据发布速率：用于限制当前租户每秒可发送给 EMQX 的字节数，可以对数据发布流量进行控制。
      • 数据发布突发速率：允许在突发情况下额外发送的字节数。
      • 消息发布速率：用于限制当前租户每秒可发送给 EMQX 的最大消息数，以避免单个客户端占用过多的计算资源。
      • 消息发布突发速率：允许在突发情况下额外发送给 EMQX 的最大消息数。

    • 客户端速率限制：该配置用于对每个客户端单独进行流量控制。客户端速率限制器的令牌是独占的，因此一个客户端的速率限制不会影响其他客户端的连接。默认情况下，开关为关闭。如启用，您可以设置以下速率限制：

      TIP

      有关该配置项的详细说明，请参阅 Dashboard 中的帮助提示。

      • 数据发布速率：用于限制单个客户端每秒可发送给 EMQX 的字节数，可以对数据发布流量进行控制。
      • 数据发布突发速率：允许在突发情况下额外发送的字节数。
      • 消息发布速率：用于限制单个客户端每秒可发送给 EMQX 的最大消息数，以避免单个客户端占用过多的计算资源。
      • 消息发布突发速率：允许在突发情况下额外发送给 EMQX 的最大消息数。

  3. 完成设置后，点击创建。您将看到新创建的命名空间出现在列表中。

编辑和删除命名空间 ​

如果您想要编辑某个特定命名空间的设置，可以在命名空间列表中，点击该命名空间操作列中的编辑。

如果您想要删除一个命名空间，可以点击操作列中的删除，在进行二次确认后，命名空间将被永久删除。

如果您想要查看连接到某个特定命名空间的客户端，可以点击操作列中的客户端。您还可以选择批量踢除客户端。

通过 REST API 管理命名空间 ​

提示

查看相应的 Swagger API 文档，确保了解最新的请求和响应端点模式。这些文档由 Dashboard 监听器通过 /api-docs 提供。

创建命名空间 ​

在应用命名空间特定配置之前，必须使用 POST /mt/ns/<namespace> API 显式创建命名空间。将 <namespace> 替换为所需的命名空间 ID，无需请求体。

配置命名空间 ​

命名空间创建后，可以使用 PUT /mt/ns/<namespace>/config API 进行配置。

通过该端点，您可以设置速率限制、会话限制和其他命名空间特定的配置。有关示例配置，请参见快速入门部分。

删除命名空间 ​

要删除命名空间及其相关配置，可以使用 DELETE /mt/ns/<namespace> API。

提示

删除命名空间之前，请确保所有与该命名空间关联的活动客户端已正确断开连接。EMQX 提供了一个 API，可以在删除托管命名空间时，自动批量踢出该命名空间下的所有会话。