Documentation

# 命令行

# 启动命令

EMQX 的主启动脚本也支持运行一些基本的管理命令。 帮助信息如下：

$ emqx help
Usage: emqx COMMAND [help]

Commonly used COMMANDs:
  start:      Start EMQX in daemon mode
  console:    Start EMQX in an interactive Erlang or Elixir shell
  foreground: Start EMQX in foreground mode without an interactive shell
  stop:       Stop the running EMQX node
  ctl:        Administration commands, execute 'emqx ctl help' for more details

More:
  Shell attach:  remote_console | attach
  Up/Down-grade: upgrade | downgrade | install | uninstall
  Install info:  ertspath | root_dir | versions | root_dir
  Runtime info:  pid | ping | versions
  Advanced:      console_clean | escript | rpc | rpcterms | eval | eval-erl

Execute 'emqx COMMAND help' for more information
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# ctl 命令介绍

所有的 ctl 命令 emqx ctl COMMAND ARGS ... (或者等效地： emqx_ctl COMMAND ARGS ...) 都需要 EMQX 服务启动之后才能运行。

ctl 命令通过启动一个隐藏的 Erlang 节点的方式，远程连接到指定的 EMQX 节点，并执行 一个 Erlang 远程调用然后打印返回的结果。

下面列举了所有 ctl 命令的子命令，和相应的简介。 本文档旨在介绍命令的功能。命令的详细参数介绍可以用 help 指令查看。

# status

emqx ctl status

快速查看当前运行的节点是否运行。

# broker

emqx ctl broker

查看当前节点的运行的版本状态以及运行时长。

# observer

emqx ctl observer

可以用于查看运行时状态。展示一个类似于 linux 的 top 命令的界面。

# cluster_call

emqx ctl cluster_call

该命令用于查看、调查甚至修改集群配置修改的同步状态。

EMQX 的 HTTP API 可以用于修改很多配置，当一个 API 被调用，例如从控制台界面的操作，来修改配置时， 在收到这个请求的节点会先将修改的内容在本地写入 data/configs/cluster-override.conf，然后 同样的操作会被记录在数据库中，并异步地转发到集群中的其他节点。

当由于某种原因，无法在另一个节点成功执行同样的修改，那么这个命令就可以很方便的查看这个异步复制的状态， 甚至可以强制跳过一个失败的复制。

EMQX 会为每个集群范围的配置修改生成一个ID，（tnxid），这个 ID 会在集群范围内严格递增， 每个修改，例如从控制台中修改一个配置之后，都会记录在数据库中。 下面这个例子，展示的是查看第二（tnxid=2）个修改的内容（这是一个启用 TLS 监听器的操作）。

$ emqx ctl cluster_call tnxid 2
{atomic,#{created_at => {{2022,6,21},{21,57,50}},
          initiator => 'emqx@127.0.0.1',
          mfa =>
              {emqx,update_config,
                    [[listeners,ssl,default],
                     {action,stop,#{<<"enabled">> => false}},
                     #{override_to => cluster,rawconf_with_defaults => true}]},
          tnx_id => 2}}
1
2
3
4
5
6
7
8
9

提示

skip 指令和 fast_forward 指令会迫使本地节点跳过一些（失败）的操作 这可能会导致集群内节点之间的配置不一致。

# admins

emqx ctl admins

这个命令用于创建，修改，删除管理员账户。

# retainer

emqx ctl retainer

这个命令可以用于查看和管理 retain 的消息。 也可以用于为 retain 表创建索引：emqx ctl retainer reindex 。

# cluster

emqx ctl cluster

这个命令可以查看和管理节点的集群状态。 请注意，EMQX 加入集群的指令 join 是向参数中指定的节点发送一个 “请求”，而不“邀请”。 也就是说，emqx ctl cluster join <OneOfTheClusteredNodes> 指令用于请求加入 OneOfTheClusteredNodes 所在的集群，而不是让这个节点加入自己所在的集群。

# clients

emqx ctl clients

可以用于查看和管理客户端。

提示

如果系统中连接了大量的客户端 list 指令可能会比较耗时且耗资源。

# topics

emqx ctl topics

这个命令在 4.x 系列中是 route，可用于查看当前系统中所有订阅的主题。

提示

如果集群中有大量的主题订阅，list 指令可能会比较耗时且耗资源。

# subscriptions

emqx ctl subscriptions

这个命令可以用于查看，增加或者删除某个客户端的订阅。

提示

当系统中有大量的订阅客户端时，list 指令可能比较耗时且耗资源。

# plugins

emqx ctl plugins

该命令用于查看和管理插件。

# vm

emqx ctl vm

用于查看 Erlang 虚拟机的运行时状态和指标。

# mnesia

emqx ctl mnesia

用于查看内置数据库（Mnesia）的运行状态和指标。

# log

emqx ctl log

用于管理日志参数，例如日志级别等。

# trace and traces

emqx ctl trace

用于对一个给定的客户端或主题进行日志追踪。

提示

建议在命令行中使用绝对路径指定追踪日志的文件。例如： emqx ctl trace start client foobar /abs/path/to/trace.log debug

提示

也可以在控制台界面中管理追踪日志。参考tracer 文档

emqx ctl traces

这个命令跟 trace 命令一样，但是会在整个集群所有节点中都开始或停止一个 tracer。

# listeners

emqx ctl listeners

管理监听器。

提示

停止监听器会导致所有通过该监听器接入的客户端都断开连接。

# authz cache-clean

emqx ctl authz cache-clean

这个命令用于强制所有客户端的授权（ACL）缓存立刻失效。

# pem_cache

emqx ctl pem_cache

这个命令可以用于清除 x509 pem 证书的缓存。

# olp

emqx ctl olp

OLP 是 “overload protection” 的缩写。 olp 命令可以用于检查系统过载的状态，也可以用于关闭或开启系统过载保护。

您可以在 overload_protection 的配置文档中查看更多信息。

提示

olp 是默认开启的，如果从命令行改变这个状态，这个改变只能持续到系统重启。重启之后会回到配置文件中的状态。

# gateway-registry

emqx ctl gateway-registry

查看当前系统中支持的网关。

当前默认支持的网关有如下 5 种：

  • coap
  • exproto
  • lwm2m
  • mqttsn
  • stomp

EMQX 的网关设计成可插拔。所以网关应用可以在启动/运行时注册到 EMQX 系统中。 一旦注册之后，就可以用 HTTP API 或者命令行来对网关进行管理了。

# gateway

emqx ctl gateway

用于查看和管理网关的启停状态。

# gateway-metrics

emqx ctl gateway-metrics

查看网关的指标。

# rules

emqx ctl rules

可用于查看系统中创建的所有的规则。 注意，命令行仅仅用于查看，规则的创建和更新等管理操作必需要在控制台的界面中操作。

← API 文档 (opens new window) →

编辑此页
本页导航