本章将带您了解如何使用 Apache ActiveMQ Artemis 服务器。

我们将展示它的位置、如何启动和停止它，以及描述目录布局、所有文件及其功能。

本文档将引用 ActiveMQ 分发文件解压到的目录的完整路径，表示为 ${ARTEMIS_HOME}。

1. 安装

您可以从 下载 页面获取最新版本。

以下是分发中一些重要文件夹的说明

|___ bin
|
|___ lib
|
|___ schema
|
|___ web
bin

运行 ActiveMQ Artemis 所需的二进制文件和脚本。

lib

运行 ActiveMQ Artemis 所需的 jar 和库。

schema

用于验证 ActiveMQ Artemis 配置文件的 XML 模式。

web

代理运行时加载 Web 上下文的文件夹。

2. 创建代理实例

代理实例是包含所有配置和运行时数据（如日志和消息日志）的目录，这些数据与代理进程相关联。建议您不要在 ${ARTEMIS_HOME} 下创建实例目录。鼓励这种分离，以便在发布 ActiveMQ Artemis 的下一个版本时更轻松地进行升级。

在 Unix 系统上，通常将这种运行时数据存储在 /var/lib 目录下。例如，要在 /var/lib/mybroker 创建一个实例，请在命令行 shell 中运行以下命令

在使用代理之前，必须创建代理实例。此过程需要使用 命令行界面，该界面将在其自己的章节中详细说明。

在以下示例中，将创建一个名为 mybroker 的代理实例

$ cd /var/lib
$ ${ARTEMIS_HOME}/bin/artemis create mybroker

代理实例目录将包含以下子目录

bin

bin

包含与该实例相关的执行脚本。

data

包含用于存储持久消息的数据文件。

etc

lib

包含实例配置文件。

lib

包含任何自定义运行时 Java 依赖项，如转换器、插件、拦截器等。

log

包含循环日志文件。

tmp

包含代理运行之间可以安全删除的临时文件。

此时，您可能需要调整 etc 目录中默认配置。

$ ./artemis help create
Usage: artemis create [--aio] [--allow-anonymous] [--autocreate] [--autodelete]
                      [--backup] [--blocking] [--clustered]
                      [--disable-persistence] [--failover-on-shutdown]
                      [--force] [--jdbc] [--linux] [--mapped] [--nio]
                      [--no-amqp-acceptor] [--no-autocreate] [--no-autotune]
                      [--no-fsync] [--no-hornetq-acceptor] [--no-mqtt-acceptor]
                      [--no-stomp-acceptor] [--no-web] [--paging]
                      [--relax-jolokia] [--replicated] [--require-login]
                      [--shared-store] [--silent] [--slave]
                      [--support-advisory]
                      [--suppress-internal-management-objects]
                      [--use-client-auth] [--verbose] [--windows]
                      [--addresses=<addresses>]
                      [--cluster-password=<clusterPassword>]
                      [--cluster-user=<clusterUser>] [--data=<data>]
                      [--default-port=<defaultPort>] [--encoding=<encoding>]
                      [--etc=<etc>] [--global-max-messages=<globalMaxMessages>]
                      [--global-max-size=<globalMaxSize>] [--home=<home>]
                      [--host=<host>] [--http-host=<httpHost>]
                      [--http-port=<httpPort>] [--java-memory=<javaMemory>]
                      [--jdbc-bindings-table-name=<jdbcBindings>]
                      [--jdbc-connection-url=<jdbcURL>]
                      [--jdbc-driver-class-name=<jdbcClassName>]
                      [--jdbc-large-message-table-name=<jdbcLargeMessages>]
                      [--jdbc-lock-expiration=<jdbcLockExpiration>]
                      [--jdbc-lock-renew-period=<jdbcLockRenewPeriod>]
                      [--jdbc-message-table-name=<jdbcMessages>]
                      [--jdbc-network-timeout=<jdbcNetworkTimeout>]
                      [--jdbc-node-manager-table-name=<jdbcNodeManager>]
                      [--jdbc-page-store-table-name=<jdbcPageStore>]
                      [--journal-device-block-size=<journalDeviceBlockSize>]
                      [--journal-retention=<retentionDays>]
                      [--journal-retention-max-bytes=<retentionMaxBytes>]
                      [--max-hops=<maxHops>]
                      [--message-load-balancing=<messageLoadBalancing>]
                      [--name=<name>] [--password=<password>] [--ping=<ping>]
                      [--port-offset=<portOffset>] [--queues=<queues>]
                      [--role=<role>] [--security-manager=<securityManager>]
                      [--ssl-key=<sslKey>]
                      [--ssl-key-password=<sslKeyPassword>]
                      [--ssl-trust=<sslTrust>]
                      [--ssl-trust-password=<sslTrustPassword>]
                      [--staticCluster=<staticNode>] [--user=<user>]
                      [--java-options=<javaOptions>]... <directory>
