EMQX Edge

简体中文

English

简体中文

English

Appearance

联系我们
联系我们

HTTP Server 配置 ​

EMQX Edge 内置 HTTP server，用于提供 Dashboard Web 界面和 HTTP API。以下配置控制该 server 如何暴露和保护，包括端口、连接限制、认证类型，以及可选的 HTTPS TLS 设置。

配置示例 ​

以下示例将 Dashboard 配置为监听 8081 端口，最多接受 32 个并发连接，并要求 Basic 认证。默认管理员账号由 username 和 password 定义。其他账号存储在 usernames 和 passwords 数组中。详情请参见 Dashboard 用户管理。

hocon
http_server {
  port = 8081
  ip_addr = "0.0.0.0"
  limit_conn = 32
  username = "admin"
  password = "<encrypted-password>"
  auth_type = basic
  usernames = ["user1"]
  passwords = ["<encrypted-password>"]
  max_body = 65535
  ssl = {
    enable = false
  }
}

配置项 ​

ParameterTypeDefaultDescription
portInteger8081HTTP server 监听端口。取值范围：0 ~ 65535。
ip_addrString"0.0.0.0"HTTP server 监听的 IP 地址。
limit_connInteger32Server 可处理的最大并发请求数。
auth_typeEnum"basic"HTTP server 认证类型。可选值："basic"、"jwt"。
usernameString"admin"默认 Dashboard 登录账号的用户名。
passwordString-默认 Dashboard 登录账号的加密密码。
usernamesArray-其他 Dashboard 账号的用户名。每一项对应 passwords 中相同索引位置的加密密码。通过 Dashboard UI 管理。
passwordsArray-其他 Dashboard 账号的加密密码。每一项对应 usernames 中相同索引位置的用户名。通过 Dashboard UI 管理。
max_bodyInteger65535HTTP 请求体最大大小，单位为字节。
jwt.public.keyfileString-JWT 校验使用的公钥文件路径。当 auth_type 为 "jwt" 时必填。

为 Dashboard 启用 HTTPS ​

默认情况下，Dashboard 通过 HTTP 提供服务。如果 Dashboard 可通过不可信网络访问，启用 HTTPS 可以加密连接，防止凭据以明文传输。要启用 HTTPS，请设置 ssl.enable = true，并提供有效证书和密钥。

注意

Dashboard HTTPS 仅支持自托管部署。你必须提供自己的证书和密钥文件。

SSL 配置项 ​

ParameterTypeDefaultDescription
ssl.enableBooleanfalse为 Dashboard 启用 HTTPS。设置为 true 后，可通过 https:// 访问 Dashboard。
ssl.key_passwordString-私钥文件密码，仅当私钥受密码保护时需要。
ssl.keyfileString-服务端私钥文件路径。
ssl.certfileString-服务端证书文件路径。
ssl.cacertfileString-当 ssl.verify_peer 为 true 时，用于验证对端/客户端证书的 CA 证书或 CA bundle 路径。
ssl.verify_peerBooleanfalse是否要求并验证客户端证书。
ssl.fail_if_no_peer_certBooleanfalse是否拒绝未提供证书的客户端连接。仅在 ssl.verify_peer 为 true 时生效。

准备自签名证书 ​

以下示例生成用于测试的自签名证书。生产环境请使用 CA 签发的证书。

  1. 创建 san.cnf 文件：

    ini
    [req]
default_bits       = 2048
prompt             = no
distinguished_name = dn
req_extensions     = req_ext
x509_extensions    = v3_ca
[dn]
CN = server
[req_ext]
subjectAltName = @alt_names
[v3_ca]
subjectAltName = @alt_names
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
[alt_names]
DNS.1 = server

    CN 和 DNS.1 的值定义证书有效的主机名（server）。后续步骤会使用该主机名。

  2. 生成证书和密钥：

    bash
    openssl req -x509 -nodes -days 825 \
  -newkey rsa:2048 \
  -keyout server.key \
  -out server.crt \
  -config san.cnf

  3. 将 server.key 和 server.crt 放到 EMQX Edge 可访问的目录，然后更新 nanomq.conf：

    hocon
    http_server {
  port = 8081
  ip_addr = "0.0.0.0"
  limit_conn = 32
  auth_type = basic
  ssl = {
    enable = true
    keyfile = "/etc/certs/https/server.key"
    certfile = "/etc/certs/https/server.crt"
    cacertfile = "/etc/certs/https/server.crt"
    verify_peer = false
    fail_if_no_peer_cert = false
  }
}

  4. 在运行浏览器的机器上，将证书添加到受信任证书存储。

    • macOS：

      bash
      sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ./server.crt

    • Ubuntu/Debian：

      bash
      sudo cp ./server.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

    在其他操作系统上，请参考系统文档添加受信任根证书。

  5. 在运行浏览器的机器上，将 server 主机名添加到 /etc/hosts，并将 <ip-address> 替换为 EMQX Edge 主机的实际 IP 地址：

    text
    <ip-address> server

  6. 重启 EMQX Edge，重新打开浏览器，然后访问 https://server:8081/。

验证 HTTPS 配置 ​

要确认 Dashboard 已正确通过 HTTPS 提供服务，请运行以下命令。该命令会检查 server 是否完成 TLS 握手，并通过 ALPN 协商 http/1.1 应用协议。

bash
curl -v --cacert server.crt https://server:8081 2>&1 | grep -i alpn

输出应包含：

text
ALPN: server accepted http/1.1