# Dashboard 配置

在 EMQX 中， Dashboard 是一个基于 Web 的图形界面，用于实时管理和监控 EMQX 及连接的设备。

EMQX Dashboard 配置包括很多配置项，例如，通过 `swagger_support` 启用 API 规范端点，以及为 Dashboard 配置监听器以接收所有传入连接。除此以外，还有以下常用配置项：

- `listeners`
- `token_expired_time`
- `password_expired_time`
- `password_login`
- `hwmark_expire_time`
- `cors`
- `default_password`
- `unsuccessful_login_max_attempts`
- `unsuccessful_login_duration`
- `unsuccessful_login_interval`
- `sso`

以下为 Dashboard 配置示例：

```bash
dashboard {
  listeners {
    http {
      bind = "0.0.0.0:18083"
      max_connections = 512
    }
    https {
      # set 'bind = 0' will disable this listener
      bind = "0.0.0.0:18084"
      ssl_options {
        certfile = "${EMQX_ETC_DIR}/certs/cert.pem"
        keyfile = "${EMQX_ETC_DIR}/certs/key.pem"
      }
    }
  }
  token_expired_time = 60m
  password_expired_time = 0
  password_login = both
  cors = false
  swagger_support = true
  default_password = jEdOgGS6vzQ
  unsuccessful_login_max_attempts = 5
  unsuccessful_login_lock_duration = 10m
  unsuccessful_login_interval = 5m
  sso = {
    # Normally, only one of `ldap`, `oidc`, or `smal` can be active at a time. Below is for the demonstration purposes.
    ldap = {
      enable = true
      backend = "ldap"
      query_timeout = "5s"
      server = "localhost:389"
      pool_size = 8
      username = "cn=admin,dc=example,dc=com"
      password = "secret"
      base_dn = "dc=example,dc=com"
      filter = "(& (objectClass=person) (uid=${username}))"
      request_timeout = "10s"
    }
    oidc = {
      enable = true
      backend = oidc
      issuer = "https://issuer.example.com"
      clientid = "your-client-id"
      secret = "your-client-secret"
      scopes = [
        "openid"
      ]
      name_var = "${sub}"
      dashboard_addr = "http://127.0.0.1:18083"
      session_expiry = "30s"
      require_pkce = false
      preferred_auth_methods = [
        "client_secret_post",
        "client_secret_basic",
        "none"
      ]
      provider = generic
      fallback_methods = [
        "RS256"
      ]
    }
    saml = {
      enable = true
      backend = "saml"
      dashboard_addr = "https://127.0.0.1:18083"
      idp_metadata_url = "https://idp.example.com"
      sp_sign_request = false
      sp_public_key = "Pub Key"
      sp_private_key = "SP Private Key"
    }
  }
}
```

其中，