Create a new broker instance.
      <directory>            The instance directory to hold the broker's
                               configuration and data. Path must be writable.
      --addresses=<addresses>
                             A comma separated list of addresses with the
                               option to specify a routing type, e.g.
                               --addresses myAddress1,myAddress2:anycast.
                               Routing-type default: multicast.
      --aio                  Set the journal as asyncio.
      --allow-anonymous      Allow connections from users with no security
                               credentials. Opposite of --require-login.
                               Default: input.
      --autocreate           Allow automatic creation of addresses & queues.
                               Default: true.
      --autodelete           Allow automatic deletion of addresses & queues.
                               Default: false.
      --backup               Be a backup broker. Valid for shared store or
                               replication.
      --blocking             Block producers when address becomes full.
                               Opposite of --paging. Default: false.
      --cluster-password=<clusterPassword>
                             The password to use for clustering. Default: input.
      --cluster-user=<clusterUser>
                             The user to use for clustering. Default: input.
      --clustered            Enable clustering.
      --data=<data>          Directory where ActiveMQ data are stored. Paths
                               can be absolute or relative to artemis.instance
                               directory. Default: data.
      --default-port=<defaultPort>
                             The port number to use for the main 'artemis'
                               acceptor. Default: 61616.
      --disable-persistence  Disable message persistence to the journal
      --encoding=<encoding>  The encoding that text files should use. Default:
                               UTF-8.
      --etc=<etc>            Directory where ActiveMQ configuration is located.
                               Paths can be absolute or relative to artemis.
                               instance directory. Default: etc.
      --failover-on-shutdown Whether broker shutdown will trigger failover for
                               clients using the core protocol. Valid only for
                               shared store. Default: false.
      --force                Overwrite configuration at destination directory.
      --global-max-messages=<globalMaxMessages>
                             Maximum number of messages that will be accepted
                               in memory before using address full policy mode.
                               Default: undefined.
      --global-max-size=<globalMaxSize>
                             Maximum amount of memory which message data may
                               consume. Default: half of the JVM's max memory.
      --home=<home>          Directory where ActiveMQ Artemis is installed.
      --host=<host>          Broker's host name. Default: 0.0.0.0 or input if
                               clustered).
      --http-host=<httpHost> Embedded web server's host name. Default:
                               localhost.
      --http-port=<httpPort> Embedded web server's port. Default: 8161.
      --java-memory=<javaMemory>
                             Define the -Xmx memory parameter for the broker.
                               Default: 2G.
      --java-options=<javaOptions>
                             Extra Java options to be passed to the profile.
      --jdbc                 Store message data in JDBC instead of local files.
      --jdbc-bindings-table-name=<jdbcBindings>
                             Name of the jdbc bindings table.
      --jdbc-connection-url=<jdbcURL>
                             The URL used for the database connection.
      --jdbc-driver-class-name=<jdbcClassName>
                             JDBC driver classname.
      --jdbc-large-message-table-name=<jdbcLargeMessages>
                             Name of the large messages table.
      --jdbc-lock-expiration=<jdbcLockExpiration>
                             Lock expiration (in milliseconds).
      --jdbc-lock-renew-period=<jdbcLockRenewPeriod>
                             Lock Renew Period (in milliseconds).
      --jdbc-message-table-name=<jdbcMessages>
                             Name of the jdbc messages table.
      --jdbc-network-timeout=<jdbcNetworkTimeout>
                             Network timeout (in milliseconds).
      --jdbc-node-manager-table-name=<jdbcNodeManager>
                             Name of the jdbc node manager table.
      --jdbc-page-store-table-name=<jdbcPageStore>
                             Name of the page store messages table.
      --journal-device-block-size=<journalDeviceBlockSize>
                             The block size of the journal's storage device.
                               Default: 4096.
      --journal-retention=<retentionDays>
                             Configure journal retention in days. If > 0 then
                               enable journal-retention-directory from broker.
                               xml allowing replay options.
      --journal-retention-max-bytes=<retentionMaxBytes>
                             Maximum number of bytes to keep in the retention
                               directory.
      --linux, --cygwin      Force Linux or Cygwin script creation. Default:
                               based on your actual system.
      --mapped               Set the journal as mapped.
      --max-hops=<maxHops>   Number of hops on the cluster configuration.
      --message-load-balancing=<messageLoadBalancing>
                             Message load balancing policy for cluster.
                               Default: ON_DEMAND. Valid values: ON_DEMAND,
                               STRICT, OFF, OFF_WITH_REDISTRIBUTION.
      --name=<name>          The name of the broker. Default: same as host name.
      --nio                  Set the journal as nio.
      --no-amqp-acceptor     Disable the AMQP specific acceptor.
      --no-autocreate        Disable auto creation for addresses & queues.
      --no-autotune          Disable auto tuning of the journal-buffer-timeout
                               in broker.xml.
      --no-fsync             Disable usage of fdatasync (channel.force(false)
                               from Java NIO) on the journal.
      --no-hornetq-acceptor  Disable the HornetQ specific acceptor.
      --no-mqtt-acceptor     Disable the MQTT specific acceptor.
      --no-stomp-acceptor    Disable the STOMP specific acceptor.
      --no-web               Whether to omit the web-server definition from
                               bootstrap.xml.
      --paging               Page messages to disk when address becomes full.
                               Opposite of --blocking. Default: true.
      --password=<password>  The user's password. Default: input.
      --ping=<ping>          A comma separated string to be passed on to the
                               broker config as network-check-list. The broker
                               will shutdown when all these addresses are
                               unreachable.
      --port-offset=<portOffset>
                             How much to off-set the ports of every acceptor.
      --queues=<queues>      A comma separated list of queues with the option
                               to specify a routing type, e.g. --queues
                               myQueue1,myQueue2:multicast. Routing-type
                               default: anycast.
      --relax-jolokia        Disable strict checking in jolokia-access.xml.
      --replicated           Enable broker replication.
      --require-login        Require security credentials from users for
                               connection. Opposite of --allow-anonymous.
      --role=<role>          The name for the role created. Default: amq.
      --security-manager=<securityManager>
                             Which security manager to use - jaas or basic.
                               Default: jaas.
      --shared-store         Enable broker shared store.
      --silent               Disable all the inputs, and make a best guess for
                               any required input.
      --slave                Deprecated for removal. Use 'backup' instead.
      --ssl-key=<sslKey>     Embedded web server's key store path.
      --ssl-key-password=<sslKeyPassword>
                             The key store's password.
      --ssl-trust=<sslTrust> The trust store path in case of client
                               authentication.
      --ssl-trust-password=<sslTrustPassword>
                             The trust store's password.
      --staticCluster, --static-cluster=<staticNode>
                             Cluster node connectors list separated by comma, e.
                               g. "tcp://server:61616,tcp://server2:61616,tcp:
                               //server3:61616".
      --support-advisory     Support advisory messages for the OpenWire
                               protocol.
      --suppress-internal-management-objects
                             Do not register any advisory addresses/queues for
                               the OpenWire protocol with the broker's
                               management service.
      --use-client-auth      Require client certificate authentication when
                               connecting to the embedded web server.
      --user=<user>          The username. Default: input.
      --verbose              Print additional information.
      --windows              Force Windows script creation. Default: based on
                               your actual system.

