# 系统设置

EMQX Dashboard 中的**系统设置**菜单提供一系列管理功能入口，包括用户与角色管理、审计日志、API 密钥、许可证、单点登录（SSO）、数据备份与恢复以及通用设置。

## 用户

**用户**页面提供了所有活跃的 Dashboard 用户的概览，包括通过[命令行](../cli.md)生成的用户。

要添加新用户，只需点击页面右上角的**创建**按钮。一个弹出的对话框将提示您输入必要的用户详细信息。输入完毕后，点击**创建**按钮即可生成用户帐户。对于进一步的用户管理，如编辑用户信息、更新密码或删除用户，您可以通过**操作**列轻松访问这些选项。

> EMQX 开源版本不提供基于角色的权限管理能力，所有的用户都有管理员权限可删除其他用户，但无法在 Dashboard 上删除当前登录用户。
> 从 EMQX 5.0.0 开始，Dashboard 用户名和密码不能直接作为 REST API 请求的 Basic 认证凭据。如需以 Dashboard 用户身份访问 REST API，请通过 [Dashboard 登录流程](../api.md#使用-bearer-token-认证)获取 Bearer Token。

<img src="./assets/ee-users.png" alt="image" style="zoom:67%;" />

### 基于角色的访问控制

从 EMQX 5.3 开始，Dashboard 用户引入了 基于角色的访问控制 （RBAC）功能。RBAC 允许根据用户在组织中的角色为其分配权限。此功能简化了授权管理，通过限制访问权限提高安全性，并改善组织合规性，因此是 Dashboard 必不可少的访问控制机制。

目前，可以为用户设置以下两种预定义角色之一。您可以在创建用户时从**角色**下拉菜单中选择角色。
+ **管理员**

    管理员拥有对 EMQX 所有功能和资源的完全管理访问权限，包括客户端管理、系统配置、API 密钥以及用户管理。

+ **查看者**

    查看者可以访问 EMQX 的所有数据和配置信息，对应 REST API 中的所有 `GET` 请求，但无权进行创建、修改和删除操作。

### 登录用户权限范围

您可以为 Dashboard 登录用户分配权限范围（Scope），在角色基础上进一步限制用户可访问的 API 区域。Dashboard 中显示为**权限范围**，对应 REST API 的 `scopes` 字段。除 [10 个 API 密钥权限范围](../api.md#内置-api-密钥权限范围) 外，Dashboard 用户还拥有 4 个仅适用于浏览器会话的专属权限范围：

| 权限范围 | 所需角色 | 用途 |
| --- | --- | --- |
| `user_management` | 管理员 | 管理 Dashboard 用户（创建 / 修改 / 删除）。 |
| `sso_management` | 管理员 | 管理 SSO 后端与 SSO 用户记录。 |
| `api_key_management` | 管理员 | 管理 API 密钥。 |
| `mfa_management` | 任意 | 管理自己的 MFA；管理员可管理其他用户的 MFA。 |

其中 `user_management`、`sso_management` 和 `api_key_management` 需要管理员角色，不能分配给查看者。`mfa_management` 是例外：可以授予查看者，但仅允许其管理自己账号的 MFA，不授予对其他用户 MFA 设置的访问权限。当您希望查看者账号能够自助重新绑定或恢复认证设备而不获得其他额外权限时，此权限范围非常有用。

在 Dashboard 中创建全局用户时，**命名空间**选项默认关闭，**权限模式**默认选择**角色默认权限**。可选择以下模式：

- **角色默认权限**：使用所选角色的默认权限。角色默认权限发生变化时，新权限会自动生效。
- **管理权限范围**：从 `system`、`user_management`、`api_key_management` 和 `sso_management` 中选择。这些权限范围可提供等同管理员的能力。
- **自定义受限权限**：从角色可用且不属于等同管理员权限组的权限范围中选择，例如 `connections`、`publish`、`data_integration`、`monitoring` 和 `mfa_management`。如果将权限范围列表留空，用户不能访问受权限范围保护的 API。

<img src="./assets/user_scopes.png" alt="创建全局 Dashboard 用户并选择权限模式" style="zoom:67%;" />

命名空间用户使用单独的权限范围配置方式，可选权限仍受角色和命名空间限制。具体配置步骤参见[创建具有命名空间角色的用户](#创建具有命名空间角色的用户)。

| 用户类型 | 默认权限 |
| --- | --- |
| 全局管理员 | 全部 14 个权限范围，包括 10 个 API 密钥权限范围和 4 个登录专属权限范围。 |
| 全局查看者 | 10 个 API 密钥权限范围。`mfa_management` 仅在显式分配时授予。 |
| 命名空间管理员 | 连接、监控、数据集成、访问控制、系统设置、集群管理、License、用户管理和 API 密钥管理。 |
| 命名空间查看者 | 与全局查看者相同的 10 个 API 密钥权限范围。`mfa_management` 仅在显式分配时授予。 |

::: warning 等同管理员权限的范围必须单独使用

以下权限范围等同管理员权限，在 Dashboard 中归入**管理权限范围**（**Privilege Scopes**），校验错误消息中称为 `privilege scopes`：

- `system` 覆盖配置管理（`/configs*`、`/data/*` 等）。持有 `system` 的用户可以更新任意配置子树，或恢复包含已存储用户和 API 密钥记录的备份文件。
- `user_management` 允许持有者创建或修改其他 Dashboard 用户，包括具有任意权限范围组合的用户。
- `api_key_management` 允许持有者创建或修改 API 密钥，包括具有任意权限范围组合的密钥。
- `sso_management` 允许持有者轮换或重新配置 SSO 后端，从而改变管理员的身份认证方式。

上述每个范围都会授予等同管理员的权限。将其中任一范围与该组之外的权限范围组合，并不能缩小用户的实际权限。

从 EMQX 6.0.4 开始，全局 Dashboard 用户的显式权限范围列表不能将上述任何等同管理员权限的范围与该组之外的权限范围组合。创建或更新请求将返回 HTTP 400，且不会应用任何权限范围变更。需要等同管理员权限时，仅使用上述权限范围；需要受限访问时，仅使用该组之外的权限范围。`mfa_management` 不属于等同管理员权限的范围组。

在 EMQX 6.0.4 之前创建且使用混合权限范围列表的用户可以继续工作，其中等同管理员权限的范围仍然有效。在 Dashboard 中编辑此类全局用户时，表单会显示兼容性警告，并要求在保存前选择**管理权限范围**、**自定义受限权限**或**角色默认权限**。显式权限范围列表必须仅包含等同管理员权限的范围，或仅包含该组之外的权限范围。使用角色默认权限或不授予任何权限范围时，不受此限制。

此互斥规则不适用于命名空间 Dashboard 管理员。命名空间管理员可以使用允许的权限范围组合，但仍只能访问所属命名空间内允许的操作和资源。

:::

#### 角色变更与权限范围兼容性

在 Dashboard 中配置用户并变更所选角色或命名空间时，表单会移除该角色或命名空间不支持的权限范围，并显示警告。通过 REST API 变更用户角色时，EMQX 会检查用户的权限范围是否与新角色兼容。不兼容的请求返回 HTTP 400。要解决此问题，请在同一请求中提供一个对新角色有效的 `scopes` 列表。

例如，如果您将一个管理员降级为查看者，而该用户持有 `user_management`、`sso_management` 或 `api_key_management`，请求将被拒绝，因为这三个权限范围需要管理员角色。请在同一请求中提供一个仅包含与查看者兼容的权限范围列表以完成变更。（`mfa_management` 不仅限于管理员，不会导致此拒绝。）

### 默认管理员保护

`dashboard.default_username` 账号（其密码由 `dashboard.default_password` 配置）是一个应急（break-glass）账号。为了保证在其他管理员配置错误或失联时系统仍可恢复，默认用户受到下列保护，以防止误操作导致整个系统失去管理入口：

- **不能被删除**：无论是从 Dashboard 还是 REST API，**删除**按钮始终不可用。
- 角色**不能被更改**，始终保持 `administrator`。
- 权限范围**不能被自定义**，始终拥有完整的管理员权限。
- 描述和密码**可以**正常修改。

其他管理员不受此限制，只要系统中至少还存在一个管理员，就可以被删除。

### 自助操作边界

每个 Dashboard 用户无论持有哪些权限范围，都可以执行以下两类自助操作：

- 修改自己的密码。
- 绑定或重新绑定自己的 TOTP / MFA。禁用 MFA 同样允许，但若管理员已为该用户账号显式要求启用 MFA，则需持有 `mfa_management` 权限范围方可禁用。

其他个人信息变更（描述、角色、由管理员授予的权限范围）都需要操作者持有对应权限范围，即使目标用户就是操作者自己也不能绕过此检查。

### 命名空间角色

从 EMQX 6.0 开始，Dashboard 支持命名空间角色功能。该特性扩展了基于角色的访问控制（RBAC），以支持多租户场景：每个用户仅被授权访问特定的命名空间，实现资源隔离与权限精细化管理。

::: warning 仅适用于受信任部署

命名空间管理员访问仅适用于受信任的内部部署场景，例如在同一组织内隔离不同团队或业务单元，以降低误修改其他配置的风险。命名空间功能不提供强隔离保障，不适合作为面向公共环境或非受信任用户的多租户安全边界。

如果允许委派管理员管理命名空间范围内的资源，建议在**管理** -> **集群配置** -> **[规则引擎安全](./cluster_settings.md#规则引擎安全)**中启用 SSRF 防护。从 EMQX 6.0.4 开始，该策略仅在测试、创建或更新 HTTP、MQTT 连接器配置时校验目标地址，不覆盖其他连接器类型或运行时连接。请增加 `iptables`、`nftables` 等主机级出站访问控制，以建立完整的出站网络边界。参见[结合规则引擎策略与防火墙规则防御 SSRF](../cluster/security.md#结合规则引擎策略与防火墙规则防御-ssrf)。

:::

::: tip

如需了解命名空间功能的详细信息，请参阅：[命名空间](../multi-tenancy/namespace-overview.md)。

:::

#### 创建具有命名空间角色的用户

在 Dashboard 中创建新用户时，**命名空间**选项默认关闭。打开该选项并选择一个命名空间，可创建具有命名空间角色的用户。

::: tip 前提条件

1. 在 Dashboard 中预先创建一个托管命名空间（如：`namespace_01`）。参考：[创建命名空间](../multi-tenancy/create-namespace.md)。
2. 确保当前使用的 EMQX License 版本为 6.0 或更高版本，并已正确部署集群。

:::

创建步骤如下：

1. 进入**系统设置 > 用户**页面，点击 **+ 创建**。
2. 配置用户：
   - **用户名**：用户的唯一标识。
   - **备注**：可选说明信息。
   - **密码**：用户登录密码。
   - **角色**：选择**管理员**或**查看者**。
   - **命名空间**：默认关闭。打开后选择一个已存在的命名空间（例如 `namespace_01`）。
   - **使用角色默认权限**：打开**命名空间**后，该字段将替代三选一的**权限模式**字段，并默认开启。保持开启将使用所选命名空间角色的默认权限；关闭后可显式分配权限范围。
   - **权限范围**：关闭**使用角色默认权限**后显示。可从所选角色在命名空间中允许持有的权限范围中选择；未选择时，不授予任何权限范围。

   <img src="./assets/create-namespaced-user.png" alt="创建命名空间用户并显式分配权限范围" style="zoom:67%;" />

3. 点击**创建**完成用户配置。

若通过 CLI 或 API 创建用户，需显式指定角色格式为：

```
ns:<NAMESPACE>::<ROLE>
```

例如：

- `ns:namespace_01::administrator`
- `ns:namespace_01::viewer`

从 EMQX 6.3.0 开始，命名空间角色中的命名空间名称不能在 `multi_tenancy.deny_namespaces` 列表中。EMQX 会拒绝使用禁止名称的角色。配置方法请参见[禁止使用的命名空间名称](../multi-tenancy/namespace-global-settings.md#禁止使用的命名空间名称)。

#### 命名空间用户的行为说明

- **资源作用域限制**：命名空间用户只能查看和管理其所属命名空间下的资源，包括连接器、动作、数据源、规则等支持命名空间的模块。
- **集群级设置访问限制**：尚未支持命名空间隔离的全局配置项对命名空间用户为只读，只有系统管理员可进行修改。
- **消息内容端点限制**：部分访问或操作原始 MQTT 消息内容的 REST API 端点对命名空间用户不可用，调用时将返回 `403 Forbidden`。这些端点仅供全局管理员使用：
  - 消息队列消息：`GET /clients/:clientid/mqueue_messages`
  - 飞行窗口消息：`GET /clients/:clientid/inflight_messages`
  - 保留消息：`GET /mqtt/retainer/messages`、`GET /mqtt/retainer/message/:topic`、`DELETE /mqtt/retainer/message/:topic`、`DELETE /mqtt/retainer/messages`
  - 延迟消息：`GET /mqtt/delayed/messages`、`GET /mqtt/delayed/messages/:node/:msgid`、`DELETE /mqtt/delayed/messages/:node/:msgid`、`DELETE /mqtt/delayed/messages/:topic`
- **日志追踪隔离**：命名空间用户访问追踪端点时，仅能看到属于其命名空间的追踪记录。对不同命名空间的追踪执行停止、下载、流式读取日志或删除操作（`PUT /trace/:name/stop`、`GET /trace/:name/download`、`GET /trace/:name/log`、`GET /trace/:name/log_detail`、`DELETE /trace/:name`）将返回 `404 Not Found`，不会泄露其他命名空间的追踪是否存在。批量删除端点（`DELETE /trace`）对命名空间用户返回 `403 Forbidden`，仅全局管理员可清空所有追踪记录。
- **API 密钥管理**：命名空间管理员可以创建、查询、查看、更新和删除自己命名空间中的 API 密钥。命名空间管理员不能创建全局 API 密钥或其他命名空间中的密钥，所属命名空间之外的密钥不会显示。REST API 的详细行为参见[命名空间管理员管理 API 密钥](../api.md#命名空间管理员管理-api-密钥)。
- **默认登录首页**：命名空间用户登录 Dashboard 后默认进入**概览**页面，菜单项与普通用户一致，但资源数据将自动过滤，仅显示其命名空间内的数据。
- **License 管理限制**：命名空间用户不显示 License 相关提示，License 相关操作仅由系统管理员负责。

#### 命名空间内角色含义

- **管理员**：对指定命名空间下的资源拥有完整权限（创建、读取、更新、删除）。
- **查看者**：仅具备只读权限（等同于 GET 请求）权限，仅可查看资源数据。

## 审计日志

**审计日志**页面允许管理员配置审计日志功能，以实时监控 EMQX 集群中的关键操作变更。

有关审计日志功能的详细说明，请参见[审计日志](./audit-log.md)。

## API 密钥

**API 密钥**页面用于创建和管理访问 [HTTP API](../api.md) 所需的 API 密钥。有关创建和管理 API 密钥（包括角色与范围分配）的操作说明，请参见[创建 API 密钥](../api.md#创建-api-密钥)。

## License

点击左侧**系统设置**菜单下的 **License** 可以来到 License 页面。在该页面上可以查看当前 License 的基础信息，包括**签发对象**、 **License 使用情况**、**EMQX 版本信息**、**签发邮箱**、**签发时间**和**到期时间**。

点击**更新 License** 可以上传 License Key。在 **License 设置**区域可以设置 License 连接配额使用量的高水位线和低水位线。更多关于 License 的内容，参考[EMQX 企业版 License](../../get-started/deploy/license.md)。

## 单点登录

单点登录页面为管理员提供了用户登录管理中单点登录功能的配置。有关单点登录功能的详细介绍，参阅[单点登录](./sso.md)。

## 备份与恢复

**备份与恢复**页面提供用于备份运行数据和配置文件的相关设置。全局管理员可以在**全局**与具体 Namespace 之间切换，管理对应范围内的备份文件。选择具体 Namespace 后，可以上传、下载、删除和恢复备份文件，但不能创建备份。

有关备份与恢复功能的详细信息，请参见[备份与恢复](../backup-restore.md)。

## 设置

要访问设置，请点击 Dashboard 右上角的齿轮图标。

在**设置**菜单中，您可以自定义 Dashboard 的语言和主题样式：

- **语言**：选择您偏好的显示语言。
- **主题**：可在浅色和深色主题之间切换，或启用与操作系统主题的自动同步。当启用同步后，Dashboard 的主题将跟随操作系统设置，无法手动选择。

此外，设置菜单中还包含一个开关，用于启用或禁用**规则**页面中的 [SQL 生成器](../../develop/data-integration/rule-get-started.md#sql-generator)功能。

<img src="./assets/settings_ee.png" alt="settings_ee" style="zoom:67%;" />