- `bind = "0.0.0.0:18083"`

  用于设置监听器绑定的网络地址和端口号。在以上示例中，监听器将绑定到所有可用的网络接口（`0.0.0.0`）上的端口 `18083`。

  从 EMQX 6.3.0 开始，当 `dashboard.listeners.http.bind` 仅指定端口（例如 `18083`）时，EMQX 使用 `node.default_listener_address` 确定各节点的绑定地址。未设置该配置项时，HTTP 监听器在 `legacy` 安全配置方案下监听所有网络接口，在 `hardened` 方案下绑定回环地址。`bind` 中显式指定的 IP 地址（如上例所示）优先于默认地址。

  该默认地址配置不适用于 Dashboard HTTPS 监听器。支持的取值、重启要求及 Docker 默认值参见[默认监听地址](../access-control/security-profile.md#默认监听地址)。

- `max_connections = 512` 

  用于设置监听器将接受的最大并发连接数。在以上示例中，最大连接数设置为 `512`。

- `ssl_options.certfile`

  指向包含 PEM 格式证书的文件。文件中第一个证书必须是服务器证书，紧接着是签发这个证书的中间 CA 证书，依次罗列到根 CA 证书为止。（根 CA 证书可选）。

- `ssl_options.keyfile`

  指向包含 PEM 格式的私钥文件。

- `token_expired_time`

  JWT Token 的过期时间，等同于“浏览器会话过期时间”。用户登录后，EMQX 会生成一个 JWT Token 和一个刷新 Token。会话会在到期前自动续期。默认值为 `60m`。

- `hwmark_expire_time`

  最高水印过期时间。默认值为 `7d`。过期后，Dashboard 将找到自过期时间到当前时间为止的最高水印。

- `password_expired_time`

  设置用户用于登录 Dashboard 的密码的过期时间，比如 `1h`。超过此时间，用户在登录 Dashboard 时必须修改密码。默认值 `0` 表示密码永不过期。

- `password_login`

  从 EMQX 6.3.1 开始，控制本地 Dashboard 用户可使用的认证方式。支持以下取值：

  - `both`：同时接受 SCRAM-SHA-256 挑战-响应登录和基于密码的 `POST /api/v5/login` 请求。此项为默认值，可兼容在请求体中发送密码的脚本和客户端。
  - `scram_only`：仅接受 SCRAM-SHA-256 挑战-响应登录。在此模式下，`POST /api/v5/login` 返回 HTTP `403` 和错误码 `PASSWORD_LOGIN_DISABLED`。使用本地 Dashboard 用户凭据获取 Bearer Token 的脚本和第三方客户端必须改用 SCRAM 端点。仅调用 EMQX 管理 REST API 的程序可以改用 API 密钥。

  设置为 `scram_only` 前，请将所有 EMQX 节点以及使用本地 Dashboard 用户凭据登录的客户端升级到支持 SCRAM 的版本。密码迁移、浏览器访问和登录操作参见[配置本地 Dashboard 用户的认证方式](../dashboard-security.md#配置本地-dashboard-用户的认证方式)。

- `cors`

  是否支持跨域资源共享（CORS）。如果您希望从其他域（如自定义前端）访问 Dashboard 的 API，可将此项设置为 `true`。

- `swagger_support = true`

  用于启用 API 文档端点，包括 `/api-spec.html`、`/api-spec.md`、`/api-spec.json`，以及提供完整 OpenAPI 规范的 `/api-docs/swagger.json`。为保持向后兼容，`/api-docs` 和 `/api-docs/index.html` 会重定向到 `/api-spec.html`。将此配置项设置为 `false` 可禁用所有 API 文档端点。

  从 EMQX 6.3.0 开始，必须通过认证才能从这些端点访问 API 规范内容。有关支持的认证方式和未认证响应行为，参见[访问 API 规范端点](../api.md#访问-api-规范端点)。

- `default_password`

  用于为 `admin` 用户初始化数据库条目的默认密码。注意：一旦 EMQX 初次启动成功，修改这个密码将不再不起作用。初始化后，密码必须在控制台或者命令行进行修改。


- `unsuccessful_login_max_attempts`

  指定在特定时间内允许的最大登录失败次数。如果用户超过此限制，账户将被暂时锁定。默认值为 `5`。

- `unsuccessful_login_duration`

  设置达到最大失败登录次数后账户被锁定的持续时间。默认值为 `10` 分钟。

- `unsuccessful_login_interval`

  定义了一个时间窗口，在该时间窗口内，失败的登录尝试会被计入限制。例如，如果设置为 `5`，则系统将在5分钟内跟踪失败的登录尝试次数。默认值为 `5` 分钟。

- `sso`

  配置[单点登录（SSO）](../dashboard/sso.md) 选项。`ldap`、`oidc` 和 `saml` 三者中只能启用一个。如需详细的配置说明，请参阅[配置手册](https://docs.emqx.com/zh/enterprise/v6.3.1/hocon/#V-dashboard-S-dashboard-sso)中的 SSO 部分。

::: tip

EMQX 提供了更多配置项以更好地满足定制化需求。详情请参见 [EMQX 企业版配置手册](https://docs.emqx.com/zh/enterprise/v6.3.1/hocon/)。

:::