2.1. 选项

$ ./artemis create /usr/server
Creating ActiveMQ Artemis instance at: /usr/server

--user:
What is the default username?
admin

--password: is mandatory with this configuration:
What is the default password?


--allow-anonymous | --require-login:
Allow anonymous access?, valid values are Y, N, True, False
y

Auto tuning journal ...
done! Your system can make 250 writes per millisecond, your journal-buffer-timeout will be 4000

You can now start the broker by executing:

   "/usr/server" run

Or you can run the broker in the background using:

   "/usr/server" start

在创建实例时，您可以使用多种选项。要查看完整的选项列表，请使用 help 命令

在某些配置中，这些选项中的一些可能是必需的，系统可能会要求您提供额外的输入，例如

/var/lib/mybroker/bin/artemis run

3. 启动和停止代理实例

/var/lib/mybroker/bin/artemis stop

假设您在 /var/lib/mybroker 下创建了代理实例，您只需执行以下操作即可启动代理实例

要停止 Apache ActiveMQ Artemis 实例，您将使用相同的 artemis 脚本，但使用 stop 参数。例如

请注意，Apache ActiveMQ Artemis 需要 Java 11 或更高版本。

默认情况下，将使用 etc/bootstrap.xml 配置。例如，可以通过运行 ./artemis run -- xml:path/to/bootstrap.xml 或您选择的其他配置来更改配置。

环境变量用于简化端口、主机和数据目录使用的更改，可以在 Linux 上的 etc/artemis.profile 和 Windows 上的 etc\artemis.profile.cmd 中找到。

4. 配置文件

这些是您可能在默认代理实例的 etc 目录中找到的文件，以及对它们配置内容的简短说明。向下滚动以获取更多详细信息（如果适用）。

artemis.profile

系统属性和 JVM 参数（例如 Xmx、Xms 等）。

artemis-roles.properties

默认 基于属性的 JAAS 登录模块 的用户/角色映射。

artemis-users.properties

