IPv6

EMQX 全面支持 IPv6，涵盖客户端连接、Dashboard、集群节点间通信以及到外部服务的出站连接。本页介绍如何在 IPv6 环境中配置 EMQX，包括纯 IPv6（单栈）和双栈部署。

MQTT 监听器

要通过 IPv6 接受 MQTT 客户端连接，需将监听器绑定到 IPv6 地址。当检测到 IPv6 绑定地址时，EMQX 会自动启用 inet6 socket 选项。

双栈（IPv4 和 IPv6）

绑定到 [::] 可在同一端口上同时接受 IPv4 和 IPv6 连接：

listeners.tcp.default {
  bind = "[::]:1883"
}

TIP

在大多数操作系统上，绑定到 [::] 默认同时接受 IPv4 和 IPv6 连接（双栈模式）。这是需要同时支持两种协议的环境中最简单的配置方式。

仅 IPv6

要将监听器限制为仅接受 IPv6 连接，请设置 ipv6_v6only = true：

listeners.tcp.default {
  bind = "[::]:1883"
  ipv6_v6only = true
}

此选项设置 IPV6_V6ONLY socket 选项，阻止接受 IPv4 映射的 IPv6 地址。

绑定到特定 IPv6 地址

可以绑定到特定的 IPv6 地址：

listeners.tcp.default {
  bind = "[::1]:1883"
}

相同的配置方式适用于 SSL、WebSocket 和安全 WebSocket 监听器：

listeners.ssl.default {
  bind = "[::]:8883"
  ssl_options {
    certfile = "etc/certs/cert.pem"
    keyfile = "etc/certs/key.pem"
    cacertfile = "etc/certs/cacert.pem"
  }
}

listeners.ws.default {
  bind = "[::]:8083"
}

listeners.wss.default {
  bind = "[::]:8084"
}

Dashboard HTTP/HTTPS 监听器

EMQX Dashboard 的 HTTP/HTTPS 监听器同样支持 IPv6。

使用 IPv6 绑定地址

当 bind 地址为 IPv6 地址时，EMQX 会自动为 Dashboard 监听器启用 IPv6：

dashboard.listeners.http {
  bind = "[::]:18083"
}

使用 inet6 标志

如果仅使用端口号绑定（不指定 IP 地址），可以显式启用 IPv6：

dashboard.listeners.http {
  bind = 18083
  inet6 = true
}

参数	类型	默认值	说明
inet6	boolean	false	启用 IPv6 支持。设为 false 时，监听器仅接受 IPv4 流量。
ipv6_v6only	boolean	false	禁用 IPv4 到 IPv6 的地址映射。仅在 inet6 为 true 时生效。

集群通信

当 EMQX 集群中的节点通过 IPv6 网络通信时，需要配置两个组件：Erlang 分布式协议（用于集群协调）和 Gen RPC 通道（用于节点间数据转发）。

Erlang 分布式协议

设置 cluster.proto_dist 以使用 IPv6 进行节点间通信：

cluster.proto_dist = inet6_tcp

可用选项：

值	说明
inet_tcp	基于 IPv4 的 TCP（默认）
inet6_tcp	基于 IPv6 的 TCP
inet_tls	基于 IPv4 的 TLS，通过 etc/ssl_dist.conf 配置
inet6_tls	基于 IPv6 的 TLS，通过 etc/ssl_dist.conf 配置

重要提示

当使用 IPv6 节点名称（例如 emqx@::1）时，必须将 cluster.proto_dist 设置为 inet6_tcp 或 inet6_tls。否则节点将无法启动，并报告"not responding to pings"错误。

Gen RPC

为 Gen RPC 配置 IPv6：

rpc.listen_address = "::"
rpc.ipv6_only = true

参数	类型	默认值	说明
rpc.listen_address	string	0.0.0.0	RPC 服务器监听的 IP 地址。IPv4 使用 0.0.0.0，IPv6 使用 ::。
rpc.ipv6_only	boolean	false	当 listen_address 为 IPv6 地址时，设为 true 可强制 RPC 客户端仅使用 IPv6。

出站连接

EMQX 会向外部服务发起出站连接，用于 HTTP 认证、Webhook 动作、数据库集成等功能。

自动 IPv6 检测

对于基于 HTTP 的连接器（认证后端、Webhook 动作等），EMQX 会自动探测目标主机是否支持 IPv6，并选择合适的地址族。大多数情况下无需手动配置。

手动配置

部分连接器类型在其配置中提供了 ipv6_probe 开关。启用时（HTTP 连接器默认启用），EMQX 会优先尝试 IPv6 连接。如果您的网络仅支持 IPv4 且 DNS 同时返回 A 和 AAAA 记录，可以禁用此探测以避免连接延迟：

# 示例：HTTP 认证后端
authentication {
  backend = "http"
  method = "post"
  url = "http://auth-server.example.com:8080/auth"

  # 如不需要，可禁用 IPv6 自动检测
  pool_size = 8
}

完整的纯 IPv6 配置示例

以下是纯 IPv6 部署的最小化 emqx.conf 配置：

# 使用 IPv6 地址的节点名称
node.name = "emqx@::1"

# 集群分布式协议使用 IPv6
cluster.proto_dist = inet6_tcp

# Gen RPC 使用 IPv6
rpc.listen_address = "::"
rpc.ipv6_only = true

# MQTT 监听器使用 IPv6
listeners.tcp.default {
  bind = "[::]:1883"
  ipv6_v6only = true
}

# Dashboard 使用 IPv6
dashboard.listeners.http {
  bind = "[::]:18083"
}

故障排查

节点无法响应 Ping

现象：使用 IPv6 节点名称启动集群节点时，节点报告"not responding to pings"并无法启动。

原因：Erlang 分布式协议默认使用 inet_tcp（IPv4）。IPv6 节点名称需要使用 inet6_tcp。

解决方案：在 emqx.conf 中设置 cluster.proto_dist = inet6_tcp。

出站连接报 enetunreach 错误

现象：出站 HTTP 请求（例如到认证后端的请求）失败，错误为 enetunreach（网络不可达）。

原因：连接尝试使用 IPv4 访问仅支持 IPv6 的服务，或反之。

解决方案：验证目标服务可通过正确的地址族从 EMQX 主机访问。对于 HTTP 连接器，自动 IPv6 探测功能通常可以处理此问题。如果服务使用域名，请确保 DNS 返回正确的记录类型（IPv4 为 A 记录，IPv6 为 AAAA 记录）。

IPv6 环境下 Dashboard 无法访问

现象：在纯 IPv6 环境中运行 EMQX 时，无法访问 Dashboard。

原因：Dashboard 监听器默认使用 IPv4（0.0.0.0:18083）。

解决方案：将 Dashboard 绑定到 IPv6 地址（bind = "[::]:18083"），或显式启用 IPv6（inet6 = true）。