# 配置与管理命名空间 您可以通过 Dashboard 和 REST API 配置和管理命名空间，包括设置会话数量限制和速率限制，以及管理客户端。 ## 命名空间的速率限制器 命名空间的配置主要包括最大会话数和速率限制器。在开始配置速率限制器之前，建议先了解命名空间中不同类型速率限制器的作用及其生效范围。 有关具体配置项的设置方法，参考[通过 Dashboard 配置和管理命名空间](#通过 Dashboard 配置和管理命名空间)。 命名空间速率限制器可用于控制特定命名空间内客户端的消息流量和带宽使用情况，并可与 EMQX 现有的速率限制机制（如区域级或监听器级速率限制）配合使用，其具体生效方式取决于速率限制器的类型。 ### 速率限制器类型 在管理的命名空间中，有两种类型的速率限制器： #### 租户速率限制器 租户速率限制器在同一命名空间内的所有客户端之间分配**共享的令牌（Token）**。 当启用该限制器时： - 限制作用于整个命名空间 - 会与现有的区域级（Zone）速率限制器共同生效 - 客户端需要同时满足区域级和命名空间级的限制条件 该类型适用于需要限制单个租户整体流量的场景。 #### 客户端速率限制器 客户端速率限制器为命名空间内的每个客户端分配独立的令牌。 当启用该限制器时： - 限制作用于单个客户端 - 会替代监听器级（Listener）速率限制器 - 监听器级速率限制将被忽略，仅应用命名空间客户端速率限制 该类型适用于需要精细控制单个客户端行为的场景。 ### 支持的限制维度 两种限制器类型均可定义以下限制： - **消息速率限制**：客户端或租户在指定时间内可以发布的最大消息数 - **字节吞吐量限制**：在指定时间内允许的最大消息有效 payload 大小 客户端速率限制器还支持**订阅报文速率限制**，用于限制单个客户端在指定时间内可发送的 `SUBSCRIBE` 报文数量。共享的租户速率限制器不支持此限制维度。 ::: tip 提示 有关速率限制机制的详细说明，请参阅[速率限制](../rate-limit.md)。 ::: ## 通过 Dashboard 配置和管理命名空间 在 Dashboard 左侧菜单中点击**管理** ->**命名空间**。在**命名空间**页面中，您可以管理命名空间以及连接到各命名空间的客户端。 命名空间列表默认仅列出通过显式创建的命名空间。您可以选择关闭页面左上角的开关以列出所有显式创建的命名空间和通过 EMQX 提取 `client_attrs.tns` 自动创建的命名空间。 ::: tip 自动创建的命名空间无法在 Dashboard 上进行编辑操作。 ::: ### 配置命名空间 您可以在创建命名空间时配置命名空间。如果您想要编辑某个特定已创建命名空间的设置，可以在命名空间列表中，点击该命名空间**操作**列中的**编辑**。 1. 在弹出的**创建命名空间**对话框中完成以下配置： - **最大会话数**：默认情况下，开关为关闭，表示最大会话数为 `infinity`（无限制）。如果启用开关，可以设置一个具体的数值，限制命名空间允许的最大会话数，防止过多的客户端在一个命名空间内占用过多资源。设置最大会话数时，要根据实际的集群容量来进行合理配置，避免因设置过低导致连接被拒绝。 - **租户速率限制**：该配置用于对整个命名空间内所有客户端进行统一流量控制。例如，多个客户共享同一个基础设施时，租户速率限制可以确保每个租户都能获得公平的带宽。默认情况下，开关为关闭。如启用，您可以设置以下速率限制： ::: tip 有关该配置项的详细说明，请参阅 Dashboard 中的帮助提示。 ::: - **报文发布速率**：用于限制当前租户每秒可发送给 EMQX 的字节数，可以对数据发布流量进行控制。 - **报文发布突发速率**：允许在突发情况下额外发送的字节数。 - **消息发布速率**：用于限制当前租户每秒可发送给 EMQX 的最大消息数，以避免单个客户端占用过多的计算资源。 - **消息发布突发速率**：允许在突发情况下额外发送给 EMQX 的最大消息数。 - **客户端速率限制**：该配置用于对每个客户端单独进行流量控制。客户端速率限制器的令牌是独占的，因此一个客户端的速率限制不会影响其他客户端的连接。默认情况下，开关为关闭。如启用，您可以设置以下速率限制： ::: tip 有关该配置项的详细说明，请参阅 Dashboard 中的帮助提示。 ::: - **报文发布速率**：用于限制单个客户端每秒可发送给 EMQX 的字节数，可以对数据发布流量进行控制。 - **报文发布突发速率**：允许在突发情况下额外发送的字节数。 - **消息发布速率**：用于限制单个客户端每秒可发送给 EMQX 的最大消息数，以避免单个客户端占用过多的计算资源。 - **消息发布突发速率**：允许在突发情况下额外发送给 EMQX 的最大消息数。 - **订阅速率**：用于限制单个客户端在指定时间内可发送的 `SUBSCRIBE` 报文数量。 - **订阅突发速率**：允许客户端在突发情况下额外发送 `SUBSCRIBE` 报文。 2. 完成设置后，点击**更新**以应用您的配置。 ### 管理命名空间客户端 如果您想要查看连接到某个特定命名空间的客户端，可以点击**操作**列中的**客户端**。您还可以选择批量踢除客户端。 ## 通过 REST API 配置和管理命名空间 ::: tip 提示 要查看与当前 EMQX 实例版本一致的请求和响应 Schema，请访问 Dashboard 监听地址下的 `/api-spec.html`，例如 `http://localhost:18083/api-spec.html`。 ::: ### 查询命名空间列表 EMQX 提供两个带详情的命名空间列表端点，可根据实际需求选择： | 端点 | 范围 | 是否包含配置 | | ---- | ---- | ------------ | | `GET /mt/ns_list_details` | 所有命名空间（自动创建和显式创建） | 否 | | `GET /mt/managed_ns_list_details` | 仅显式创建（托管）的命名空间 | 是 | 两个端点支持相同的查询参数： | 参数 | 类型 | 默认值 | 说明 | | ---- | ---- | ------ | ---- | | `last_ns` | 字符串 | `""` | 分页游标。传入上一页最后一条记录的 `name`，可获取下一页数据。 | | `limit` | 整数 | `100` | 每次请求返回的最大命名空间数量。 | #### 查询所有命名空间 `GET /mt/ns_list_details` 返回所有命名空间，包括从客户端连接元数据自动创建的命名空间。每条记录仅包含 `name` 和 `created_at`，不含配置字段。 **响应示例** ```json [ { "name": "ns1", "created_at": 1747917753 }, { "name": "ns2", "created_at": 1747917754 } ] ``` #### 查询托管命名空间及其配置 `GET /mt/managed_ns_list_details` 仅返回显式创建的命名空间，并在响应中内联每个命名空间的当前配置。管理界面可通过该端点一次请求完成带配置数据的完整列表渲染。 **响应示例** ```json [ { "name": "ns1", "created_at": 1747917753, "config": { "session": { "max_sessions": 100 }, "limiter": { "tenant": { "bytes": { "rate": "20MB/10s", "burst": "300MB/1m" }, "messages": { "rate": "5000/1s", "burst": "60/1m" } }, "client": { "bytes": { "rate": "10MB/10s", "burst": "200MB/1m" }, "messages": { "rate": "3000/1s", "burst": "40/1m" } } } } }, { "name": "ns2", "created_at": 1747917754, "config": {} } ] ``` 响应数组中每条记录包含以下字段： - `name`：命名空间标识符 - `created_at`：命名空间创建时间的 Unix 时间戳（秒） - `config`：命名空间配置。空对象（`{}`）表示尚未应用任何配置。关于各配置字段的详细说明，请参见[配置命名空间](#配置命名空间)。 如需获取某个命名空间的完整配置详情，可使用 `GET /mt/ns//config` 端点。 ### 配置命名空间 命名空间创建后，可以使用 `PUT /mt/ns//config` API 进行配置。 通过该端点，您可以设置速率限制、会话限制和其他命名空间特定的配置。 #### 配置示例 本示例使用 REST API 对命名空间进行配置。假设您希望为 `ns1` 命名空间中的客户端配置一些特定的速率限制。您还希望限制该命名空间允许的最大并发会话数。 ##### 创建命名空间 在应用任何配置之前，确保命名空间已显式创建： ```bash # 无需请求体 POST /mt/ns/ns1 ``` ::: tip 重要提示 如果客户端在命名空间显式创建之前连接到该命名空间，它们将无法继承之后应用的配置，如速率限制器。要强制执行新设置，这些客户端必须手动断开并重新连接。 ::: ##### 配置速率限制和会话限制 一旦命名空间创建完成，使用以下命令应用配置： ``` PUT /mt/ns/ns1/config ``` **请求体：** ```json { "limiter": { "client": { "bytes": { "rate": "10MB/10s", "burst": "200MB/1m" }, "messages": { "rate": "3000/1s", "burst": "40/30s" }, "subscribes": { "rate": "120/1m", "burst": "10/10s" } }, "tenant": { "bytes": { "rate": "20MB/10s", "burst": "300MB/1m" }, "messages": { "rate": "5000/1s", "burst": "60/30s" } } }, "session": { "max_sessions": 100 } } ``` 此配置同时应用客户端特定和共享租户的速率限制，并设置该命名空间的最大会话数为 100。`subscribes` 配置将单个客户端的订阅速率限制为每分钟 120 个 `SUBSCRIBE` 报文，并允许每 10 秒突发发送最多 10 个额外报文。命名空间级 `subscribes` 配置会覆盖该命名空间内客户端所使用的监听器级订阅报文速率限制。 ##### 禁用命名空间速率限制器 如果您希望完全禁用速率限制，可以通过更新配置并将速率限制器类型设置为 `"disabled"` 来实现： ``` PUT /mt/ns/ns1/config ``` **请求体：** ```json { "limiter": { "client": "disabled", "tenant": "disabled" } } ``` ## 删除和清理命名空间 删除托管命名空间会永久删除该命名空间及其相关配置。从 EMQX 6.1.4 开始，EMQX 还会异步删除内置数据库中属于该命名空间的数据，包括密码认证用户、SCRAM 用户和授权规则。EMQX 会清理已删除命名空间所有用户组中的认证用户，不影响全局命名空间或其他命名空间。清理完成后，重新创建同名命名空间不会恢复已删除的用户或授权规则。 ::: tip 提示 删除托管命名空间时，EMQX 会自动开始断开当前通过该命名空间连接的所有客户端。为避免客户端连接意外中断，请在删除命名空间之前主动断开活动客户端。 ::: ### 通过 Dashboard 删除 如果您想要删除一个命名空间，可以点击**操作**列中的**删除**，在进行二次确认后，命名空间将被永久删除。 ### 通过 REST API 删除 要删除命名空间及其相关配置，使用 `DELETE /mt/ns/` API。 ### 从中断的删除操作中恢复 从 EMQX 6.1.4 开始，如果上一次命名空间删除操作中断并遗留数据，可以将 `emqx ctl mt purge_ns ` 命令作为最后的补救措施。即使命名空间已不存在，该命令仍会尝试清理其数据。如果命名空间仍然存在，该命令也会将其删除。 ::: warning 重要提示 对现有命名空间运行此命令会永久删除该命名空间及其数据。常规命名空间删除应使用 Dashboard 或 REST API。仅在删除操作未完成时，使用 `purge_ns` 命令进行恢复；重新创建同名命名空间后，不要再次运行该命令。 ::: 有关命令语法、输出和错误处理的信息，参见 [`mt purge_ns`](../cli.md#mt)。