默认 基于属性的 JAAS 登录模块 的用户/密码。

bootstrap.xml

嵌入式 Web 服务器、安全、broker.xml 的位置。

broker.xml

核心代理配置，例如接受器、地址、队列、转移、集群；完整参考

jolokia-access.xml

Jolokia 的安全性，特别是跨域资源共享 (CORS)。

log4j2.properties

日志记录配置，如级别、日志文件位置等。

login.config

JAAS 安全性 的标准 Java 配置。

management.xml

远程连接和 JMX MBean 的安全性。

<broker xmlns="https://activemq.apache.org/schema">

   <jaas-security domain="activemq"/>

   <server configuration="file:/path/to/broker.xml"/>

   <web path="web">
      <binding uri="https://127.0.0.1:8161">
         <app url="activemq-branding" war="activemq-branding.war"/>
         <app url="artemis-plugin" war="artemis-plugin.war"/>
         <app url="console" war="console.war"/>
      </binding>
   </web>
</broker>
4.1. 引导配置

bootstrap.xml 文件非常简单。让我们看一个示例

jaas-security

为服务器配置基于 JAAS 的安全性。domain 属性引用 login.config 中相关的登录模块条目。如果需要不同的行为，则可以通过将 jaas-security 替换为 security-manager 来配置自定义安全管理器。有关更多详细信息，请参见 安全性章节 中的“自定义安全管理器”部分。

web

server

使用 configuration 属性中的配置文件实例化核心服务器。这是执行所有实际消息传递工作所需的主要代理 POJO。

为管理控制台等配置嵌入式 Web 服务器。

4.2. 代理配置文件

Apache ActiveMQ Artemis 核心代理的配置包含在 broker.xml 中。

您可以为 Apache ActiveMQ Artemis 配置许多属性。在大多数情况下，默认值就足够了，实际上每个属性都可以有默认值，这意味着只有一个空 configuration 元素的文件是一个有效的配置文件。不同的配置将在整个手册中进行解释，或者您可以参考配置参考 此处。

5. 其他用例

<connector name="netty">tcp://${activemq.remoting.netty.host:localhost}:${activemq.remoting.netty.port:61616}</connector>

5.1. 系统属性替换

可以在所有配置文件中使用系统属性替换，方法是用系统属性的名称替换值。以下是一个使用连接器配置的示例

在这里，您可以看到我们将 2 个值替换为系统属性 activemq.remoting.netty.host 和 activemq.remoting.netty.port。如果存在这些值，它们将被系统属性中找到的值替换，否则它们将分别默认为 localhost 或 61616。也可以不提供默认值（即 ${activemq.remoting.netty.host}），但是在这种情况下必须提供系统属性。

 $ ./artemis-service.exe install

5.2. Windows 服务器

在 Windows 上，您可以选择将 ActiveMQ Artemis 作为服务运行。只需使用以下命令来安装它

创建过程应该会提示您有关 artemis-service.exe 可用命令的信息。

5.3. 添加引导依赖项

引导依赖项（如日志处理程序）必须在启动时可供日志管理器访问。将依赖项打包到 jar 中，并将其放在日志管理器 jar 之前的引导类路径上。这可以通过在 artemis.profile 中定义的 JAVA_ARGS 变量中追加 jar 来实现，方法是使用 -Xbootclasspath/a 选项。

可以使用环境变量 JAVA_ARGS_APPEND 来追加或覆盖选项。

-Dartemis.extra.libs=/usr/local/share/java/lib1,/usr/local/share/java/lib2

5.4. 添加运行时依赖项

export ARTEMIS_EXTRA_LIBS=/usr/local/share/java/lib1,/usr/local/share/java/lib2

运行时依赖项（如转换器、代理插件、JDBC 驱动程序、密码解码器等）必须在运行时可供代理访问。将依赖项打包到 jar 中，并将其放在代理的类路径上。这可以通过将 jar 文件放在代理分发本身的 lib 目录中、将 jar 文件放在代理实例的 lib 目录中、使用 artemis.extra.libs 系统属性设置包含 jar 文件的目录，或使用 ARTEMIS_EXTRA_LIBS 环境变量设置包含 jar 文件的目录来实现。默认情况下，代理实例没有 lib 目录，因此可能需要创建它。它应该位于与 bin、data、log 等目录相同的“顶层”。artemis.extra.libs 系统属性是包含 jar 文件的目录的逗号分隔列表，即

ARTEMIS_EXTRA_LIBS 环境变量是包含 jar 文件的目录的逗号分隔列表，如果定义了 artemis.extra.libs 系统属性，则会忽略它，即

5.5. 库路径

如果您在 Linux 上使用 异步 IO 日志，则需要在 Java 选项中指定 java.library.path 作为属性。这在脚本中自动完成。