EMQX 企业版

简体中文

English
日本語

简体中文

English
日本語

Appearance

联系我们

配置与管理命名空间 ​

您可以通过 Dashboard 和 REST API 对命名空间进行配置和管理，包括会话数量限制、速率限制以及客户端管理等操作。

命名空间的速率限制器 ​

命名空间的配置主要包括最大会话数和速率限制器。在开始配置速率限制器之前，建议先了解命名空间中不同类型速率限制器的作用及其生效范围。

有关具体配置项的设置方法，参考[通过 Dashboard 配置和管理命名空间](#通过 Dashboard 配置和管理命名空间)。

命名空间速率限制器可用于控制特定命名空间内客户端的消息流量和带宽使用情况，并可与 EMQX 现有的速率限制机制（如区域级或监听器级速率限制）配合使用，其具体生效方式取决于速率限制器的类型。

速率限制器类型 ​

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

租户速率限制器 ​

租户速率限制器在同一命名空间内的所有客户端之间分配共享的令牌（Token）。

当启用该限制器时：

  • 限制作用于整个命名空间
  • 会与现有的区域级（Zone）速率限制器共同生效
  • 客户端需要同时满足区域级和命名空间级的限制条件

该类型适用于需要限制单个租户整体流量的场景。

客户端速率限制器 ​

客户端速率限制器为命名空间内的每个客户端分配独立的令牌。

当启用该限制器时：

  • 限制作用于单个客户端
  • 会替代监听器级（Listener）速率限制器
  • 监听器级速率限制将被忽略，仅应用命名空间客户端速率限制

该类型适用于需要精细控制单个客户端行为的场景。

支持的限制维度 ​

无论是租户速率限制器还是客户端速率限制器，均支持以下限制维度：

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

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

提示

有关速率限制机制的详细说明，请参阅速率限制。

通过 Dashboard 配置和管理命名空间 ​

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

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

TIP

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

配置命名空间 ​

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

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

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

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

      TIP

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

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

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

      TIP

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

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

  2. 完成设置后，点击更新以应用您的配置。

删除命名空间 ​

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

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

通过 REST API 配置和管理命名空间 ​

提示

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

配置命名空间 ​

命名空间创建后，可以使用 PUT /mt/ns/<namespace>/config 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"
  }
}

删除命名空间 ​

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

提示

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