本章將讓您熟悉如何使用 Apache ActiveMQ Artemis 伺服器。

我們將說明它的位置、如何啟動和停止它，並將描述目錄結構以及所有檔案的功能。

本文檔將把 ActiveMQ 發行版解壓縮到的目錄完整路徑稱為 ${ARTEMIS_HOME}。

1. 安裝

您可以從下載頁面取得最新版本。

以下重點說明發行版中的一些重要資料夾

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

執行 ActiveMQ Artemis 所需的二進制檔案和腳本。

lib

執行 ActiveMQ Artemis 所需的 jar 檔和程式庫

schema

用於驗證 ActiveMQ Artemis 設定檔的 XML Schema

web

Broker 執行時載入 Web 內容的資料夾。

2. 建立 Broker 實例

Broker「實例」是一個目錄，其中包含與 Broker 處理程序相關聯的所有設定和執行時資料，例如日誌和訊息日誌。建議您「不要」在 ${ARTEMIS_HOME} 下建立實例目錄。鼓勵這種分離，以便您在發佈下一個版本的 ActiveMQ Artemis 時更容易升級。

在 Unix 系統上，習慣將此類執行時資料儲存在 /var/lib 目錄下。例如，若要在 /var/lib/mybroker 建立實例，請在命令列殼層中執行下列命令

在使用 Broker 之前，必須先建立 Broker 實例。此程序需要使用命令列介面，該介面在其單獨的章節中有更詳細的說明。

在以下範例中，將建立名為 mybroker 的 Broker 實例

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

Broker 實例目錄將包含以下子目錄

bin

持有與此實例關聯的執行腳本。

data

持有用於儲存持久訊息的資料檔案

etc

持有實例設定檔

lib

持有任何自訂執行時 Java 相依性，例如轉換器、外掛程式、攔截器等。

log

持有輪換日誌檔案

tmp

持有在 Broker 執行之間可以安全刪除的暫存檔

此時，您可能需要調整位於 etc 目錄中的預設設定。

2.1. 選項

建立實例時，可以使用多個選項。如需完整選項清單，請使用 help 命令

$ ./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.

其中一些選項在某些設定中可能是強制性的，系統可能會要求您提供額外輸入，例如

$ ./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

3. 啟動與停止 Broker 實例

假設您在 /var/lib/mybroker 下建立 Broker 實例，您只需執行以下命令即可啟動 Broker 實例

/var/lib/mybroker/bin/artemis run

若要停止 Apache ActiveMQ Artemis 實例，您將使用相同的 artemis 腳本，但帶有 stop 引數。範例

/var/lib/mybroker/bin/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. 設定檔

這些是您可能會在預設 Broker 實例的 etc 目錄中找到的檔案，並簡要說明它們設定的內容。向下捲動以查看其他詳細資訊。

artemis.profile

系統屬性和 JVM 引數 (例如 Xmx、Xms 等)

artemis-roles.properties

預設基於屬性的 JAAS 登入模組的使用者/角色對應

artemis-users.properties

預設基於屬性的 JAAS 登入模組的使用者/密碼

bootstrap.xml

嵌入式 Web 伺服器、安全性、broker.xml 的位置

broker.xml

核心 Broker 設定，例如接受器、位址、佇列、轉向、叢集；完整參考

jolokia-access.xml

Jolokia 的安全性，特別是跨來源資源共享 (CORS)

log4j2.properties

日誌設定，例如層級、日誌檔位置等。

login.config

JAAS 安全性的標準 Java 設定

management.xml

遠端連線和 JMX MBean 的安全性

4.1. 啟動設定檔

bootstrap.xml 檔案非常簡單。讓我們看一個範例

<broker xmlns="https://activemq.dev.org.tw/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>
jaas-security

為伺服器設定基於 JAAS 的安全性。domain 屬性是指 login.config 中的相關登入模組項目。如果需要不同的行為，可以通過將 jaas-security 替換為 security-manager 來設定自訂安全性管理員。如需更多詳細資訊，請參閱安全性章節中的「自訂安全性管理員」部分。

server

使用 configuration 屬性中的設定檔來實例化核心伺服器。這是執行所有實際訊息傳遞工作所需的主要 Broker POJO。

web

設定嵌入式 Web 伺服器以用於管理主控台等。

4.2. Broker 設定檔

Apache ActiveMQ Artemis 核心 Broker 的設定包含在 broker.xml 中。

您可以為 Apache ActiveMQ Artemis 設定許多屬性。在大多數情況下，預設值都可以正常運作，事實上，每個屬性都可以預設，這表示具有單個空 configuration 元素的檔案是有效的設定檔。不同的設定將在手冊中進行說明，或者您可以參考此處的設定參考。

5. 其他使用案例

5.1. 系統屬性替換

可以在所有設定檔中使用系統屬性替換。方法是用系統屬性的名稱替換值。以下是使用連接器設定的範例

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

在這裡，您可以看到我們已將 2 個值替換為系統屬性 activemq.remoting.netty.host 和 activemq.remoting.netty.port。這些值將由系統屬性中找到的值替換（如果有的話），如果沒有，則會分別預設為 localhost 或 61616。也可以不提供預設值 (即 ${activemq.remoting.netty.host})，但是，在這種情況下「必須」提供系統屬性。

5.2. Windows 伺服器

在 Windows 上，您可以選擇將 ActiveMQ Artemis 作為服務執行。只需使用以下命令進行安裝

 $ ./artemis-service.exe install

建立程序應會提示您 artemis-service.exe 可用的命令

5.3. 新增啟動相依性

啟動相依性（例如日誌處理程式）必須在啟動時可供日誌管理員存取。將相依性打包到 jar 檔中，並將其置於日誌管理員 jar 之前的啟動類別路徑上。這可以通過使用 -Xbootclasspath/a 選項，將 jar 附加到 artemis.profile 中定義的變數 JAVA_ARGS 來完成。

環境變數 JAVA_ARGS_APPEND 可以用於附加或覆寫選項。

5.4. 新增執行時相依性

執行時相依性（例如轉換器、Broker 外掛程式、JDBC 驅動程式、密碼解碼器等）必須在執行時可供 Broker 存取。將相依性打包到 jar 檔中，並將其置於 Broker 發行版本身的 lib 目錄中、置於 Broker 實例的 lib 目錄中，透過設定具有 jar 檔案所在目錄的系統屬性 artemis.extra.libs，或透過設定具有 jar 檔案所在目錄的環境變數 ARTEMIS_EXTRA_LIBS 來完成。預設情況下，Broker 實例沒有 lib 目錄，因此可能需要建立該目錄。它應與 bin、data、log 等目錄位於「頂層」。系統屬性 artemis.extra.libs 是包含 jar 檔案的目錄的逗號分隔清單，即

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

環境變數 ARTEMIS_EXTRA_LIBS 是包含 jar 檔案的目錄的逗號分隔清單，如果定義了系統屬性 artemis.extra.libs，則會忽略該環境變數，即

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

5.5. 程式庫路徑

如果您在 Linux 上使用非同步 IO 日誌，則需要在 Java 選項中指定 java.library.path 作為屬性。這會在腳本中自動完成。

如果您未在 Java 選項中指定 java.library.path，則 JVM 將使用環境變數 LD_LIBRARY_PATH。

您需要確保在 Linux 上安裝了 libaio。如需更多資訊，請參閱libaio 章節。