# 命名空间 从 EMQX 5.9.0 开始，命名空间功能允许用户在单个 EMQX 集群中逻辑地分组 MQTT 客户端，并对其应用流量限制。该功能使得多个客户端组（如业务单元、应用程序或客户）能够共享相同的基础设施，同时保持逻辑上的隔离，从而支持可扩展的部署。 ::: tip 提示 尽管该功能遵循多租户设计原则，但在 EMQX 5.9 中，该功能被称为**命名空间**。 ::: 从 EMQX 6.1 起，命名空间相关能力在保持原有语义不变的基础上进行了增强，进一步简化了多租户隔离配置，并统一了主题隔离相关的行为。 ## 什么是命名空间 命名空间是 EMQX 企业版中用于对 MQTT 客户端进行逻辑隔离和资源管理的一种机制。它允许用户在共享一个 EMQX 集群的前提下，将不同业务或租户的客户端划分到不同的命名空间中，实现连接、消息、配额等方面的隔离控制。 命名空间通过特殊的客户端属性 `tns`（租户命名空间）来标识。该属性并非自动存在，而是需要通过配置从客户端连接的元数据中提取，例如用户名或服务器名称指示符（SNI）。 命名空间在被创建后即开始生效，无论该命名空间是通过 Dashboard 或 REST API 显式创建，还是基于命名空间来源在客户端连接时自动创建。 > **典型应用场景包括**：企业内部多个业务共用集群、租户级资源隔离管理、集中化接入控制等。 ### 命名空间可以用于实现以下目标： - **客户端与消息的逻辑隔离** 命名空间可作为区分不同租户的依据，用于实现客户端 ID 和消息主题的命名隔离。但请注意，启用命名空间后**不会自动**获得客户端 ID 覆盖、主题前缀等隔离效果，用户需根据实际需要手动配置，详见[隔离机制](#隔离机制)。 - **租户级配额与连接控制** 可以限制每个命名空间下的客户端连接数和消息发布速率，防止单一租户过度占用资源。 - **日志增强与运维追踪** 日志中将自动添加命名空间标识字段，便于识别和定位某个租户下的客户端行为。 - **按命名空间进行资源使用监控** 支持基于命名空间统计连接数量、发布速率等指标，为运维和容量规划提供支持。 - **管理员用户隔离** 从 EMQX 6.0 起，命名空间机制也扩展到了 Dashboard、CLI 与 API 层面的用户管理，通过[命名空间角色](../dashboard/system.md/#命名空间角色)实现租户级权限控制： ::: warning 仅适用于受信任部署 管理员命名空间仅适用于受信任的内部部署场景，例如在同一组织内隔离不同团队或业务单元，以降低误修改其他配置的风险。命名空间功能不提供强隔离保障，不适合作为面向公共环境或非受信任用户的多租户安全边界。 如果允许委派管理员配置命名空间范围内的资源，建议在可用版本中优先启用 `rule_engine.ssrf` 来校验规则引擎管理的出站目标。如果还需要运行时网络边界，再通过 `iptables` 或 `nftables` 等主机级防火墙规则限制出站访问。参见[结合规则引擎策略与防火墙规则防御 SSRF](../deploy/cluster/security.md)。 ::: - 管理员用户可被指定为仅限访问特定命名空间的角色，例如：`ns:team_a::administrator`。 - 命名空间用户仅能查看与操作其所属命名空间内的资源。 - 尚未支持命名空间隔离的集群级配置项对命名空间用户为只读，仅全局管理员具备修改权限。 - 这一机制在实现数据隔离的同时，也确保了管理权限的安全分离。 - **多租户统一管理** 系统管理员可以在同一个集群中统一管理多个命名空间，而每个租户在其独立的环境中进行操作，资源与权限完全隔离，互不影响。 ## 管理员命名空间的运维安全 委派的命名空间管理员可以配置连接器、数据桥接和动作等出站目标。如果缺乏访问控制，可能导致 EMQX 向内部或敏感网络发起非预期请求。 在可用版本中启用 `rule_engine.ssrf` 来校验规则引擎管理的出站目标。如果部署还需要运行时网络边界，在 EMQX 所在主机上增加出站访问控制： - 仅允许访问已批准的目标地址，例如身份提供商（IdP）、Webhook 接收端或连接器后端。 - 默认拒绝访问实例元数据服务、回环地址、链路本地地址以及内部管理网络，除非明确需要。典型需要显式阻止的元数据端点包括 `100.100.100.200`、`169.254.169.253`、`169.254.169.254` 和 `fd00:ec2::254`。 - 每次新增会发起出站 HTTP 或 TCP 连接的集成功能或管理能力时，都同步审查防火墙规则。 详情参见[结合规则引擎策略与防火墙规则防御 SSRF](../deploy/cluster/security.md)。 ## 隔离机制 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 中使用命名空间功能： - **[创建命名空间](./create-namespace.md)**: 了解如何通过 Dashboard 或 REST API 显式创建命名空间，或基于客户端元数据自动创建命名空间。 - **[配置与管理命名空间](./configure-manage-namespace.md)**: 了解如何通过 Dashboard 或 REST API 设置速率限制、会话配额等命名空间相关配置。 - **[命名空间全局设置](./namespace-global-settings.md)**：配置集群级别的命名空间行为，包括命名空间的解析方式、隔离机制、主题挂载点以及授权处理方式。 - **[快速体验命名空间功能](./namespace-quick-start.md)**：通过 MQTTX 实践操作，快速体验命名空间在客户端隔离、主题隔离等场景中的应用效果。