搜索

配置指南

download PDF
Red Hat JBoss Enterprise Application Platform 7.3

设置和维护红帽 JBoss 企业应用平台的说明,包括运行应用程序和服务.

摘要

本指南的目的是涵盖设置和维护 JBoss EAP 以及在其上运行应用程序和其他服务所需的许多配置任务。

第 1 章 简介

在使用本指南配置 JBoss EAP 之前,假定已下载和安装了 JBoss EAP 的最新版本。有关安装说明,请参阅 JBoss EAP安装指南

重要

由于 JBoss EAP 的安装位置因主机计算机而异,本指南将安装位置称为 EAP_HOME。在执行管理任务时,应使用 JBoss EAP 安装的实际位置,而非 EAP_HOME

第 2 章 启动和停止 JBoss EAP

2.1. 启动 JBoss EAP

JBoss EAP 在红帽企业 Linux、Windows Server 和 Oracle Solaris 上受支持,并且以单机服务器或受管域工作模式运行。启动 JBoss EAP 的具体命令取决于底层平台和所需的工作模式。

服务器最初以暂停状态启动,在启动所有必要的服务之前,将不会接受任何请求;达到此刻,服务器将置于正常运行状态并可以开始接受请求。

启动 JBoss EAP 作为单机服务器
$ EAP_HOME/bin/standalone.sh
注意

对于 Windows Server,请使用 EAP_HOME\bin\standalone.bat 脚本。

此启动脚本使用 EAP_HOME/bin/standalone.conf 文件或 standalone.conf.bat 用于 Windows Server 来设置一些默认首选项,如 JVM 选项。您可以自定义此文件中的设置。

JBoss EAP 默认使用 standalone.xml 配置文件,但可使用其他配置文件启动。有关可用独立配置文件以及如何使用它们的详情,请查看单机服务器配置文件部分

有关所有可用启动脚本参数及其目的的完整列表,请使用 --help 参数或查看 服务器运行时参数 部分。

在受管域中启动 JBoss EAP

域控制器必须在域中任何服务器组的服务器之前启动。使用此脚本首先启动域控制器,然后为每个关联的主机控制器启动。

$ EAP_HOME/bin/domain.sh
注意

对于 Windows Server,请使用 EAP_HOME\bin\domain.bat 脚本。

此启动脚本使用 EAP_HOME/bin/domain.conf 文件或 domain.conf.bat 作为 Windows Server 来设置一些默认首选项,如 JVM 选项。您可以自定义此文件中的设置。

JBoss EAP 默认使用 host.xml 主机配置文件,但可使用其他文件启动。有关可用的受管域配置文件和使用方法的详细信息,请参阅受管域配置文件部分

在设置受管域时,需要将其他参数传递到启动脚本。有关所有可用启动脚本参数及其目的的完整列表,请使用 --help 参数或查看 服务器运行时参数 部分。

2.2. 停止 JBoss EAP

停止 JBoss EAP 的方式取决于它的启动方式。

停止 JBoss EAP 的交互实例

在启动 JBoss EAP 的终端中按 Ctrl+C

停止 JBoss EAP 的后台实例

使用管理 CLI 连接正在运行的实例并关闭服务器。

  1. 启动管理 CLI。

    $ EAP_HOME/bin/jboss-cli.sh --connect
  2. 发出 shutdown 命令。

    shutdown
注意

在受管域中运行时,您必须通过将 --host 参数与 shutdown 命令搭配使用来指定要关闭的主机名。

2.3. 在仅限管理员模式中运行 JBoss EAP

JBoss EAP 能够以仅限管理员模式启动。这使得 JBoss EAP 能够运行和接受管理请求,但不启动其他运行时服务或接受最终用户请求。仅管理模式可用于单机服务器和 受管域。

在仅限管理员模式中运行单机服务器
以管理员模式启动服务器

要在仅管理员模式下启动 JBoss EAP 实例,请在启动 JBoss EAP 实例时使用 --start-mode=admin-only runtime 参数。

$ EAP_HOME/bin/standalone.sh --start-mode=admin-only
检查服务器是否在仅限管理员模式下运行

使用以下命令检查服务器的运行模式:如果服务器以管理员模式运行,则结果为 ADMIN_ONLY

:read-attribute(name=running-mode)
{
  "outcome" => "success",
  "result" => "ADMIN_ONLY"
}
注意

此外,您可以使用以下命令检查启动 JBoss EAP 的初始运行模式:

/core-service=server-environment:read-attribute(name=initial-running-mode)
从管理 CLI 以不同模式重新加载

除了停止和启动具有其他运行时交换机的 JBoss EAP 实例外,也可使用管理 CLI 以不同模式重新加载它。

以仅限管理员模式重新载入服务器:

reload --start-mode=admin-only

以正常模式重新载入服务器:

reload --start-mode=normal

请注意,如果服务器是以 admin-only 模式启动且没有为 重新加载 命令指定 --start-mode 参数,那么服务器将以正常模式启动。

在仅限管理员模式中运行受管域

在受管域中,如果域控制器以管理员模式启动,它将不接受来自从属主机控制器的传入连接。

以管理员模式启动主机控制器

传递 --admin-only runtime 参数,以仅 admin 模式启动主机控制器。

$ EAP_HOME/bin/domain.sh --admin-only
检查主机控制器是否在仅限管理员模式下运行

使用以下命令,检查主机控制器的运行模式:如果主机控制器以管理员模式运行,则结果为 ADMIN_ONLY

/host=HOST_NAME:read-attribute(name=running-mode)
{
  "outcome" => "success",
  "result" => "ADMIN_ONLY"
}
从管理 CLI 以不同模式重新加载

除了停止和启动具有其他运行时交换机的主机控制器外,也可使用管理 CLI 以其他模式重新加载它。

以仅限管理员模式重新载入主机控制器:

reload --host=HOST_NAME --admin-only=true

以正常模式重新载入主机控制器:

reload --host=HOST_NAME --admin-only=false

请注意,如果主机控制器是以 admin-only 模式启动且没有为 重新加载 命令指定 --admin-only 参数,则主机控制器将以正常模式启动。

2.4. 正常暂停和关闭 JBoss EAP

JBoss EAP 可以被暂停或正常关闭。这允许活动请求正常完成,而不接受任何新请求。超时值指定暂停或关机操作将等待活跃请求完成的时间。服务器暂停时,仍然处理管理请求。

安全关闭在服务器范围内协调,主要关注请求进入服务器的入口点。以下子系统支持安全关闭:

Undertow
undertow 子系统将等待所有请求完成。
mod_cluster
modcluster 子系统将通知负载平衡器,服务器正在 PRE_SUSPEND 阶段暂停。
EJB
ejb3 子系统将等待所有远程 EJB 请求和 MDB 消息发送完成。在 PRE_SUSPEND 阶段停止发送到 MDB。EJB 定时器会被暂停,在服务器恢复时将激活错过的计时器。
事务

暂停后,服务器将不会接受新请求,但内点事务和请求可以继续,直到它们完成或超时后过期。这也适用于与 XTS 事务关联的 Web 服务请求。

注意

默认情况下,对于 ejb 子系统禁用事务安全关闭。如果您希望服务器在暂停前等待 EJB 相关的事务完成,则必须启用事务正常关闭。例如:

/subsystem=ejb3:write-attribute(name=enable-graceful-txn-shutdown,value=true)
EE 一致性

服务器将等待所有活动任务完成。将跳过所有排队的作业。目前,由于 EE Concurrency 没有持久性,被跳过的排队作业将丢失。

服务器处于暂停状态时,计划的任务将继续在计划的时间执行,但会抛出 java.lang.IllegalStateException。服务器恢复后,计划的任务将继续正常执行,而且在大多数情况下,不需要重新排期任务。

batch
服务器将在超时时间内停止所有运行的作业,并延迟所有计划的作业。
注意

目前正常关闭不会拒绝新的入站 JMS 消息。目前允许继续执行由 in-light 活动调度的 EE 批处理作业和 EE 并发任务;但是,提交的 EE 并发任务会在执行时传递超时窗口。

请求由 request-controller 子系统跟踪。如果没有此子系统,则暂停和恢复功能会受到限制,并且服务器不会在暂停或关闭前等待请求完成;但是,如果您不需要此功能,则可移除 request-controller 子系统以提高小的性能。

2.4.1. 挂起服务器

JBoss EAP 7 引入了暂停模式,可正常暂停服务器操作。这允许所有活动的请求正常完成,但不接受任何新请求。服务器暂停后,可以关机,返回到运行中状态,或保持暂停状态以执行维护。

注意

暂停服务器不会影响到管理接口。

可以使用管理控制台或管理 CLI 暂停和恢复服务器。

检查 Server Suspend 状态

可以通过下列管理 CLI 命令查看服务器暂停状态:生成的值为 RUNNINGPRE_SUSPEND、SUSPEND ING 或 SUS PENDED 之一。

  • 检查单机服务器的暂停状态。

    :read-attribute(name=suspend-state)
  • 检查受管域中服务器的暂停状态。

    /host=master/server=server-one:read-attribute(name=suspend-state)
suspend

使用以下管理 CLI 命令,通过指定超时值(以秒为单位)暂停服务器,以便服务器等待活动请求完成:默认值为 0,它会立即暂停。值为 -1 将导致服务器无限期等待所有活动的请求完成。

每个示例最多等待 60 秒以请求完成,然后再暂停。

  • 暂停单机服务器.

    :suspend(suspend-timeout=60)
  • 暂停受管域中的所有服务器。

    :suspend-servers(suspend-timeout=60)
  • 在受管域中暂停一台服务器。

    /host=master/server-config=server-one:suspend(suspend-timeout=60)
  • 暂停服务器组中的所有服务器。

    /server-group=main-server-group:suspend-servers(suspend-timeout=60)
  • 在主机级别暂停所有服务器。

    /host=master:suspend-servers(suspend-timeout=60)
恢复

restore 命令将服务器返回到正常运行状态,以接受新请求。您可以在主机、服务器、服务器组或域级别启动 命令。例如:

:resume
在 Suspended State 中启动 Server

您可以启动处于暂停状态的服务器,以便在服务器恢复之前不会接受任何请求。

  • 若要以暂停状态启动单机服务器,可在启动 JBoss EAP 实例时使用 --start-mode=suspend 运行时参数。

    $ EAP_HOME/bin/standalone.sh --start-mode=suspend
  • 若要启动处于暂停状态的受管域服务器,可将 start-mode=suspend 参数传递到管理 CLI 命令中的 启动 操作。

    /host=HOST_NAME/server-config=SERVER_NAME:start(start-mode=suspend)
    注意

    您还可以将 start-mode 参数传递到服务器的 重新加载重新启动 操作。

  • 若要启动受管域服务器组中处于暂停状态的所有服务器,可将 start-mode=suspend 参数传递到管理 CLI 命令中的 start-servers 操作:

    /server-group=SERVER_GROUP_NAME:start-servers(start-mode=suspend)
    注意

    您还可以将 start-mode 参数传递到 reload-serversrestart-servers 操作,供服务器组使用。

2.4.2. 使用管理 CLI 正常关闭服务器

如果在停止服务器时指定了适当的超时值,则会安全地关闭服务器。发出 命令后,服务器将被暂停,并将等待所有请求的指定超时完成,然后再关机。

使用以下管理 CLI 命令,安全地关闭服务器:指定服务器的超时值(以秒为单位),以便服务器等待活跃请求完成。默认值为 0,它将立即关闭服务器。值为 -1 将导致服务器无限期等待所有活动的请求完成,然后再关机。

每个示例最多等待 60 秒以请求完成,然后关机。

  • 正常关闭单机服务器。

    shutdown --suspend-timeout=60
  • 正常停止受管域中的所有服务器。

    :stop-servers(suspend-timeout=60)
  • 正常停止受管域中的一台服务器。

    /host=master/server-config=server-one:stop(suspend-timeout=60)
  • 正常停止服务器组中的所有服务器。

    /server-group=main-server-group:stop-servers(suspend-timeout=60)
  • 关闭主机控制器及其管理的所有服务器。

    /host=master:shutdown(suspend-timeout=60)
    注意

    suspend-timeout 属性仅应用到主机控制器管理的服务器,而不应用到主机控制器本身。

2.4.3. 使用 OS 信号正常关闭服务器

可以通过发送 OS TERM 信号 (如 kill -15 PID )来安全地关闭服务器。默认情况下,这个值与管理 CLI 的 shutdown --suspend-timeout=0 命令相同,从而导致任何当前处理请求立即终止。超时可以通过 org.wildfly.sigterm.suspend.timeout 系统属性进行配置,这表示服务器关闭之前等待请求完成的最大秒数。值 -1 表示服务器将无限期等待。

重要

在受管域中,不应使用 OS 信号来关闭服务器。取而代之,应当使用管理 CLI 和管理主机控制器来关闭服务器

如果使用 OS 信号正常关机,如果 JVM 配置为禁用信号处理,例如 -Xrs java 参数已传递到 JVM 选项,或者发送的信号不是进程可以响应的信号,例如发送 KILL 信号 时,则不会起作用。

2.5. 启动和停止 JBoss EAP(RPM 安装)

与 ZIP 或安装程序安装相比,启动和停止 JBoss EAP 对于 RPM 安装不同。

2.5.1. 启动 JBoss EAP(RPM 安装)

启动 JBoss EAP RPM 安装的命令取决于您要启动的操作模式、单机服务器或受管域,以及您正在运行的红帽企业 Linux 版本。

启动 JBoss EAP 作为单机服务器(RPM 安装)
  • Red Hat Enterprise Linux 6:

    $ service eap7-standalone start
  • Red Hat Enterprise Linux 7 及更新的版本:

    $ systemctl start eap7-standalone.service

默认情况下,此操作将使用 standalone.xml 配置文件启动 JBoss EAP。您可以通过在 RPM 服务配置文件中设置属性,使用不同的单机服务器配置文件启动 JBoss EAP。如需更多信息,请参阅以下 Configure RPM Service Properties 部分。

在受管域中启动 JBoss EAP(RPM 安装)
  • Red Hat Enterprise Linux 6:

    $ service eap7-domain start
  • Red Hat Enterprise Linux 7 及更新的版本:

    $ systemctl start eap7-domain.service

默认情况下,此操作将使用 host.xml 配置文件启动 JBoss EAP。您可以通过在 RPM 服务配置文件中设置属性,使用不同的受管域配置文件启动 JBoss EAP。如需更多信息,请参阅以下 Configure RPM Service Properties 部分。

配置 RPM 服务属性

本节介绍如何为您的 JBoss EAP 安装配置 RPM 服务属性和其他启动选项。请注意,建议在进行修改前备份您的配置文件。

有关 RPM 安装的所有可用启动选项列表,请参阅 RPM 服务配置属性部分

重要

对于 Red Hat Enterprise Linux 7 及更新的版本,使用 systemd 加载 RPM 服务配置文件,因此不会扩展变量表达式。

  • 指定服务器配置文件。

    启动单机服务器时,默认情况下将使用 standalone.xml 文件。在受管域中运行时,默认情况下将使用 host.xml 文件。您可以通过在相应的 RPM 配置文件中设置 WILDFLY_SERVER_CONFIG 属性来使用其他配置文件启动 JBoss EAP,eap7-standalone.conf

    WILDFLY_SERVER_CONFIG=standalone-full.xml
  • 绑定到特定的 IP 地址。

    默认情况下,JBoss EAP RPM 安装绑定到 0.0.0.0。您可以通过在适当的 RPM 配置文件中 设置 WILDFLY_BIND 属性,将 JBoss EAP 绑定到特定的 IP 地址,如 eap7-standalone.conf

    WILDFLY_BIND=192.168.0.1
    注意

    如果要将管理接口绑定到特定的 IP 地址,可以在 JBoss EAP 启动配置文件中进行配置,如下一个示例所示。

  • 设置 JVM 选项或 Java 属性.

    您可以通过编辑 启动配置文件,指定要传递给 JBoss EAP 启动脚本的 JVM 选项或 Java 属性。此文件是单机服务器的 EAP_HOME/bin/standalone.conf,或用于受管域的 EAP_HOME/bin/domain.conf。以下示例配置了堆大小,并将 JBoss EAP 管理接口绑定到 IP 地址。

    JAVA_OPTS="$JAVA_OPTS -Xms2048m -Xmx2048m"
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address.management=192.168.0.1"
    注意

    如果需要,必须使用 WILDFLY_BIND 属性来配置 JBoss EAP 绑定地址,而不在此处使用 jboss.bind.address 标准属性。

注意

如果在 RPM 服务配置文件中具有相同的名称(如 /etc/sysconfig/eap7-standalone ),并且在 JBoss EAP 启动配置文件中,如 EAP_HOME/bin/standalone.conf,则优先的值就是 JBoss EAP 启动配置文件中的值。个这样的属性是 JAVA_HOME

2.5.2. 停止 JBoss EAP(RPM 安装)

用于停止 JBoss EAP RPM 安装的命令取决于启动的运营模式、单机服务器或受管域,以及您正在运行的红帽企业 Linux 版本。

停止 JBoss EAP 作为单机服务器(RPM 安装)
  • Red Hat Enterprise Linux 6:

    $ service eap7-standalone stop
  • Red Hat Enterprise Linux 7 及更新的版本:

    $ systemctl stop eap7-standalone.service
在受管域中停止 JBoss EAP(RPM 安装)
  • Red Hat Enterprise Linux 6:

    $ service eap7-domain stop
  • Red Hat Enterprise Linux 7 及更新的版本:

    $ systemctl stop eap7-domain.service

有关 RPM 安装的所有可用启动选项列表,请参阅 RPM 服务配置文件 部分。

2.6. PowerShell 脚本(Windows 服务器)

重要

PowerShell 脚本的集合仅作为技术预览提供。技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

JBoss EAP 包含与大多数 JBoss EAP 管理脚本等效的 PowerShell 脚本。这包括在 Microsoft Windows Server 上启动 JBoss EAP 的 PowerShell 脚本。

JBoss EAP PowerShell 脚本设计为能与 PowerShell 版本 2 一起使用,并在经过测试的 Windows Server 版本上运行。

JBoss EAP PowerShell 脚本位于 EAP_HOME\bin 中,其使用方式与 JBoss EAP 批处理脚本基本相同。

例如,要启动带有 standalone-full.xml 配置文件的独立 JBoss EAP 服务器,请使用以下 PowerShell 命令:

.\standalone.ps1 "-c=standalone-full.xml"
注意

JBoss EAP PowerShell 脚本的参数必须放在引号内。

第 3 章 JBoss EAP 管理

JBoss EAP 使用简化的配置,每个单机服务器或受管域有一个配置文件。单机服务器的默认配置存储在 EAP_HOME/standalone/configuration/standalone.xml 文件中,受管域的默认配置则存储在 EAP_HOME/domain/configuration/domain.xml 文件中。此外,主机控制器的默认配置存储在 EAP_HOME/domain/configuration/host.xml 文件中。

可以使用命令行管理 CLI、基于 Web 的管理控制台、Java API 或 HTTP API 来配置 JBoss EAP。使用这些管理接口所做的更改将自动保留,并且管理 API 将覆盖 XML 配置文件。管理 CLI 和管理控制台是首选的方法,不建议手动编辑 XML 配置文件。

3.1. 关于子系统、扩展和配置文件

在不同的子系统中配置 JBoss EAP 功能的不同方面。例如,应用和服务器日志记录在 logging 子系统中配置。

扩展是扩展服务器核心功能的模块。扩展会根据部署需要加载,并在不再需要时卸载。有关如何添加 和删除扩展的信息,请参阅 JBoss EAP 管理 CLI 指南

子系统提供特定扩展的配置选项。如需有关可用子系统的更多信息,请参阅 JBoss EAP 子系统概述。

子系统配置的集合构成一个配置文件,它配置为满足服务器的需求。单机服务器具有单个未命名的配置文件。受管域可以定义许多配置文件,供域中的服务器组使用。

使用管理控制台或管理 CLI

管理控制台和管理 CLI 均有效,受到支持的方式可以更新 JBoss EAP 实例的配置。在两者间进行选择是一个优先的问题。更喜欢使用基于 Web 的图形界面的用户应使用管理控制台。更喜欢命令行界面的人员应使用管理 CLI。

3.2. 管理用户

默认 JBoss EAP 配置提供本地身份验证,让用户可以访问本地主机上的管理 CLI,而无需身份验证。

但是,如果您要远程访问管理 CLI,则必须添加管理用户,或使用管理控制台,即使流量来自本地主机上也被视为远程访问。如果在添加管理用户之前尝试访问管理控制台,您会收到错误消息。

如果使用图形安装程序安装 JBoss EAP,则在安装过程中创建管理用户。

本指南介绍了使用 add-user 脚本对 JBoss EAP 进行简单的用户管理,此脚本可用于将新用户添加到用于开箱即用身份验证的属性文件中。

有关更高级的身份验证和授权选项,如 LDAP 或基于角色的访问控制(RBAC),请参见 JBoss EAP 安全架构的核心管理身份验证部分

3.2.1. 添加管理用户

  1. 运行 add-user 实用程序脚本并按照提示进行操作。

    $ EAP_HOME/bin/add-user.sh
    注意

    对于 Windows Server,请使用 EAP_HOME\bin\add-user.bat 脚本。

  2. ENTER,选择默认选项 a 以添加管理用户。

    此用户将添加到 ManagementRealm 中,并将获得使用管理控制台或管理控制台执行管理操作的授权。另一个选择 b 将用户添加到 ApplicationRealm 中,该应用程序用于应用程序,不提供任何特定权限。

  3. 输入所需的用户名和密码。系统将提示您确认密码。

    注意

    用户名只能以任何数字和顺序包含以下字符:

    • 字母数字字符(a-z、A-Z、0-9)
    • 短划线(-)、句点(.)、逗号(@)
    • 反斜杠(\)
    • Equals (=)

    默认情况下,JBoss EAP 允许弱密码,但会发出警告。

    有关更改此默认行为的详情,请参阅设置附加用户实用程序密码限制

  4. 输入用户所属组的逗号分隔列表。如果您不希望用户属于任何组,请按 ENTER 将它留空。
  5. 检查信息并输入 yes 进行确认。
  6. 确定此用户是否代表远程 JBoss EAP 服务器实例。对于基本管理用户,请输入 no.

    可能需要添加到 ManagementRealm 的一种用户是代表另一个 JBoss EAP 实例的用户,它必须能够进行身份验证以作为群集成员加入。如果出现这种情况,则在此提示中回答 yes,系统会为您提供一个表示用户密码的散列化机密值,该值需要添加到其他配置文件中。

也可以通过向 add-user 脚本传递参数,以非交互方式创建用户。共享系统上不建议使用此方法,因为密码将在日志和历史记录文件中可见。如需更多信息,请参阅非活动运行 Add-User 实用程序

3.2.2. 主动运行 Add-User 实用程序

您可以通过在命令行中传递参数,以非交互方式运行 add-user 脚本。必须至少提供用户名和密码。

警告

共享系统上不建议使用此方法,因为密码将在日志和历史记录文件中可见。

创建一个属于多个组的用户

以下命令添加了一个管理用户, mgmtuser1,它带有 guest and mgmtgroup 组。

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser1' -p 'password1!' -g 'guest,mgmtgroup'
指定替代属性文件

默认情况下,使用 add-user 脚本创建的用户和组信息存储在服务器配置目录中的属性文件中。

用户信息存储在以下属性文件中:

  • EAP_HOME/standalone/configuration/mgmt-users.properties
  • EAP_HOME/domain/configuration/mgmt-users.properties

组信息存储在以下属性文件中:

  • EAP_HOME/standalone/configuration/mgmt-groups.properties
  • EAP_HOME/domain/configuration/mgmt-groups.properties

这些默认目录和属性文件名可以被覆盖。以下命令添加新用户,为用户属性文件指定不同的名称和位置。

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser2' -p 'password1!' -sc '/path/to/standaloneconfig/' -dc '/path/to/domainconfig/' -up 'newname.properties'

新用户已添加到位于 /path/to /standaloneconfig/newname.properties/path/to /domainconfig/newname.properties 的用户属性文件中。请注意,这些文件必须已经存在,否则您将看到错误。

有关所有可用 add-user 参数及其目的的完整列表,请使用 --help 参数或参阅 Add-User 实用程序参数 部分。

3.2.3. 附加用户实用程序密码限制

可以使用 EAP_HOME/bin/add -user.properties 文件配置 add -user 实用程序脚本的密码限制。

重要

add-user.properties 文件是一个未受保护的纯文本文件,必须加以保护,以避免对其内容进行不必要的访问。

要避免设置不需要的密码,请检查键盘的系统键映射是否正确。默认系统键映射为 en-qwerty。如果更改此默认设置并创建新密码,您必须检查密码是否满足类 SimplePasswordStrengthChecker 中的条件

默认情况下,JBoss EAP 允许弱密码,但会发出警告。要拒绝不满足指定最低要求的密码,请将 password.restriction 属性设置为 REJECT

下表描述了可在 EAP_HOME/bin/add-user.properties 文件中配置的额外密码要求设置:

表 3.1. 额外密码要求设置
属性描述

minLength

密码的最少字符数.例如,password .restriction.minLength=8 将密码限制为最少 8 个字符。

strength

设置密码必须满足的阈值才有效。有效的阈值条目包括:

* VERY_WEAK

*

* 中等

* 中

* 强

* VERY_STRONG

* 例外

默认值为 MODERATE。定义了阈值,并且定义了类 SimplePasswordStrengthChecker 中指定的默认值。

注意:如果您没有指定阈值,MODE RATE 将成为默认值。这个值在类 SimplePasswordStrengthChecker 中指定。

minAlpha

为密码设置的最少字母字符数。例如,password.restriction.minAlpha=1 将密码限制为至少包含一个字母字符。

minDigit

为密码设置的最小数字字符数.例如,password.restriction.minDigit=1 将密码限制为至少包含一个数字字符。

minSymbol

为密码设置的最少符号数。例如,password.restriction.minSymbol=1 将密码限制为至少包含一个符号。

forbiddenValue

限制用户设置易于确定的密码,如 root。例如,password .restriction.forbidden=root、admin、administrators 限制 设置 root、admin admin 作为密码。

mustNotMatchUsername

限制用户将其用户名设置为密码。例如,password.restriction.mustNotMatchUsername=TRUE 限制用户将其用户名设置为密码。如果设置为 false,则忽略此规则。

3.2.4. 更新管理用户

您可以使用 add-user 实用程序脚本在提示时输入用户名来更新现有管理用户的设置。

$ EAP_HOME/bin/add-user.sh

What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): a

Enter the details of the new user to add.
Using realm 'ManagementRealm' as discovered from the existing property files.
Username : test-user
User 'test-user' already exists and is enabled, would you like to...
 a) Update the existing user password and roles
 b) Disable the existing user
 c) Type a new username
(a):

当您输入已存在的用户名时,会显示几个选项:

  • 键入 a 以更新现有用户的密码。
  • 键入 b 以禁用现有用户。
  • c 键输入新用户名。
警告

以非交互方式使用 add-user 脚本更新用户时,用户会自动更新,无需确认提示。

3.3. 优化 JBoss EAP 服务器配置

安装 JBoss EAP 服务器并且 创建了管理用户后,红帽建议您优化服务器配置。

确保查看《性能调优指南》中的信息,了解如何优化服务器配置,以避免在生产环境中部署应用程序时出现常见问题。常见的优化包括设置 ulimits、启用垃圾回收、创建 Java 堆转储 ,以及调整线程池大小

最好为产品发布应用任何现有的补丁。EAP 的每个补丁都包含大量漏洞修复。如需更多信息,请参阅 JBoss EAP 的补丁和升级指南中的 JBoss EAP 补丁和升级指南

3.4. 管理接口

3.4.1. 管理 CLI

管理命令行界面(CLI)是 JBoss EAP 的命令行管理工具。

使用管理 CLI 启动和停止服务器、部署和取消部署应用、配置系统设置,以及执行其他管理任务。操作可以在批处理模式下执行,允许以组形式运行多个任务。

许多常见的终端命令可用,如 lscdpwd。管理 CLI 也支持 tab 自动完成功能。

有关使用管理 CLI 的详细信息,包括命令和操作、语法以及批处理模式下运行,请参阅 JBoss EAP管理 CLI 指南

启动管理 CLI
$ EAP_HOME/bin/jboss-cli.sh
注意

对于 Windows Server,请使用 EAP_HOME\bin\jboss-cli.bat 脚本。

连接到正在运行的服务器
connect

或者,您可以使用 EAP_HOME/bin/jboss-cli.sh --connect 命令启动管理 CLI 并在一个步骤中进行连接。

显示帮助

使用以下命令获取一般帮助:

help

在命令中使用 --help 标志,以接收有关 使用该特定命令的说明。例如,若要使用 deploy 接收关于 的信息,请执行以下命令:

deploy --help
退出管理 CLI
quit
查看系统设置

以下命令使用 read-attribute 操作来显示是否启用了示例数据源:

/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
{
    "outcome" => "success",
    "result" => true
}

在受管域中运行时,您必须通过 /profile=PROFILE_NAME 命令指定要更新的配置集。

/profile=default/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
更新系统设置

以下命令使用 write-attribute 操作来禁用示例数据源。

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=false)
启动服务器

管理 CLI 也可用于在受管域中运行时启动和停止服务器。

/host=HOST_NAME/server-config=server-one:start

3.4.2. 管理控制台

管理控制台是用于 JBoss EAP 的基于 Web 的管理工具。

使用管理控制台启动和停止服务器、部署和取消部署应用、调优系统设置,以及对服务器配置进行持续修改。管理控制台还具备执行管理任务的功能,当当前用户执行的任何更改都要求重新启动或重新加载服务器实例时,实时通知功能。

在受管域中,可以从域控制器的管理控制台集中管理同一域中的服务器实例和服务器组。

对于使用默认管理端口在本地主机上运行的 JBoss EAP 实例,可通过位于 http://localhost:9990/console/index.html 的 Web 浏览器访问管理控制台。您将需要使用具有访问管理控制台权限的用户进行身份验证。

管理控制台提供下列选项卡,用于浏览和管理 JBoss EAP 单机服务器或受管域。

Home
了解如何完成几个常见配置和管理任务。参加导览,熟悉 JBoss EAP 管理控制台。
部署
添加、移除和启用部署。在受管域中,将部署分配到服务器组。
Configuration
配置可用的子系统,提供 Web 服务、消息传递或高可用性等功能。在受管域中,管理包含不同子系统配置的配置文件。
Runtime
查看运行时信息,如服务器状态、JVM 使用量和服务器日志。在受管域中,管理您的主机、服务器组和服务器。
patching
将补丁应用到您的 JBoss EAP 实例。
访问控制
在使用基于角色的访问控制时,将角色分配给用户和组。
3.4.2.1. 在管理控制台中更新属性

导航到管理控制台中相应部分以用于要修改的资源后,只要您拥有适当的权限,即可编辑其属性。

  1. 单击编辑链接
  2. 进行所需的更改。

    必填字段标有星号(*)。您可以通过单击 Help 链接来查看属性描述。

    注意

    根据属性类型,输入字段可以是文本字段、ON/OFF 字段,或者下拉字段。在某些文本字段中,正如您键入的,配置的其他位置中的值可能显示为建议。

  3. 单击 Save 以保存更改
  4. 如有必要,重新加载服务器以使更改生效。

    保存需要重新加载才能生效的更改时会出现弹出窗口。若要重新加载单机服务器,可在弹出窗口中单击 Reload 链接。若要重新加载受管域中的服务器,可单击 Topology 链接,选择相应的服务器,然后单击 Reload 下拉列表

要查看您最近执行的配置操作的历史记录,请单击管理控制台右上角的通知图标。

3.4.2.2. 启用/禁用管理控制台

您可以通过设置 /core-service=management/management -interface=http-interface=http-interface=http-interface=http-interface 属性来启用或禁用管理控制台。对于域模式中的 master 主机,请使用 /host=master/core-service=management/management-interface=http-interface

例如,要启用:

/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=true)

例如,要禁用:

/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=false)
3.4.2.3. 更改管理控制台的语言

默认情况下,管理控制台的语言设置为英文。您可以选择使用以下语言之一:

  • 德语(de)
  • 简体中文(zh-Hans)
  • 巴西葡萄牙语(pt-BR)
  • 法语(fr)
  • 西班牙语(es)
  • 日语(Jab)
更改管理控制台的语言
  1. 登录管理控制台。
  2. 单击管理控制台右下角的 Settings 链接。
  3. Locale 选择框中选择所需的语言。
  4. 选择 Save。确认框通知您需要重新加载应用。
  5. 单击 Yes。系统会自动刷新 Web 浏览器以使用所选区域设置。
3.4.2.4. 自定义管理控制台标题

您可以自定义管理控制台标题,以便快速识别每个 JBoss EAP 实例。

自定义管理控制台标题:

  1. 登录管理控制台。
  2. 单击管理控制台右下角的 Settings
  3. Settings 窗口中,修改标题字段中的标题
  4. Save

    确认框通知您必须重新加载管理控制台。

  5. 单击 Yes

    系统会自动刷新 Web 浏览器,新的标题会显示在标签页标头中。

3.5. 管理 API

3.5.1. HTTP API

HTTP API 端点是管理客户端的入口点,它依赖于 HTTP 协议与 JBoss EAP 管理层集成。

HTTP API 由 JBoss EAP 管理控制台使用,但也为其他客户端提供集成功能。默认情况下,HTTP API 可通过 http://HOST_NAME: 9990/management 访问。此 URL 将显示公开给 API 的原始属性和值。

读取资源

虽然您可以使用 HTTP POST 方法读取、写入或执行其他操作,但您可以使用 GET 请求 来执行一些读取操作。HTTP GET 方法使用以下 URL 格式:

http://HOST_NAME:9990/management/PATH_TO_RESOURCE?operation=OPERATION&PARAMETER=VALUE

务必将所有可替换值替换为适合您的请求的值。以下值是 OPERATION 可替换 的可用选项:

描述

attribute

执行 读-attribute 操作。

operation-description

执行 read-operation-description 操作。

operation-names

执行 read-operation-names 操作。

resource

执行 read-resource 操作。

resource-description

执行 read-resource-description 操作。

快照

执行 list-snapshots 操作。

以下示例 URL 演示了如何使用 HTTP API 执行读取操作。

示例:阅读资源的所有属性和值

http://HOST_NAME:9990/management/subsystem/undertow/server/default-server/http-listener/default

这将显示 默认 HTTP 侦听器的所有属性及其值。

注意

默认操作为 read-resource

示例:阅读资源属性的值

http://HOST_NAME:9990/management/subsystem/datasources/data-source/ExampleDS?operation=attribute&name=enabled

这会读取 ExampleDS 数据源的 enabled 属性的值。

更新资源

您可以使用 HTTP POST 方法更新配置值或使用 HTTP API 执行其他操作。您必须为这些操作提供身份验证。

以下示例演示了如何使用 HTTP API 更新资源。

示例:更新资源的属性值

$ curl --digest http://HOST_NAME:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"write-attribute", "address":["subsystem","datasources","data-source","ExampleDS"], "name":"enabled", "value":"false", "json.pretty":"1"}'

这会将 ExampleDS 数据源的 enabled 属性值更新为 false

示例:把操作到服务器

$ curl --digest http://localhost:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"reload"}'

这将重新加载服务器。

如需有关如何使用 HTTP API 部署应用程序到 JBoss EAP 的信息,请参阅使用 HTTP API 部署应用

3.5.2. 原生 API

原生 API 端点是管理客户端的入口点,它依赖于原生协议与 JBoss EAP 管理层集成。原生 API 由 JBoss EAP 管理 CLI 使用,但也为其他客户端提供集成功能。

以下 Java 代码演示了如何使用原生 API 从 Java 代码执行管理操作的示例。

注意

您必须将 EAP_HOME/bin/client/jboss-cli-client.jar 文件中所需的 JBoss EAP 库添加到您的类路径中。

示例:使用原生 API 读取资源

// Create the management client
ModelControllerClient client = ModelControllerClient.Factory.create("localhost", 9990);

// Create the operation request
ModelNode op = new ModelNode();

// Set the operation
op.get("operation").set("read-resource");

// Set the address
ModelNode address = op.get("address");
address.add("subsystem", "undertow");
address.add("server", "default-server");
address.add("http-listener", "default");

// Execute the operation and manipulate the result
ModelNode returnVal = client.execute(op);
System.out.println("Outcome: " + returnVal.get("outcome").toString());
System.out.println("Result: " + returnVal.get("result").toString());

// Close the client
client.close();

3.6. 配置数据

3.6.1. 独立服务器配置文件

独立配置文件位于 EAP_HOME/standalone/configuration/ 目录中。每个预定义配置文件(默认为 hafull、full-ha负载平衡器)均存在单独的 文件。

表 3.2. 独立配置文件
配置文件用途

standalone.xml

此独立配置文件是启动单机服务器时使用的默认配置。它包含有关服务器的所有信息,包括子系统、网络、部署、套接字绑定和其他可配置的详细信息。它不提供消息传递或高可用性所需的子系统。

standalone-ha.xml

此单机配置文件包含所有默认子系统,并添加 modclusterjgroups 子系统,以实现高可用性。它不提供消息传递所需的子系统。

standalone-full.xml

此单机配置文件包含所有默认子系统,并添加 messaging-activemqiiop-openjdk 子系统。它不提供高可用性所需的子系统。

standalone-full-ha.xml

此独立配置文件包括对每一种可能子系统的支持,包括消息传递和高可用性方面的支持。

standalone-load-balancer.xml

此单机配置文件包含使用内置 mod_cluster 前端负载平衡器对其他 JBoss EAP 实例进行负载平衡所需的最小子系统。

默认情况下,将 JBoss EAP 作为单机服务器启动使用 standalone.xml 文件。若要使用其他配置启动 JBoss EAP,可使用 --server-config 参数:例如,

$ EAP_HOME/bin/standalone.sh --server-config=standalone-full.xml

3.6.2. 受管域配置文件

受管域配置文件位于 EAP_HOME/domain/configuration/ 目录中。

表 3.3. 受管域配置文件
配置文件用途

domain.xml

这是受管域的主配置文件。只有域 master 会读取此文件。此文件包含所有配置文件的配置(默认为 ha、full、full-ha、load-balancer )。

host.xml

此文件包含特定于受管域中物理主机的配置详细信息,如网络接口、套接字绑定、主机名称和其他特定于主机的详细信息。host.xml 文件包含 host-master.xmlhost-slave.xml 的所有功能,如下所述。

host-master.xml

此文件仅包含将服务器作为主域控制器运行所需的配置详细信息。

host-slave.xml

此文件仅包含作为受管域主机控制器运行服务器所需的配置详细信息。

默认情况下,在受管域中启动 JBoss EAP 将使用 host.xml 文件。若要使用其他配置启动 JBoss EAP,可使用 --host-config 参数:例如,

$ EAP_HOME/bin/domain.sh --host-config=host-master.xml

3.6.3. 备份配置数据

为了稍后恢复 JBoss EAP 服务器配置,应备份以下位置中的项目:

  • EAP_HOME/standalone/configuration/

    • 备份整个目录,以保存单机服务器的用户数据、服务器配置和日志记录设置。
  • EAP_HOME/domain/configuration/

    • 备份整个目录,以保存用户和配置文件数据、域和主机配置,以及受管域的日志记录设置。
  • EAP_HOME/modules/

    • 备份任何自定义模块。
  • EAP_HOME/welcome-content/

    • 备份任何自定义欢迎内容。
  • EAP_HOME/bin/

    • 备份任何自定义脚本或启动配置文件。

3.6.4. 配置文件快照

为了协助服务器维护和管理,JBoss EAP 在启动时创建原始配置文件的时间戳版本。管理操作的任何其他配置更改将导致自动备份原始文件,保留实例的工作副本供引用和回滚。此外,还可以生成配置快照,它们是当前服务器配置的即时副本。这些快照可由管理员保存和加载。

以下示例使用 standalone.xml 文件,但同一进程适用于 domain.xmlhost.xml 文件。

拍摄快照

使用管理 CLI 为当前配置生成快照。

:take-snapshot
{
    "outcome" => "success",
    "result" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20151022-133109702standalone.xml"
}
列出快照

使用管理 CLI 列出已执行的所有快照。

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
        "names" => [
            "20151022-133109702standalone.xml",
            "20151022-132715958standalone.xml"
        ]
    }
}
删除快照

使用管理 CLI 删除快照。

:delete-snapshot(name=20151022-133109702standalone.xml)
使用快照启动服务器

可以使用快照或自动保存的配置启动服务器。

  1. 导航到 EAP_HOME/standalone/configuration/standalone_xml_history 目录,再识别要加载的快照或保存的配置文件。
  2. 启动服务器并指向所选配置文件。传递与配置目录相关的文件路径 EAP_HOME/standalone/configuration/

    $ EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/snapshot/20151022-133109702standalone.xml
注意

在受管域中运行时,请使用 --host-config 参数来指定配置文件。

3.6.5. 查看配置更改

JBoss EAP 7 提供了跟踪对运行系统进行的配置更改的功能。这样,管理员可以查看其他授权用户所做的配置更改历史记录。

重要

更改存储在内存中,不会在服务器重新启动之间保留。此功能不能取代管理审计日志记录

您可以从管理 CLI 或管理控制台启用跟踪和查看配置更改

通过管理 CLI 跟踪和查看配置更改

若要启用跟踪配置更改,可使用以下管理 CLI 命令:您可以使用 max-history 属性指定要存储的条目数量。

/subsystem=core-management/service=configuration-changes:add(max-history=20)
注意

在受管域中,配置更改在主机级别上跟踪,以进行主机和服务器相关的修改。为主机控制器启用配置更改可为其所有受管服务器启用它。您可以使用以下命令跟踪每个主机的配置更改:

/host=HOST_NAME/subsystem=core-management/service=configuration-changes:add(max-history=20)

要查看最近的配置更改列表,请使用以下管理 CLI 命令:

/subsystem=core-management/service=configuration-changes:list-changes
注意

在受管域中,您可以使用以下命令列出主机的配置更改:

/host=HOST_NAME/subsystem=core-management/service=configuration-changes:list-changes

您可以使用以下命令列出影响特定服务器的配置更改:

/host=HOST_NAME/server=SERVER_NAME/subsystem=core-management/service=configuration-changes:list-changes

这会列出所做的每个配置更改,包括日期、来源、结果和操作详情。例如,以下 list-changes 命令的输出显示配置更改,最近显示的第一个显示为第一个。

{
    "outcome" => "success",
    "result" => [
        {
            "operation-date" => "2016-02-12T18:37:00.354Z",
            "access-mechanism" => "NATIVE",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "address" => [],
                "operation" => "reload",
                "operation-headers" => {
                    "caller-type" => "user",
                    "access-mechanism" => "NATIVE"
                }
            }]
        },
        {
            "operation-date" => "2016-02-12T18:34:16.859Z",
            "access-mechanism" => "NATIVE",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "address" => [
                    ("subsystem" => "datasources"),
                    ("data-source" => "ExampleDS")
                ],
                "operation" => "write-attribute",
                "name" => "enabled",
                "value" => false,
                "operation-headers" => {
                    "caller-type" => "user",
                    "access-mechanism" => "NATIVE"
                }
            }]
        },
        {
            "operation-date" => "2016-02-12T18:24:11.670Z",
            "access-mechanism" => "HTTP",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "operation" => "remove",
                "address" => [
                    ("subsystem" => "messaging-activemq"),
                    ("server" => "default"),
                    ("jms-queue" => "ExpiryQueue")
                ],
                "operation-headers" => {"access-mechanism" => "HTTP"}
            }]
        }
    ]
}

这个示例列出了影响配置的三个操作详情:

  • 从管理 CLI 重新加载服务器:
  • 从管理 CLI 禁用 ExampleDS 数据源.
  • 从管理控制台 移除 ExpiryQueue 队列。
从管理控制台跟踪和查看配置更改

若要启用从管理控制台跟踪配置更改,可选择到 Runtime 选项卡,前往服务器或主机以跟踪 的更改,并从下拉菜单中选择 Configuration Changes。单击 Enable Configuration Changes,并提供最大历史记录值。

然后,此页面上的表列出进行的每个配置更改,包括日期、来源、结果和操作详情。

3.6.6. 属性替换

JBoss EAP 允许您使用表达式来定义可在配置中替换字面值的可替换属性。表达式使用 ${PARAMETER: DEFAULT_VALUE} 格式。如果设置了指定参数,则将使用参数的值。否则,将使用提供的默认值。

解析表达式支持的源包括系统属性、环境变量和密码库。对于部署,源可以是部署存档中的 META-INF/jboss.properties 文件中的属性。对于支持子部署的部署类型,如果属性文件位于外部部署中,则解析范围仅限于所有子部署,如 EAR。如果属性文件在子部署中,则解析的范围仅限于该子部署。

以下 standalone.xml 配置文件的示例将 公共 接口的 inet-address 设为 127.0.0.1,除非设置了 jboss.bind.address 参数。

<interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
</interface>

将 EAP 启动为单机服务器时,可以使用以下命令设置 jboss.bind.address 参数:

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS
嵌套表达式

表达式可以嵌套,允许更高级地使用表达式来代替固定值。嵌套表达式的格式类似于普通表达式的格式,但一个表达式被嵌入在另一个表达式中,例如:

${SYSTEM_VALUE_1${SYSTEM_VALUE_2}}

嵌套表达式是递归评估的,因此首先评估内嵌表达式 ,然后评估外部表达式。表达式也可能是递归的,其中表达式解析为其他表达式,然后解析。允许表达式的任何位置都允许嵌套表达式,但管理 CLI 命令除外。

例如,如果数据源定义中使用的密码被屏蔽,则可以使用嵌套表达式。数据源的配置可能包含以下行:

<password>${VAULT::ds_ExampleDS::password::1}</password>

ds_ExampleDS 的值可以替换为使用嵌套表达式的系统属性(datasource_name)。数据源的配置可以改为有以下行:

<password>${VAULT::${datasource_name}::password::1}</password>

JBoss EAP 首先评估表达式 ${datasource_name},然后将其输入到更大的表达式并评估生成的表达式。此配置的优点在于数据源的名称是从固定配置中提取的。

基于描述符的特征替换

应用程序配置(如数据源连接参数)通常会因开发、测试和生产环境而异。构建系统脚本有时可以容纳这种差异,因为 Jakarta EE 规范不包含将这些配置外部化的方法。借助 JBoss EAP,您可以使用基于描述符的属性替换在外部管理配置。

基于描述符的属性替换基于描述符的属性,允许您从应用和构建链中删除对环境相关的假设。特定环境的配置可以在部署描述符中指定,而不是注释或构建系统脚本。您可以在文件中提供配置,或者作为参数在命令行中提供。

ee 子系统中有几个标记控制是否应用属性替换。

JBoss 特定的描述符替换由 jboss-descriptor-property-replacement 标志控制,默认情况下是 启用 的。启用后,可以在以下部署描述符中替换属性:

  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml

以下管理 CLI 命令可用于启用或禁用特定于 JBoss 的描述符中的属性替换:

/subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)

Jakarta EE 描述符替换由 spec-descriptor-property-replacement 标志控制,默认为 禁用。启用后,可以在以下部署描述符中替换属性:

  • ejb-jar.xml
  • persistence.xml
  • application.xml
  • web.xml

以下管理 CLI 命令可用于在 Jakarta EE 描述符中启用或禁用属性替换:

/subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)

3.6.7. 使用 Git 管理配置数据

自 JBoss EAP 7.3 起,您可以使用 Git 来管理和持久保留您的服务器配置数据、属性文件和部署。这不仅允许您管理这些文件的版本历史记录,还允许您使用一个或多个 Git 存储库在多个服务器和节点间共享服务器和应用配置。此功能仅适用于使用默认配置目录布局的单机服务器。

您可以选择在本地 Git 存储库中使用配置数据 ,也可以从远程 Git 存储库中提取数据。Git 存储库在 jboss.server.base.dir 目录中配置,这是单机服务器内容的基础目录。在 jboss.server.base.dir 目录配置为使用 Git 后,JBoss EAP 将自动通过管理 CLI 或管理控制台提交每次更新到配置的更新。通过手动编辑配置文件在服务器外进行的任何更改都不会提交或保留,但您可以使用 Git CLI 添加和提交手动更改。您还可以使用 Git CLI 查看提交历史记录,管理分支和管理内容。

要使用此功能,在您启动服务器时在命令行中传递一个或多个参数。

表 3.4. Git 配置管理的服务器启动参数
参数描述

--git-repo

用于管理和持久服务器配置数据的 Git 存储库的位置。如果要在本地存储 或者远程存储库的 URL,这可能是本地的。

--git-branch

Git 存储库中要使用的分支或标签名称。此参数应命名现有的分支或标签名称,因为如果不存在,则不会创建该分支或标签名称。如果使用标签名称,请将存储库置于分离的 HEAD 状态,这意味着以后的提交不会附加到任何分支。标签名称为只读,通常在多个节点之间复制配置时使用。

--git-auth

指向 Elytron 配置文件的 URL,该文件包含连接远程 Git 存储库时要使用的凭据。如果您的远程 Git 存储库需要身份验证,则需要此参数。虽然 Git 支持 SSH 身份验证,但 Elytron 不支持;因此,目前只能指定要通过 HTTP 或 HTTPS 进行身份验证的凭据,而不是通过 SSH 进行身份验证。此参数不与 本地存储库 一起使用。

使用本地 Git 存储库

要使用本地 Git 存储库,请使用 --git-repo=local 参数启动服务器。您还可以在启动服务器时添加 --git-branch=GIT_BRANCH_NAME 参数,在远程存储库中指定可选分支或标签名称。此参数应命名现有的分支或标签名称,因为如果不存在,则不会 创建该分支或标签名称。如果使用标签名称,请将存储库置于分离的 HEAD 状态,这意味着以后的提交不会附加到任何分支。

以下是使用 本地存储库1.0.x 分支启动服务器的命令示例:

$ EAP_HOME/bin/standalone.sh --git-repo=local --git-branch=1.0.x

如果您使用 参数启动服务器以使用 本地 Git 存储库,JBoss EAP 将检查 jboss.server.base.dir 目录是否已针对 Git 进行了配置。否则,JBoss EAP 会利用现有配置内容在 jboss.server.base.dir 目录中创建并初始化 Git 存储库。JBoss EAP 检查由 --git-branch 参数传递的分支名称。如果未传递该参数,它将检查 master 分支。初始化后,您应该会看到单机服务器内容的基础目录中的 a .git/ 目录和 a.gitignore 文件。

使用远程 Git 存储库

要使用远程 Git 存储库,请使用 --git-repo=REMOTE_REPO 参数启动服务器。参数的值可以是您手动添加到本地 Git 配置的 URL 或远程别名。

您还可以在启动服务器时添加 --git-branch=GIT_BRANCH_NAME 参数,在远程存储库中指定可选分支或标签名称。此参数应命名现有的分支或标签名称,因为如果不存在,则不会创建该分支或标签名称。如果使用标签名称,请将存储库置于分离的 HEAD 状态,这意味着以后的提交不会附加到任何分支。

如果您的 Git 存储库需要身份验证,那么在启动服务器时,还必须添加 --git-auth=AUTH_FILE_URL 参数。此参数应当是 Elytron 配置文件的 URL,其中包含连接 Git 存储库所需的凭据。以下是可用于身份验证的 Elytron 配置文件的示例:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <authentication-client xmlns="urn:elytron:client:1.2">
    <authentication-rules>
      <rule use-configuration="test-login">
      </rule>
    </authentication-rules>
    <authentication-configurations>
      <configuration name="test-login">
        <sasl-mechanism-selector selector="BASIC" />
        <set-user-name name="eap-user" />
        <credentials>
          <clear-password password="my_api_key" />
        </credentials>
        <set-mechanism-realm name="testRealm" />
      </configuration>
    </authentication-configurations>
  </authentication-client>
</configuration>
注意

虽然 Git 支持 SSH 身份验证,但 Elytron 不支持;因此,目前只能指定要通过 HTTP 或 HTTPS 进行身份验证的凭据,而不是通过 SSH 进行身份验证。

以下是使用 full 配置文件启动服务器的命令示例,它使用远程 eap-configuration 存储库的 1.0.x 分支,并将 URL 传递到包含身份验证凭据的 Elytron 配置文件。

$ EAP_HOME/bin/standalone.sh --git-repo=https://github.com/MY_GIT_ID/eap-configuration.git --git-branch=1.0.x --git-auth=file:///home/USER_NAME/github-wildfly-config.xml --server-config=standalone-full.xml

如果您使用 参数启动服务器以使用远程 Git 存储库,JBoss EAP 会检查 jboss.server.base.dir 目录是否已针对 Git 进行了配置。否则,JBoss EAP 将删除 jboss.server.base.dir 目录中的现有配置文件,并将它们替换为远程 Git 配置数据。JBoss EAP 检查由 --git-branch 参数传递的分支名称。如果未传递该参数,它将检查 master 分支。这个过程完成后,您应该会在单机服务器内容的基础目录中看到 a .git/ 目录和 a.gitignore 文件。

警告

如果您稍后启动服务器传递与最初使用的 --git-repo URL 或 --git-branch 名称不同的服务器,您将在尝试启动服务器时看到错误消息 java.lang.RuntimeException: WFLYSRV0268: Failed to pull repository GIT_REPO_NAME。这是因为 JBoss EAP 尝试从与 jboss.server.base.dir 目录中当前配置的仓库和分支不同的存储库和分支中提取配置数据,而 Git 拉取会导致冲突。

使用 Git 时发布远程配置数据

您可以使用管理 CLI 发布配置 操作将您的 Git 存储库更改推送到远程存储库。由于当您启动服务器时,JBoss EAP 会在启动过程中从远程 Git 存储库提取配置,这允许您在多个服务器之间共享配置数据。您只能将此操作用于远程存储库。它不适用于本地存储库。

以下管理 CLI 操作将配置数据发布到远程 eap-configuration 存储库:

:publish-configuration(location="=https://github.com/MY_GIT_ID/eap-configuration.git")
{"outcome" => "success"}
通过 Git 使用快照

除了使用 Git 提交历史记录来跟踪配置更改外,您还可以生成快照以在特定时间点保留配置。您可以列出快照并删除快照。

使用 Git 时生成快照

快照作为标签存储在 Git 中。您可以在 take-snapshot 操作上将快照标签名称和提交消息指定为参数。

以下管理 CLI 操作将拍摄快照,并将其命名为"snapshot-01"标签。

:take-snapshot(name="snapshot-01", comment="1st snapshot")
{
    "outcome" => "success",
    "result" => "1st snapshot"
}
使用 Git 列出快照

您可以使用 list-snapshots 操作列出所有快照标签。

以下管理 CLI 操作列出了快照标签:

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "",
        "names" => [
            "snapshot : 1st snapshot",
            "refs/tags/snapshot-01",
            "snapshot2 : 2nd snapshot",
            "refs/tags/snapshot-02"
        ]
    }
}
使用 Git 删除快照

您可以通过在 delete-snapshot 操作上传递标签名称来删除特定的快照。

以下管理 CLI 操作将使用标签名称 "snapshot-01" 删除快照。

:delete-snapshot(name="snapshot-01")
{"outcome" => "success"}

3.7. 文件系统路径

JBoss EAP 将逻辑名称用于文件系统路径。然后,其他配置区域可以使用其逻辑名称引用路径,从而避免为每个实例使用绝对路径,并允许特定主机配置解析为通用逻辑名称。

例如,默认的 logging 子系统配置将 jboss.server.log.dir 声明为服务器日志目录的逻辑名称。

示例:服务器日志目录的相对路径示例

<file relative-to="jboss.server.log.dir" path="server.log"/>

JBoss EAP 自动提供多个标准路径,用户无需在配置文件中进行配置。

表 3.5. 标准路径
属性描述

java.home

Java 安装目录

jboss.controller.temp.dir

单机服务器和受管域的常用别名.用于临时文件存储的目录。等同于受管域中的 jboss.domain.temp.dir 和单机服务器上的 jboss.server.temp.dir

jboss.domain.base.dir

域内容的基础目录。

jboss.domain.config.dir

包含域配置的目录。

jboss.domain.data.dir

域将用于持久数据存储的目录。

jboss.domain.log.dir

域将用于持久日志文件存储的目录。

jboss.domain.temp.dir

域将用于临时文件存储的目录。

jboss.domain.deployment.dir

域将用于存储已部署内容的目录。

jboss.domain.servers.dir

域将用于存储受管域实例输出的目录。

jboss.home.dir

JBoss EAP 分发的根目录.

jboss.server.base.dir

单机服务器内容的基础目录。

jboss.server.config.dir

包含单机服务器配置的目录。

jboss.server.data.dir

单机服务器将用于持久数据存储的目录。

jboss.server.log.dir

单机服务器将用于日志文件存储的目录。

jboss.server.temp.dir

单机服务器将用于临时文件存储的目录。

jboss.server.deploy.dir

单机服务器将用于存储已部署内容的目录。

user.dir

用户的当前工作目录.

user.home

用户主目录。

您可以覆盖标准路径或 添加自定义路径

3.7.1. 查看文件系统路径

使用以下命令列出文件系统路径:

ls /path
注意

在受管域中,您可以使用以下命令列出特定服务器的文件系统路径:

ls /host=HOST_NAME/server=SERVER_NAME/path

使用以下命令来读取文件系统路径的值:

/path=PATH_NAME:read-resource
注意

在受管域中,您可以使用以下命令读取特定服务器的文件系统路径值:

/host=HOST_NAME/server=SERVER_NAME/path=PATH_NAME:read-resource

3.7.2. 覆盖标准路径

您可以覆盖以 jboss. server.* 或 jboss. domain.* 开头的标准路径的默认位置。这可以通过以下两种方式之一完成:

  • 启动服务器时传递命令行参数。例如:

    $ EAP_HOME/bin/standalone.sh -Djboss.server.log.dir=/var/log
  • 修改服务器配置文件中 standalone.conf 或 domain.conf 中的 JAVA_OPTS 变量,使其包含新位置。例如:

    JAVA_OPTS="$JAVA_OPTS -Djboss.server.log.dir=/var/log"
覆盖受管域的标准路径

在本示例中,目标是将域文件存储在 /opt/jboss_eap/domain_data 目录中,并为每个顶级目录指定一个自定义名称。使用默认目录分组 by-server

  • 日志文件存储在 all_logs 子目录中
  • 数据文件存储在 all_data 子目录中
  • 临时文件存储在 all_temp 子目录中
  • 服务器的文件存储在 all_servers 子目录中

为了实现此配置,启动 JBoss EAP 时将覆盖多个系统属性。

$ EAP_HOME/bin/domain.sh -Djboss.domain.temp.dir=/opt/jboss_eap/domain_data/all_temp -Djboss.domain.log.dir=/opt/jboss_eap/domain_data/all_logs -Djboss.domain.data.dir=/opt/jboss_eap/domain_data/all_data -Djboss.domain.servers.dir=/opt/jboss_eap/domain_data/all_servers

生成的路径结构如下:

/opt/jboss_eap/domain_data/
               ├── all_data
               ├── all_logs
               ├── all_servers
               │   ├── server-one
               │   │   ├── data
               │   │   ├── log
               │   │   └── tmp
               │   └── server-two
               │       ├── data
               │       ├── log
               │       └── tmp
               └── all_temp

3.7.3. 添加自定义路径

您可以使用管理 CLI 或管理控制台添加自定义文件系统路径。

  • 在管理 CLI 中,您可以使用以下管理 CLI 命令添加新路径:

    /path=my.custom.path:add(path=/my/custom/path)
  • 从管理控制台中,您可以通过导航到 Configuration 选项卡、选择路径并单击 View 来配置文件系统路径。在这里,您可以添加、修改和删除路径。

然后您可以在配置中使用这个自定义路径。例如,以下日志处理程序将自定义路径用于其相对路径:

<subsystem xmlns="urn:jboss:domain:logging:6.0">
  ...
  <periodic-rotating-file-handler name="FILE" autoflush="true">
    <formatter>
      <named-formatter name="PATTERN"/>
    </formatter>
    <file relative-to="my.custom.path" path="server.log"/>
    <suffix value=".yyyy-MM-dd"/>
    <append value="true"/>
  </periodic-rotating-file-handler>
  ...
</subsystem>

3.8. 目录分组

在受管域中,每一服务器的文件存储在 EAP_HOME/domain 目录中。您可以使用主机控制器的 directory-grouping 属性来指定如何组织服务器的子目录。目录可以按 服务器类型 分组.默认情况下,目录按 服务器 分组。

通过服务器分组目录

默认情况下,目录按服务器分组。如果您的管理以 server 为中心的,则建议进行此配置。例如,它允许为每个服务器实例配置备份和日志文件处理。

如果使用 ZIP 安装方法安装 JBoss EAP,默认目录结构(由 server 进行分组)将如下所示:

EAP_HOME/domain
         └─ servers
            ├── server-one
            │   ├── data
            │   ├── tmp
            │   └── log
            └── server-two
                ├── data
                ├── tmp
                └── log

要按服务器对域目录进行分组,请输入以下管理 CLI 命令:

/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-server)

这将更新主机控制器的 host.xml 配置文件:

<servers directory-grouping="by-server">
  <server name="server-one" group="main-server-group"/>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
</servers>
按类型分组目录

您可以改为按文件类型分组目录,而不是按 server 对目录进行分组。如果您的管理是以文件类型为中心的,则建议采用此配置。例如,这样可以轻松备份仅备份 数据文件

如果使用 ZIP 安装方法安装 JBoss EAP,并且域的文件按照类型分组,则目录结构将如下所示:

EAP_HOME/domain
         ├── data
         │   └── servers
         │       ├── server-one
         │       └── server-two
         ├── log
         │   └── servers
         │       ├── server-one
         │       └── server-two
         └── tmp
             └── servers
                 ├── server-one
                 └── server-two

要根据类型对域目录进行分组,请输入以下管理 CLI 命令:

/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-type)

这将更新主机控制器的 host.xml 配置文件:

<servers directory-grouping="by-type">
  <server name="server-one" group="main-server-group"/>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
</servers>

3.9. 系统属性

您可以使用 Java 系统属性配置许多 JBoss EAP 选项,并可设置任何名称值对供应用服务器内使用。

系统属性可用于覆盖 JBoss EAP 配置中的默认值。例如,公共接口绑定地址的以下 XML 配置显示它可以通过 jboss.bind.address 系统属性设置,但如果未提供 system 属性,则默认为 127.0.0.1

<inet-address value="${jboss.bind.address:127.0.0.1}"/>

您可以通过几种方式在 JBoss EAP 中设置系统属性,包括:

如果您使用 JBoss EAP 受管域,系统属性可以应用到整个域、特定服务器组、特定主机及其所有服务器实例,或者仅应用到一个特定的服务器实例。与大多数其他 JBoss EAP 域设置一样,在更具体的级别上设置的系统属性将覆盖更抽象化的级别。如需更多信息,请参阅域管理一章

将系统属性传递给启动脚本

您可以使用 -D 参数将系统属性传递到 JBoss EAP 启动脚本。例如:

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=192.168.1.2

这种设置系统属性的方法对于 JBoss EAP 启动之前需要设置的 JBoss EAP 选项特别有用。

使用管理 CLI 设置系统属性

使用管理 CLI,您可以使用以下语法设置系统属性:

/system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)

例如:

/system-property=jboss.bind.address:add(value=192.168.1.2)

使用管理 CLI 设置系统属性时,某些 JBoss EAP 选项(包括上述 jboss.bind.address 示例)仅在下一次服务器重启后生效。

对于受管域,上例为整个域配置系统属性,但您也可以在更具体的域配置级别上设置或覆盖系统属性。

使用管理控制台设置系统属性
  • 对于独立 JBoss EAP 服务器,您可以在管理控制台 Configuration 选项卡下配置系统属性。选择"系统属性" ,然后单击"查看 "按钮。
  • 对于受管域:

    • 域级系统属性可以在 Configuration 选项卡中设置。选择"系统属性" ,然后单击"查看 "按钮。
    • 服务器组和服务器级系统属性可以在 Runtime 选项卡中设置。选择您要配置的服务器组或服务器,单击服务器组或服务器名称旁边的 View 按钮,然后选择系统属性选项卡
    • 主机级别系统属性可以在 Runtime 选项卡中设置。选择您要配置的主机,然后使用主机名旁边的下拉菜单选择属性
使用 JAVA_OPTS 设置系统属性

系统属性也可以使用 JAVA_OPTS 环境变量进行配置。可以通过多种方式修改 JAVA_OPTS,但 JBoss EAP 提供了用于设置 JBoss EAP 流程使用的 JAVA_OPTS 的配置文件。

对于单机服务器,此文件为 EAP_HOME/bin/standalone.conf,或者对于受管域,它是 EAP_HOME/bin/domain.conf。对于 Microsoft Windows 系统,这些文件具有 .bat 扩展名。

注意

对于 RPM 安装,RPM 服务配置文件 是修改 JAVA_OPTS 以配置系统属性的首选位置。如需更多信息,请参阅配置 RPM 服务属性

将您的系统属性定义添加到相关配置文件中的 JAVA_OPTS 中。以下示例演示了在 Red Hat Enterprise Linux 系统中设置绑定地址。

  • 对于 standalone.conf,请在文件的末尾添加 JAVA_OPTS 系统属性定义。例如:

    ...
    # Set the bind address
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
  • 对于 domain.conf,必须在进程控制器JAVA_OPTS 设置之前设置 JAVA_OPTS。例如:

    ...
    # Set the bind address
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
    
    # The ProcessController process uses its own set of java options
    if [ "x$PROCESS_CONTROLLER_JAVA_OPTS" = "x" ]; then
    ...

3.10. 管理审计日志记录

您可以为管理接口启用审计日志,它会记录使用管理控制台、管理 CLI 或使用管理 API 的自定义应用执行的所有操作。审计日志条目以 JSON 格式存储。默认情况下禁用审计日志。

您可以将审计日志记录配置为输出到文件或 syslog 服务器

注意

由于 JBoss EAP 中没有经过身份验证的会话,因此无法对登录和注销事件进行审计。相反,当从用户收到操作时,会记录审计消息。

独立服务器审计日志记录

虽然默认禁用,但默认的审计日志配置会写入到文件中。

<audit-log>
    <formatters>
        <json-formatter name="json-formatter"/>
    </formatters>
    <handlers>
        <file-handler name="file" formatter="json-formatter" path="audit-log.log" relative-to="jboss.server.data.dir"/>
    </handlers>
    <logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="file"/>
        </handlers>
    </logger>
</audit-log>

此配置可以通过以下管理 CLI 命令读取:

/core-service=management/access=audit:read-resource(recursive=true)

请参阅启用审计日志记录,为单机服务器启用审计日志记录。

受管域审计日志记录

虽然默认为禁用,默认的审计日志记录配置会为每个主机和每台服务器写入一个文件。

<audit-log>
    <formatters>
        <json-formatter name="json-formatter"/>
    </formatters>
    <handlers>
        <file-handler name="host-file" formatter="json-formatter" relative-to="jboss.domain.data.dir" path="audit-log.log"/>
        <file-handler name="server-file" formatter="json-formatter" relative-to="jboss.server.data.dir" path="audit-log.log"/>
    </handlers>
    <logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="host-file"/>
        </handlers>
    </logger>
    <server-logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="server-file"/>
        </handlers>
    </server-logger>
</audit-log>

此配置可以通过以下管理 CLI 命令读取:

/host=HOST_NAME/core-service=management/access=audit:read-resource(recursive=true)

请参阅启用审计日志记录,为受管域启用审计日志记录。

3.10.1. 启用管理审计日志记录

JBoss EAP 预配置了审计日志记录的文件处理程序,但审计日志记录默认为禁用。启用审计日志记录的管理 CLI 命令取决于您是以单机服务器还是在受管域中运行。如需文件处理程序属性,请参阅管理审计日志记录属性

以下说明启用 NATIVEHTTP 审计日志记录。要配置 JMX 审计日志,请参阅 启用 JMX 管理审计日志

要设置 syslog 审计日志记录,请参阅发送管理审计日志记录到 Syslog 服务器

启用单机服务器审计日志记录

可以使用以下命令启用审计日志记录:

/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)

默认情况下,这会将审计日志写入 EAP_HOME/standalone/data/audit-log.log

启用受管域审计日志记录

受管域的默认审计日志记录配置已预先配置为为每个主机和每一服务器写入审计日志。

可以使用以下命令,为每个主机启用审计日志记录:

/host=HOST_NAME/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)

默认情况下,这会将审计日志写入 EAP_HOME/domain/data/audit-log.log

可以使用以下命令,为每个服务器启用审计日志记录:

/host=HOST_NAME/core-service=management/access=audit/server-logger=audit-log:write-attribute(name=enabled,value=true)

默认情况下,这会将审计日志写入 EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log

3.10.2. 启用 JMX 管理审计日志记录

JBoss EAP 预配置了 JMX 审计日志的文件处理程序,尽管默认情况下这些日志是禁用的。启用审计日志记录的管理 CLI 命令取决于您是作为单机服务器还是受管域来运行。

要配置 NATIVE 或 HTTP 审计日志记录,请参阅 启用管理审计日志记录

启用单机服务器 JMX 审计日志记录

可以使用以下命令为单机服务器启用 JMX 审计日志记录:

/subsystem=jmx/configuration=audit-log:add()
/subsystem=jmx/configuration=audit-log/handler=file:add()

这将启用 JMX 审计日志记录,然后使用定义 的文件 处理程序将这些日志写入 EAP_HOME/standalone/data/audit-log.log

启用受管域 JMX 审计日志记录

可以为受管域中的每个主机和配置文件启用 JMX 审计日志记录。

为主机启用 JMX 审计日志记录

  1. 在主机的 jmx 子系统中启用审计日志记录。

    /host=HOST_NAME/subsystem=jmx/configuration=audit-log:add()
  2. 启用了 jmx 子系统的审计日志记录后,可以使用以下命令为主机定义处理程序:

    /host=HOST_NAME/subsystem=jmx/configuration=audit-log/handler=host-file:add()

    默认情况下,这会将 JMX 审计日志写入 EAP_HOME/domain/data/audit-log.log

为配置集启用 JMX 审计日志记录

  1. 在配置集的 jmx 子系统中启用审计日志记录。

    /profile=PROFILE_NAME/subsystem=jmx/configuration=audit-log:add()
  2. 启用了 jmx 子系统的审计日志记录后,可以使用以下命令为配置文件定义处理程序:

    /profile=PROFILE_NAME/subsystem=jmx/configuration=audit-log/handler=server-file:add()

    默认情况下,这会将 JMX 审计日志写入 EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log

3.10.3. 将管理审计日志记录发送到 Syslog 服务器

syslog 处理程序指定审计日志条目发送到 syslog 服务器的参数,特别是 syslog 服务器的主机名和 syslog 服务器侦听的端口。将审计日志记录发送到 syslog 服务器比记录到本地文件或本地 syslog 服务器更安全的选项。可以定义多个 syslog 处理程序并同时处于活动状态。

默认情况下,审计日志在启用时预先配置为输出到文件。使用以下步骤将审计日志记录设置并启用到 syslog 服务器。如需 syslog 处理程序属性,请参阅管理审计日志记录属性

  1. 添加 syslog 处理程序。

    通过指定 syslog 服务器的主机和端口,创建 syslog 处理程序。在受管域中,您必须在 /core-service 命令之前使用 /host=HOST_NAME

    batch
    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME:add(formatter=json-formatter)
    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=udp:add(host=HOST_NAME,port=PORT)
    run-batch
    注意

    要传递的参数因指定的协议而异。

    要将处理器配置为使用 TLS 与 syslog 服务器安全地通信,还必须配置身份验证,例如:

    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=tls/authentication=truststore:add(keystore-path=PATH_TO_TRUSTSTORE,keystore-password=TRUSTSTORE_PASSWORD)
  2. 添加对 syslog 处理程序的引用。

    在受管域中,您必须在此命令前加上 /host=HOST_NAME

    /core-service=management/access=audit/logger=audit-log/handler=SYSLOG_HANDLER_NAME:add
  3. 启用审计日志记录。

    请参阅 启用管理审计日志记录以启用审计日志记录

重要

在 JBoss EAP 中启用对 syslog 服务器的审计日志记录将不起作用,除非操作系统中也启用了日志记录。

有关 Red Hat Enterprise Linux 中的 rsyslog 配置的更多信息,请参阅 Red Hat Enterprise Linux 系统管理员指南的 Rsyslog 基本配置 部分,网址为 https://access.redhat.com/documentation/en/red-hat-enterprise-linux/

3.10.4. 阅读审计日志条目

输出到文件的审计日志条目最好使用文本查看器查看,而 syslog 服务器的输出则最好使用 syslog viewer 应用程序查看。

注意

不建议使用文本编辑器查看日志文件,因为这样可能会导致进一步日志条目写入到日志文件中。

审计日志条目以 JSON 格式存储。每个日志条目都以可选时间戳开头,后跟下表中的字段。

表 3.6. 管理审计日志字段
字段名称描述

访问

这可以有以下值之一:

  • NATIVE - 操作通过原生管理界面启动。
  • HTTP - 操作通过域 HTTP 接口进入。
  • JMX - 该操作通过 jmx 子系统进行。

引导

如果操作在启动过程中执行,则值为 true ;如果该操作在服务器启动并运行后执行,则为 false

domainUUID

个 ID,用于链接所有操作,因为它们从域控制器传播到其服务器、从属主机控制器和从属主机控制器服务器。

ops

正在执行的操作。这是序列化为 JSON 的操作列表。在引导时,这是解析 XML 时生成的操作。引导后,列表通常包含单个条目。

r/o

如果操作不更改管理模式,则值为 true ;如果更改管理模式,则为 false

remote-address

执行此操作的客户端地址。

success

如果操作成功,则值为 true,如果回滚,则为 false

type

这可以具有值 core,即管理操作或 jmx,即来自 jmx 子系统。

user

经过身份验证的用户的用户名。如果使用管理 CLI 在与正在运行的服务器相同的计算机上发生,则会使用特殊用户 $local

version

JBoss EAP 实例的版本号。

3.11. 服务器生命周期事件通知

您可以使用 JBoss EAP core-management 子系统JMX 为服务器生命周期事件设置通知。服务器运行时配置状态或服务器运行状态的变化将触发通知。

JBoss EAP 的服务器运行时配置状态为 STARTING、RUN NINGRELOAD_REQUIRED、REART_REQUIREDSTOPPINGSTOPPED

JBoss EAP 的服务器运行状态为 STARTING、NORMA L ADMIN_ONLYPRE_SUSPEND ING、SUSPENDINGSUSPENDEDSTOPPINGSTOPPED

3.11.1. 使用核心管理系统监控服务器生命周期事件

您可以将侦听器注册到 JBoss EAP 核心管理 子系统,以监控服务器生命周期事件。下列步骤演示了如何创建和注册将事件记录到文件中的示例侦听器。

  1. 创建监听器。

    创建 org.wildfly.extension.core.management.client.ProcessStateListener 实施,如下例所示。

    示例: Listener Class

    package org.simple.lifecycle.events.listener;
    
    import java.io.File;
    import java.io.FileWriter;
    import java.io.IOException;
    
    import org.wildfly.extension.core.management.client.ProcessStateListener;
    import org.wildfly.extension.core.management.client.ProcessStateListenerInitParameters;
    import org.wildfly.extension.core.management.client.RunningStateChangeEvent;
    import org.wildfly.extension.core.management.client.RuntimeConfigurationStateChangeEvent;
    
    public class SimpleListener implements ProcessStateListener {
    
        private File file;
        private FileWriter fileWriter;
        private ProcessStateListenerInitParameters parameters;
    
        public void init(ProcessStateListenerInitParameters parameters) {
            this.parameters = parameters;
            this.file = new File(parameters.getInitProperties().get("file"));
            try {
                fileWriter = new FileWriter(file, true);
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    
        public void cleanup() {
            try {
                fileWriter.close();
            } catch (IOException e) {
                e.printStackTrace();
            } finally {
                fileWriter = null;
            }
        }
    
        public void runtimeConfigurationStateChanged(RuntimeConfigurationStateChangeEvent evt) {
            try {
                fileWriter.write(String.format("Runtime configuration state change for %s: %s to %s\n", parameters.getProcessType(), evt.getOldState(), evt.getNewState()));
                fileWriter.flush();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    
        public void runningStateChanged(RunningStateChangeEvent evt) {
            try {
                fileWriter.write(String.format("Running state change for %s: %s to %s\n", parameters.getProcessType(), evt.getOldState(), evt.getNewState()));
                fileWriter.flush();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }

    注意

    实施监听程序时请牢记以下几点:

    • 在服务器重新加载时,侦听器在服务器尝试停止时停止侦听,并在服务器启动时重新加载侦听器。因此,实施必须确保它们可以在同一 JVM 中正确加载、初始化和删除多次。
    • 通知监听器正在阻止,允许响应服务器状态变化。实施必须确保它们不会阻断或死锁。
    • 每个侦听器实例在自己的线程中执行,而且顺序不受保证。
  2. 编译该类,并将它打包为 JAR。

    请注意,要编译,您需要依赖于 org.wildfly.core:wildfly-core-management-client Maven 模块。

  3. 添加 JAR 作为 JBoss EAP 模块。

    使用以下管理 CLI 命令,并提供模块名称和 JAR 路径:

    module add --name=org.simple.lifecycle.events.listener --dependencies=org.wildfly.extension.core-management-client --resources=/path/to/simple-listener-0.0.1-SNAPSHOT.jar
    重要

    使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

    技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

    如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

  4. 注册侦听器。

    使用下列管理 CLI 命令,将侦听器添加到 core-management 子系统:指定记录服务器生命周期事件的类、模块和文件位置。

    /subsystem=core-management/process-state-listener=my-simple-listener:add(class=org.simple.lifecycle.events.listener.SimpleListener, module=org.simple.lifecycle.events.listener,properties={file=/path/to/my-listener-output.txt})

现在,服务器生命周期事件会根据上面的 SimpleList ener 类记录到 my-listener -output.txt 文件中。例如,在管理 CLI 中发出 :suspend 命令会将以下内容输出到 my-listener-output.txt 文件:

Running state change for STANDALONE_SERVER: normal to suspending
Running state change for STANDALONE_SERVER: suspending to suspended

这表明运行状态已从 正常 更改为 暂停,然后从 暂停 变为 暂停

3.11.2. 使用 JMX 通知监控服务器生命周期事件

您可以注册 JMX 通知监听程序来监控服务器生命周期事件。以下步骤演示了如何创建和添加将事件记录到文件中的示例侦听器。

  1. 创建监听器。

    创建 javax.management.NotificationListener 实施,如下例所示:

    示例: Listener Class

    import java.io.BufferedWriter;
    import java.io.IOException;
    import java.nio.charset.StandardCharsets;
    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.nio.file.Paths;
    import java.nio.file.StandardOpenOption;
    
    import javax.management.AttributeChangeNotification;
    import javax.management.Notification;
    import javax.management.NotificationListener;
    
    import org.jboss.logging.Logger;
    
    public class StateNotificationListener implements NotificationListener {
    
      public static final String RUNTIME_CONFIGURATION_FILENAME = "runtime-configuration-notifications.txt";
      public static final String RUNNING_FILENAME = "running-notifications.txt";
      private final Path targetFile;
    
      public StateNotificationListener() {
        this.targetFile = Paths.get("notifications/data").toAbsolutePath();
        init(targetFile);
      }
    
      protected Path getRuntimeConfigurationTargetFile() {
        return this.targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME);
      }
    
      protected Path getRunningConfigurationTargetFile() {
        return this.targetFile.resolve(RUNNING_FILENAME);
      }
    
      protected final void init(Path targetFile) {
        try {
          Files.createDirectories(targetFile);
    
          if (!Files.exists(targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME))) {
            Files.createFile(targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME));
          }
    
          if (!Files.exists(targetFile.resolve(RUNNING_FILENAME))) {
            Files.createFile(targetFile.resolve(RUNNING_FILENAME));
          }
        } catch (IOException ex) {
            Logger.getLogger(StateNotificationListener.class).error("Problem handling JMX Notification", ex);
        }
      }
    
      @Override
      public void handleNotification(Notification notification, Object handback) {
        AttributeChangeNotification attributeChangeNotification = (AttributeChangeNotification) notification;
        if ("RuntimeConfigurationState".equals(attributeChangeNotification.getAttributeName())) {
          writeNotification(attributeChangeNotification, getRuntimeConfigurationTargetFile());
        } else {
          writeNotification(attributeChangeNotification, getRunningConfigurationTargetFile());
        }
      }
    
      private void writeNotification(AttributeChangeNotification notification, Path path) {
        try (BufferedWriter in = Files.newBufferedWriter(path, StandardCharsets.UTF_8, StandardOpenOption.APPEND)) {
          in.write(String.format("%s %s %s %s", notification.getType(), notification.getSequenceNumber(), notification.getSource().toString(), notification.getMessage()));
          in.newLine();
          in.flush();
        } catch (IOException ex) {
          Logger.getLogger(StateNotificationListener.class).error("Problem handling JMX Notification", ex);
        }
      }
    }

  2. 注册通知监听程序。

    将通知监听程序添加到 MBeanServer

    示例:添加通知列表

    MBeanServer server = ManagementFactory.getPlatformMBeanServer();
    server.addNotificationListener(ObjectName.getInstance("jboss.root:type=state"), new StateNotificationListener(), null, null);

  3. 打包并部署到 JBoss EAP.

服务器生命周期事件现在根据上面的 StateNotificationListener 类记录到文件中。例如,在管理 CLI 中发出 :suspend 命令会将以下内容输出到 running-notifications.txt 文件:

jmx.attribute.change 5 jboss.root:type=state The attribute 'RunningState' has changed from 'normal' to 'suspending'
jmx.attribute.change 6 jboss.root:type=state The attribute 'RunningState' has changed from 'suspending' to 'suspended'

这表明运行状态已从 正常 更改为 暂停,然后从 暂停 变为 暂停

第 4 章 网络和端口配置

4.1. interfaces

JBoss EAP 在整个配置中引用了命名接口。这允许配置引用带有逻辑名称的独立接口声明,而不必要求每次使用的接口的完整详情。

这也便于在受管域中配置,其中网络接口详细信息可能因多台计算机而异。每个服务器实例可以对应一个逻辑名称组。

standalone.xmldomain.xmlhost.xml 文件都包含接口声明。根据使用的默认配置,有几个预配置的接口名称。管理接口可用于需要管理层 的所有组件和服务,包括 HTTP 管理端点。公共 接口可用于所有应用相关的网络通信。无安全 接口用于标准配置中的 IIOP 套接字。专用 接口用于标准配置中的 JGroups 套接字。

4.1.1. 默认接口配置

<interfaces>
  <interface name="management">
    <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
  </interface>
  <interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
  </interface>
  <interface name="private">
    <inet-address value="${jboss.bind.address.private:127.0.0.1}"/>
  </interface>
  <interface name="unsecure">
    <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/>
  </interface>
</interfaces>

默认情况下,JBoss EAP 将这些接口绑定到 127.0.0.1,但可以通过设置适当的 属性在运行时覆盖这些值。例如,通过以下命令将 JBoss EAP 启动为单机服务器时可以设置 公共 接口的 inet-address

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS

或者,您也可以在 server start 命令行上使用 -b 参数。有关服务器启动选项的更多信息,请参阅服务器运行时参数

重要

如果您修改了 JBoss EAP 使用的默认网络接口或端口,您还必须记得更改使用修改后的接口或端口的任何脚本。其中包括 JBoss EAP 服务脚本,以及记得在访问管理控制台或管理控制台或 CLI 时指定正确的接口和端口。

4.1.2. 配置接口

通过为物理接口指定逻辑名称和选择条件来声明网络接口。选择条件可以引用通配符地址,或者指定接口或地址必须具有的一个或多个特征集,才能成为有效的匹配项。有关所有可用接口选择条件的列表,请参阅 Interface Attributes 部分。

接口可以使用管理控制台或管理 CLI 进行配置。以下是添加和更新接口的几个示例。首先显示管理 CLI 命令,后跟对应的配置 XML。

使用 NIC 值添加接口

添加一个 NIC 值为 eth0 的新接口。

/interface=external:add(nic=eth0)
<interface name="external">
   <nic name="eth0"/>
</interface>
使用 Several Conditional 值添加接口

添加一个与正确子网上任何接口/地址匹配的新接口(如果已启动,支持多播),且不是点对点的新接口。

/interface=default:add(subnet-match=192.168.0.0/16,up=true,multicast=true,not={point-to-point=true})
<interface name="default">
   <subnet-match value="192.168.0.0/16"/>
   <up/>
   <multicast/>
   <not>
      <point-to-point/>
   </not>
</interface>
更新接口属性

更新 公共 接口的默认 inet-address 值,保留 jboss.bind.address 属性,以允许在运行时设置此值。

/interface=public:write-attribute(name=inet-address,value="${jboss.bind.address:192.168.0.0}")
<interface name="public">
    <inet-address value="${jboss.bind.address:192.168.0.0}"/>
</interface>
向受管域中的服务器添加接口
/host=HOST_NAME/server-config=SERVER_NAME/interface=INTERFACE_NAME:add(inet-address=127.0.0.1)
<servers>
   <server name="SERVER_NAME" group="main-server-group">
      <interfaces>
         <interface name="INTERFACE_NAME">
            <inet-address value="127.0.0.1"/>
         </interface>
      </interfaces>
   </server>
</servers>

4.2. 套接字绑定

通过套接字绑定和套接字绑定组,您可以定义网络端口及其与 JBoss EAP 配置所需的网络接口的关系。套接字绑定是套接字的命名配置。套接字绑定组是套接字绑定声明的集合,这些声明按照逻辑名称分组。

这允许配置的其他部分根据其逻辑名称引用套接字绑定,而不必在每次使用套接字配置的完整详情。

这些指定配置的声明可以在 standalone.xmldomain.xml 配置文件中找到。单机服务器仅包含一个套接字绑定组,而受管域则可包含多个组。您可以为受管域中的每个服务器组创建一个套接字绑定组,或者在多个服务器组之间共享套接字绑定组。

JBoss EAP 默认使用的端口取决于使用的套接字绑定组以及您各个部署的要求。

JBoss EAP 配置的套接字绑定组中可以定义三种类型的套接字绑定:

入站套接字绑定

socket-binding 元素用于为 JBoss EAP 服务器配置入站套接字绑定。默认 JBoss EAP 配置提供多个预配置的 套接字绑定 元素,例如用于 HTTP 和 HTTPS 流量的元素。另一个示例是在为 JBoss EAP 配置消息传递 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuring_messaging/#broadcast_groups 的广播组小节

此元素的属性可以在入站套接字绑定属性表中找到

远程出站套接字绑定

remote-destination-outbound-socket-binding 元素用于为远程到 JBoss EAP 服务器的目的地配置出站套接字绑定。默认 JBoss EAP 配置提供一个示例远程目标套接字绑定,可用于邮件服务器。在为 JBoss EAP 配置消息传递的 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuring_messaging/#use_provided_amq_adapter "为远程连接使用集成 Artemis 资源适配器"一节中,可找到另一个示例。

此元素的属性可以在 Remote Outbound Socket Binding Attributes 表中找到。

本地出站套接字绑定

local-destination-outbound-socket-binding 元素用于为属于 JBoss EAP 服务器本地的目的地配置出站套接字绑定。预计通常不会使用这种套接字绑定。

此元素的属性可以在 Local Outbound Socket Binding Attributes 表中找到。

4.2.1. 管理端口

JBoss EAP 7 中整合了管理端口。默认情况下,JBoss EAP 7 将端口 9990 用于本地管理(由管理 CLI 使用)和 HTTP 管理(由基于 Web 的管理控制台使用)。用作 JBoss EAP 6 中的原生管理端口的端口 9999 不再使用,但在需要时仍可启用。

如果为管理控制台启用了 HTTPS,则默认使用端口 9993

4.2.2. 默认套接字绑定

JBoss EAP随附一个套接字绑定组,适用于这五个预定义配置文件(默认为 ha、full、full-ha 、负载均衡)。

有关默认套接字绑定的详细信息,如默认端口和描述,请参阅 Default Socket Bindings 部分。

重要

如果您修改了 JBoss EAP 使用的默认网络接口或端口,您还必须记得更改使用修改后的接口或端口的任何脚本。其中包括 JBoss EAP 服务脚本,以及记得在访问管理控制台或管理控制台或 CLI 时指定正确的接口和端口。

独立服务器

作为单机服务器运行时,每个配置文件仅定义一个套接字绑定组。每个独立配置文件(standalone.xmlstandalone-ha.xmlstandalone-full.xmlstandalone-full-ha.xmlstandalone-load-balancer.xml)定义其对应配置集所使用的技术的套接字绑定。

例如,默认的单机配置文件(standalone.xml)指定以下套接字绑定:

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
    <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
        <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
</socket-binding-group>
受管域

在受管域中运行时,所有套接字绑定组都在 domain.xml 文件中定义。有五个预定义的套接字绑定组:

  • 标准套接字
  • ha-sockets
  • 全套接字
  • full-ha-sockets
  • load-balancer-sockets

每个套接字绑定组都指定其对应配置集所使用的技术套接字绑定。例如,full-ha-sockets 套接字绑定组定义几个 jgroups 套接字绑定,供 full-ha 配置文件用于高可用性。

<socket-binding-groups>
  <socket-binding-group name="standard-sockets" default-interface="public">
    <!-- Needed for server groups using the 'default' profile  -->
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
      <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
  </socket-binding-group>
  <socket-binding-group name="ha-sockets" default-interface="public">
    <!-- Needed for server groups using the 'ha' profile  -->
    ...
  </socket-binding-group>
  <socket-binding-group name="full-sockets" default-interface="public">
    <!-- Needed for server groups using the 'full' profile  -->
    ...
  </socket-binding-group>
  <socket-binding-group name="full-ha-sockets" default-interface="public">
    <!-- Needed for server groups using the 'full-ha' profile  -->
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="iiop" interface="unsecure" port="3528"/>
    <socket-binding name="iiop-ssl" interface="unsecure" port="3529"/>
    <socket-binding name="jgroups-mping" interface="private" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
    <socket-binding name="jgroups-tcp" interface="private" port="7600"/>
    <socket-binding name="jgroups-udp" interface="private" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
    <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
      <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
  </socket-binding-group>
  <socket-binding-group name="load-balancer-sockets" default-interface="public">
    <!-- Needed for server groups using the 'load-balancer' profile  -->
    ...
  </socket-binding-group>
</socket-binding-groups>
注意

管理接口的套接字配置在域控制器的 host.xml 文件中定义。

4.2.3. 配置套接字绑定

在定义套接字绑定时,您可以配置 端口接口 属性,以及多播设置,如 多播地址和多 播端口。有关所有可用套接字绑定属性的详情,请查看 Socket Binding Attributes 部分。

可以使用管理控制台或管理 CLI 配置套接字绑定。下列步骤介绍了添加套接字绑定组、添加套接字绑定和使用管理 CLI 配置套接字绑定设置。

  1. 添加新套接字绑定组。请注意,作为单机服务器运行时,无法执行此步骤。

    /socket-binding-group=new-sockets:add(default-interface=public)
  2. 添加套接字绑定。

    /socket-binding-group=new-sockets/socket-binding=new-socket-binding:add(port=1234)
  3. 将套接字绑定更改为使用默认接口,由套接字绑定组设置。

    /socket-binding-group=new-sockets/socket-binding=new-socket-binding:write-attribute(name=interface,value=unsecure)

以下示例显示了在上述步骤完成后 XML 配置可以如何进行。

<socket-binding-groups>
    ...
    <socket-binding-group name="new-sockets" default-interface="public">
        <socket-binding name="new-socket-binding" interface="unsecure" port="1234"/>
    </socket-binding-group>
</socket-binding-groups>

4.2.4. 查看服务器的套接字绑定和开放端口

您可以从管理控制台查看服务器的套接字绑定名称和开放端口。当服务器处于以下状态时,可看到该信息:

  • running
  • reload-required
  • restart-required

查看服务器的套接字绑定和开放端口:

  1. 访问管理控制台并导航到 Runtime
  2. 单击服务器,以查看右侧窗格中的套接字绑定名称和打开的端口。

4.2.5. 端口偏移

端口偏移是一个数字偏移值,添加到该服务器的套接字绑定组中指定的所有端口值中。这使得服务器能够继承其套接字绑定组中定义的端口值,并提供偏移以确保它不与同一主机上的任何其他服务器冲突。例如,如果套接字绑定组的 HTTP 端口为 8080,并且服务器使用端口偏移 100,则其 HTTP 端口为 8180

以下是使用管理 CLI 受管域中的服务器设置端口偏移 250 的示例。

/host=master/server-config=server-two/:write-attribute(name=socket-binding-port-offset,value=250)

端口偏移可用于受管域中的服务器和在同一主机上运行多个单机服务器。

使用 jboss.socket.binding.port-offset 属性启动单机服务器时,您可以传递端口偏移。

$ EAP_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=100

4.3. IPv6 地址

默认情况下,JBoss EAP 配置为使用 IPv4 地址运行。以下步骤演示了如何配置 JBoss EAP 以使用 IPv6 地址运行。

为 IPv6 地址配置 JVM 堆栈

更新启动配置,以首选 IPv6 地址。

  1. 打开 启动配置文件。

    • 作为单机服务器运行时,编辑 EAP_HOME/bin/standalone.conf 文件(或 standalone.conf.bat for Windows Server)。
    • 在受管域中运行时,编辑 EAP_HOME/bin/domain.conf 文件(或 domain.conf.bat for Windows Server)。
  2. java.net.preferIPv4Stack 属性设置为 false

    -Djava.net.preferIPv4Stack=false
  3. 附加 java.net.preferIPv6Addresses 属性,并将它设为 true

    -Djava.net.preferIPv6Addresses=true

下例演示了在进行上述更改后,启动配置文件中的 JVM 选项如何显示。

# Specify options to pass to the Java VM.
#
if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="-Xms1303m -Xmx1303m -Djava.net.preferIPv4Stack=false"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
   JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv6Addresses=true"
else
更新 IPv6 地址的接口声明

配置中的默认接口值可以更改为 IPv6 地址。例如,以下管理 CLI 命令将 管理 接口设置为 IPv6 环回地址(::1)

/interface=management:write-attribute(name=inet-address,value="${jboss.bind.address.management:[::1]}")

以下示例演示了在运行上述命令后 XML 配置可以如何进行。

<interfaces>
    <interface name="management">
        <inet-address value="${jboss.bind.address.management:[::1]}"/>
    </interface>
    ....
</interfaces>

第 5 章 JBoss EAP 安全

JBoss EAP 提供为其自己的接口和服务配置安全性的功能,并为其上运行的应用程序提供安全性。

第 6 章 JBoss EAP 类加载

JBoss EAP 使用模块化类加载系统来控制已部署应用的类路径。这个系统比传统的分层类加载器系统提供更多灵活性和控制力。开发人员对其应用可用的类有精细的控制,并且可以配置部署来忽略应用服务器提供的类,而非自有的类。

模块类加载器将所有 Java 类划分为称为模块的逻辑组。每个模块可以定义对其他模块的依赖关系,以便将该模块中的类添加到其自己的类路径中。由于每个部署的 JAR 和 WAR 文件都被视为模块,因此开发人员可以通过在其应用中添加模块配置来控制其应用的类路径的内容。

6.1. 模块

模块是用于类加载和依赖关系管理的逻辑类分组。JBoss EAP 识别两种不同类型的模块:静态 和动态。这两者之间的主要区别在于如何打包它们。

静态模块

静态模块在应用服务器的 EAP_HOME/modules/ 目录中定义。每个模块都作为子目录存在,例如 EAP_HOME/modules/com/mysql/。每个模块目录随后包含一个插槽子目录,默认为 main,它包含 module.xml 配置文件以及任何所需的 JAR 文件。所有应用程序服务器提供的 API 都作为静态模块提供,包括 Jakarta EE API 以及其他 API。

示例:MySQL JDBC Driver module.xml 文件

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-8.0.12.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

模块名称 com.mysql 必须与模块的目录结构匹配,不包括插槽名称 main

如果许多应用部署在使用相同的第三方库的同一服务器上,创建自定义静态模块非常有用。管理员可以创建和安装包含这些库的模块,而不是将这些库与各个应用捆绑在一起。然后,应用可以声明对自定义静态模块的显式依赖关系。

JBoss EAP 分发中提供的模块位于 EAP_HOME/modules 目录中的 系统 目录中。这使它们与第三方提供的任何模块相隔离。任何红帽都在 JBoss EAP 基础上提供的产品也会将其模块安装到 系统 目录中。

用户必须确保自定义模块安装至 EAP_HOME/modules 目录中,每个模块使用一个目录。这可确保加载 系统 目录中已存在的模块自定义版本,而不是所附带的版本。这样,用户提供的模块优先于系统模块。

如果您使用 JBOSS_MODULEPATH 环境变量更改 JBoss EAP 搜索模块的位置,则产品将在指定的位置之一内查找 系统 子目录结构。系统 结构必须存在于通过 JBOSS_MODULEPATH 指定的位置。

注意

从 JBoss EAP 7.1 开始,还支持在 module.xml 文件的 resource-root path 元素中使用绝对路径。这样,就可以访问您的资源库,而无需将它们移到 EAP_HOME/modules 目录。

示例: module.xml 文件中的 Absolute Path

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="oracle.jdbc">
    <resources>
        <resource-root path="/home/redhat/test.jar"/>
    </resources>
</module>

动态模块

动态模块由应用服务器为每个 JAR 或 WAR 部署创建和加载,或者针对 EAR 中的每个子部署创建和加载。动态模块的名称派生自部署存档的名称。由于部署是作为模块加载的,所以它们可以配置依赖项,供其他部署用作依赖项。

只有在需要时才加载模块。这通常仅在部署具有显式或隐式依赖项的应用时才发生。

预定义模块

从 JBoss EAP 7.2 开始,当您使用默认模块加载程序时,可以使用一组预定义模块。包括所有 JBoss 模块 API 的特殊模块 org.jboss.modules 始终可用,并由 JBoss 模块提供。标准 Java 平台模块系统(JPMS)模块(Java 9 及更高版本中提供)也可通过其标准名称提供。使用 JDK 8 时,JDK 9 模块由 JBoss 模块模拟。

有关 Java 9 或更高版本中可用平台模块列表,请参阅相应的 JDK 文档。

有关为 Java 8 提供的平台模块列表,请参阅为 Java 8 提供的平台模块

6.2. 模块依赖项

模块依赖项是一种声明,一个模块需要一个或多个其他模块的类才能正常工作。当 JBoss EAP 加载模块时,模块类加载程序会解析该模块的依赖性,并将各个依赖项中的类添加到其类路径中。如果无法找到指定的依赖项,模块将无法加载。

注意

部署的应用(如 JAR 或 WAR)作为动态模块加载,并利用依赖项来访问 JBoss EAP 提供的 API。

有两种类型的依赖项:显式和 隐式

显式依赖项
开发人员在配置文件中声明显式依赖项。静态模块可以在其 module.xml 文件中声明依赖项。动态模块可以声明部署的 MANIFEST.MFjboss-deployment-structure.xml 部署描述符中的依赖关系。
隐式依赖项

当部署中发现特定条件或元数据时,JBoss EAP 会自动添加隐式依赖关系。JBoss EAP 提供的 Jakarta EE API 是通过检测部署中隐式依赖项而添加的模块示例。

也可以使用 jboss-deployment-structure.xml 部署描述符文件将部署配置为排除特定的隐式依赖项。当应用捆绑了 JBoss EAP 将尝试添加 作为隐式依赖项的库的特定版本时,这非常有用。

可选依赖项

明确的依赖项可以作为可选指定。如果加载可选依赖项,则不会导致模块加载失败。但是,如果稍后依赖项可用,它不会添加到模块的类路径中。加载模块时,依赖项必须可用。

导出依赖性

模块的类路径仅包含其自身的类和直接依赖项的类。模块无法访问其中一个依赖项的依赖项类别。不过,模块可以指定导出明确的依赖项。导出的依赖关系会提供给依赖于导出它的模块的任何模块。

例如,模块 A 依赖于模块 B,而模块 B 则依赖于模块 C。模块 A 可以访问模块 B 的类,而模块 B 则可访问模块 C 类。模块 A 无法访问模块 C 类,除非:

  • 模块 A 声明了明确依赖模块 C
  • 模块 B 导出其对模块 C 的依赖。
全局模块

全局模块是 JBoss EAP 提供的一个模块,作为每个应用的依赖性。任何模块均可通过添加至 JBoss EAP 的全局模块列表来实现全局。它不需要更改模块。

详情请查看 Define Global Modules 部分。

6.3. 创建自定义模块

可以添加自定义静态模块,以便为在 JBoss EAP 上运行的部署提供资源。您可以手动创建模块 ,也可以使用管理 CLI 来创建模块。

创建模块后,如果需要将其资源提供给应用,则必须将模块添加为依赖项

手动创建自定义模块

您可以按照以下步骤手动创建自定义模块。

  1. EAP_HOME/modules/ 目录中创建适当的目录结构。

    示例:创建 MySQL JDBC Driver Directory 结构

    $ cd EAP_HOME/modules/
    $ mkdir -p com/mysql/main

  2. 将 JAR 文件复制到 main/ 子目录中。

    示例:复制 MySQL JDBC 驱动程序 JAR

    $ cp /path/to/mysql-connector-java-8.0.12.jar EAP_HOME/modules/com/mysql/main/

  3. main/ 子目录中创建 module.xml 文件,并在 文件中指定适当的资源和依赖项。

    示例:MySQL JDBC Driver module.xml 文件

    <?xml version="1.0" ?>
    <module xmlns="urn:jboss:module:1.1" name="com.mysql">
      <resources>
        <resource-root path="mysql-connector-java-8.0.12.jar"/>
      </resources>
      <dependencies>
        <module name="javaee.api"/>
        <module name="sun.jdk"/>
        <module name="ibm.jdk"/>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
      </dependencies>
    </module>

使用管理 CLI 创建自定义模块

您可以使用模块 add management CLI 命令来创建自定义模块

重要

使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

  1. 启动 JBoss EAP 服务器。
  2. 启动管理 CLI。

    $ EAP_HOME/bin/jboss-cli.sh
  3. 使用 模块 add management CLI 命令,添加新的核心模块。

    module add --name=MODULE_NAME --resources=PATH_TO_RESOURCE --dependencies=DEPENDENCIES

    示例:创建一个 MySQL 模块

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api

    请参阅 模块命令参数 以了解可用于自定义此命令的参数,例如,使用外部模块目录提供您自己的 module.xml 文件,或者为模块指定备选插槽。您还可以执行 模块 --help 来了解有关使用此命令添加和删除模块的更多详细信息。

添加模块作为依赖性

为了使您的应用能够访问此模块的资源,您必须将模块添加为依赖项。

  • 有关将模块添加为依赖性到所有应用程序的说明,请参阅 Define Global Modules 部分。

例如,下列步骤添加一个 JAR 文件,该文件包含多个属性文件作为模块,再定义全局模块,以便应用随后可以加载这些属性。

  1. 将 JAR 文件添加为核心模块。

    module add --name=myprops --resources=/path/to/properties.jar
  2. 将此模块定义为全局模块,使它可供所有部署使用。

    /subsystem=ee:list-add(name=global-modules,value={name=myprops})
  3. 然后,应用可以从 JAR 中包含的其中一个属性文件中检索属性。

    Thread.currentThread().getContextClassLoader().getResource("my.properties");

6.4. 删除自定义模块

可以手动 或使用管理 CLI 删除自定义静态模块。

手动删除自定义模块

在手动删除模块之前,请确保部署的应用或服务器配置中的其他位置不需要该模块,如数据源。

若要移除自定义模块,可删除 EAP_HOME/modules/ 下的模块目录,其中包括模块的 module.xml 文件以及关联的 JAR 文件或其他资源。例如,删除 EAP_HOME/modules/com/mysql/main/ 目录,以删除 插槽中的自定义 MySQL JDBC 驱动程序模块。

使用管理 CLI 移除自定义模块

您可以使用模块 删除管理 CLI 命令删除自定义模块

重要

使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

  1. 启动 JBoss EAP 服务器。
  2. 启动管理 CLI。

    $ EAP_HOME/bin/jboss-cli.sh
  3. 使用 模块 remove management CLI 命令,以删除自定义模块。

    module remove --name=MODULE_NAME
    • 如果要删除的模块位于 main 以外的插槽中,请使用 --slot 参数。

    示例:删除 MySQL 模块

    module remove --name=com.mysql

执行 模块 --help 获取关于使用此命令添加和删除模块的更多详细信息。

6.5. 定义全局模块

可以为 JBoss EAP 定义全局模块列表,它们将模块添加为依赖项到所有部署。

注意

使用以下管理 CLI 命令,定义全局模块列表:

/subsystem=ee:write-attribute(name=global-modules,value=[{name=MODULE_NAME_1},{name=MODULE_NAME_2}]

使用以下管理 CLI 命令,将单个模块添加到现有全局模块列表中:

/subsystem=ee:list-add(name=global-modules,value={name=MODULE_NAME})

也可以使用管理控制台从 Configuration 选项卡导航到 EE 子系统并选择 Global Modules 部分来添加和删除全局模块。

如果您希望全局模块可由外部依赖项访问,您必须明确使其可用。以下选项可用于从外部获取全局模块中的服务:

  • jboss-deployment-structure.xml中,将 services="import" 添加到模块中
  • 在全局模块定义中添加 services="true"。

    /subsystem=ee:write-attribute(name=global-modules,value=[{name=module1,services=true}]

    或者,在添加多个模块时:

    /subsystem=ee:write-attribute(name=global-modules,value=[{name=module1,services=true},{name=module2,services=false}]

    将新模块添加到现有列表中:

    /subsystem=ee:list-add(name=global-modules,value={name=module1,services=true})
  • 使用管理控制台定义全局模块时,请确保 Services 属性的值为 On

6.6. 配置子部署隔离

企业存档(EAR)中的每个子部署是一个具有自己的类加载器的动态模块。Subdeployments 始终对父模块具有隐式依赖关系,这使得它们有权访问 EAR/lib 中的类。默认情况下,子部署可以访问该 EAR 内其他子部署的资源。

如果您不希望子部署被允许访问属于其他子部署的类,则可以在 JBoss EAP 中启用严格的子部署隔离。此设置将影响所有部署。

为所有部署启用子部署模块隔离

可以使用管理控制台或来自 ee 子系统的管理 CLI 来启用或禁用子部署隔离。默认情况下,子部署隔离设为 false,允许子部署访问 EAR 部署中其他子部署的资源。

使用以下管理 CLI 启用 EAR 子部署隔离:

/subsystem=ee:write-attribute(name=ear-subdeployments-isolated,value=true)

EAR 中的子部署将不再能够从其他子部署访问资源。

6.7. 定义外部 JBoss EAP 模块目录

JBoss EAP 模块的默认目录是 EAP_HOME/modules。您可以使用 JBOSS_MODULEPATH 变量为 JBoss EAP 模块指定不同的目录。按照以下步骤,在 JBoss EAP 启动配置文件中设置此变量。

注意

您还可以将 JBOSS_MODULEPATH 设置为环境变量,而不是在 JBoss EAP 启动配置文件中设置它。

  1. 编辑 启动配置文件。

    • 作为单机服务器运行时,编辑 EAP_HOME/bin/standalone.conf 文件或 standalone.conf.bat (Windows Server)。
    • 在受管域中运行时,编辑 EAP_HOME/bin/domain.conf 文件或 domain.conf.bat (Windows Server)。
  2. 设置 JBOSS_MODULEPATH 变量,例如:

    JBOSS_MODULEPATH="/path/to/modules/directory/"

    若要指定目录列表,可使用冒号(:)来分隔目录列表。

    注意

    对于 Windows Server,使用以下语法设置 JBOSS_MODULEPATH 变量:

    set "JBOSS_MODULEPATH /path/to/modules/directory/"

    要指定目录列表,请使用分号(;)来分隔目录列表。

6.8. 动态模块命名约定

JBoss EAP 将所有部署作为模块加载,这些模块按照以下惯例命名:

  • WAR 和 JAR 文件的部署使用以下格式命名:

    deployment.DEPLOYMENT_NAME

    例如,inventory.warstore.jar 将分别具有 deployment.inventory.war 和 deployment. store.jar 的模块名称。

  • Enterprise Archive(EAR)中的子部署使用以下格式命名:

    deployment.EAR_NAME.SUBDEPLOYMENT_NAME

    例如,在企业存档 帐户内部署 report .war 的子 部署将具有 模块名称 deployment.accounts.ear.reports.war

第 7 章 部署应用程序

JBoss EAP 具有一系列应用部署和配置选项,可同时满足管理员和开发人员的需求。对于管理员而言,管理控制台 和管理 CLI 提供了理想的图形和命令行界面来管理生产环境中的应用部署。对于开发人员,应用部署测试选项的范围包括可配置的文件系统部署扫描程序 、HTTP API、红帽 CodeReady Studio 和 Maven 等 IDE。

在部署应用时,您可能希望通过将 org.jboss.metadata.parser.validate system 属性设置为 true 来启用对部署描述符的验证。这可以通过以下方法之一完成:

  • 启动服务器时:

    $ EAP_HOME/bin/standalone.sh -Dorg.jboss.metadata.parser.validate=true
  • 使用以下管理 CLI 命令将其添加到服务器配置中:

    /system-property=org.jboss.metadata.parser.validate:add(value=true)

7.1. 使用管理 CLI 部署应用

使用管理 CLI 部署应用可让您可以利用单一命令行界面来创建和运行部署脚本。您可以使用此脚本编写功能来配置特定的应用部署和管理场景。作为单机服务器运行时,您可以管理单个服务器的部署,或者受管域中运行的整个服务器网络。

7.1.1. 使用管理 CLI 将应用部署到单机服务器

部署应用程序

在管理 CLI 中,使用 部署 deploy-file 命令并指定应用部署的路径。

deployment deploy-file /path/to/test-application.war

成功部署不会向管理 CLI 生成任何输出,但服务器日志会显示部署消息。

WFLYSRV0027: Starting deployment of "test-application.war" (runtime-name: "test-application.war")
WFLYUT0021: Registered web context: /test-application
WFLYSRV0010: Deployed "test-application.war" (runtime-name : "test-application.war")

同样,您可以使用以下 部署 命令:

  • 使用 部署 deploy-cli-archive 从 a .cli 存档文件中部署内容。CLI 部署存档是扩展名为 .cliJAR 文件。它包含应当部署的应用存档,以及包含命令和操作的 CLI 脚本文件 deploy .scr 和 undeploy.scr。个脚本文件 deploy.scr 包含部署应用存档和设置环境的命令和操作;另一个脚本文件 undeploy.scr 包含用于取消部署应用存档并清理环境的命令。
  • 使用 部署 deploy-url 来部署 URL 引用的内容。

您还可以使用 deployment enable 命令启用 禁用 的应用。

取消部署应用

在管理 CLI 中,使用 部署 undeploy 命令并指定部署名称。这将从存储库删除部署内容。如需在取消部署时保留部署内容,请参阅禁用应用程序

deployment undeploy test-application.war

成功卸载不会向管理 CLI 生成任何输出,但服务器日志会显示未部署消息。

WFLYUT0022: Unregistered web context: /test-application
WFLYSRV0028: Stopped deployment test-application.war (runtime-name: test-application.war) in 62ms
WFLYSRV0009: Undeployed "test-application.war" (runtime-name: "test-application.war")

类似地,您可以使用 部署 undeploy-cli-archive 从 a .cli 存档文件中取消部署内容。您还可以使用通配符(*)取消部署所有部署。

deployment undeploy *
禁用应用程序

禁用部署的应用,但不从存储库中删除部署内容。

deployment disable test-application.war

您可以使用 deployment disable-all 命令禁用所有部署。

deployment disable-all
启用应用程序

启用禁用的部署应用。

deployment enable test-application.war

您可以使用 deployment enable-all 命令启用所有部署。

deployment enable-all
列出部署

在管理 CLI 中,使用 deployment info 命令列出部署信息。

deployment info

输出中将显示每个部署的详细信息,如运行时名称、状态以及是否启用。

NAME                 RUNTIME-NAME         PERSISTENT ENABLED STATUS
helloworld.war       helloworld.war       true       true    OK
test-application.war test-application.war true       true    OK

按名称显示部署信息:

deployment info helloworld.war

您还可以使用 deployment list 命令列出所有 部署。

7.1.2. 使用管理 CLI 在受管域中部署应用

部署应用程序

在管理 CLI 中,使用 部署 deploy-file 命令并指定应用部署的路径。您还必须指定应用应部署到的服务器组。

  • 将应用部署到所有服务器组:

    deployment deploy-file /path/to/test-application.war --all-server-groups
  • 将应用部署到特定的服务器组:

    deployment deploy-file /path/to/test-application.war --server-groups=main-server-group,other-server-group

成功部署不会向管理 CLI 生成任何输出,但服务器日志显示每个受影响的服务器的部署消息。

[Server:server-one] WFLYSRV0027: Starting deployment of "test-application.war" (runtime-name: "test-application.war")
[Server:server-one] WFLYUT0021: Registered web context: /test-application
[Server:server-one] WFLYSRV0010: Deployed "test-application.war" (runtime-name : "test-application.war")

同样,您可以使用以下 部署 命令:

  • 使用 deployment deploy-cli-archive 命令,从 a .cli 存档文件中部署内容。CLI 部署存档是扩展名为 .cliJAR 文件。它包含应当部署的应用存档,以及包含命令和操作的 CLI 脚本文件 deploy .scr 和 undeploy.scr。个脚本文件 deploy.scr 包含部署应用存档和设置环境的命令和操作;另一个脚本文件 undeploy.scr 包含用于取消部署应用存档并清理环境的命令。
  • 使用 deployment deploy-url 命令来部署 URL 引用的内容。

您还可以使用 deployment enable 命令启用 禁用 的应用。

取消部署应用

在管理 CLI 中,使用 部署 undeploy 命令并指定部署名称。您还必须指定应当从中取消部署应用的服务器组。如需从特定服务器组取消部署,请参阅禁用应用程序

利用该部署,从所有服务器组取消部署应用。

deployment undeploy test-application.war --all-relevant-server-groups

成功卸载不会向管理 CLI 生成任何输出,但服务器日志显示每个受影响的服务器的未部署消息。

[Server:server-one] WFLYUT0022: Unregistered web context: /test-application
[Server:server-one] WFLYSRV0028: Stopped deployment test-application.war (runtime-name: test-application.war) in 74ms
[Server:server-one] WFLYSRV0009: Undeployed "test-application.war" (runtime-name: "test-application.war")

类似地,您可以使用 部署 undeploy-cli-archive 命令从 a .cli 存档文件中取消部署内容。您还可以使用通配符(*)取消部署所有部署。

deployment undeploy * --all-relevant-server-groups
禁用应用程序

从特定的服务器组禁用部署的应用,并将其内容保留在存储库中,以用于使用该部署的其他服务器组。

deployment disable test-application.war --server-groups=other-server-group

您可以使用 deployment disable-all 命令禁用所有部署。

deployment disable-all --server-groups=other-server-group
启用应用程序

启用禁用的部署应用。

deployment enable test-application.war

您可以使用 deployment enable-all 命令启用所有部署。

deployment enable-all --server-groups=other-server-group
列出部署

在管理 CLI 中,使用 deployment info 命令列出部署信息。您可以按照部署名称或服务器组列出部署信息。

按名称显示部署信息:

deployment info helloworld.war

输出中将列出各个服务器组中的部署及其状态。

NAME               RUNTIME-NAME
helloworld.war     helloworld.war

SERVER-GROUP       STATE
main-server-group  enabled
other-server-group added

显示服务器组的部署信息:

deployment info --server-group=other-server-group

输出将列出指定服务器组的部署及其状态。

NAME                 RUNTIME-NAME         STATE
helloworld.war       helloworld.war       added
test-application.war test-application.war enabled

您还可以使用 deployment list 命令列出域中的所有部署

7.2. 使用管理控制台部署应用

使用管理控制台部署应用程序可为您提供易于使用的图形界面。您可以在概览中看到哪些应用部署到您的服务器或服务器组,您可以根据需要从内容存储库中启用、禁用或删除应用。

7.2.1. 使用管理控制台将应用程序部署到单机服务器

可以从 JBoss EAP 管理控制台的 Deployments 选项卡查看和管理部署。

部署应用程序

单击添加(+)按钮。您可以选择通过上传部署、添加非受管部署或 创建空部署 来部署应用。部署默认是启用的。

  • 上传部署

    上传将复制到服务器的内容存储库并由 JBoss EAP 管理的应用。

  • 添加非受管部署

    指定部署的位置。此部署不会复制到服务器的内容存储库中,也不会由 JBoss EAP 管理。

  • 创建空部署

    创建一个展开式空部署。您可以在创建后将文件添加到部署中。

取消部署应用

选择部署,再选择 Undeploy 选项。JBoss EAP 从内容存储库中移除部署。

禁用应用程序

选择部署并选择 Disable 选项来禁用应用。这会取消部署部署,但不会将它从内容存储库中移除。

替换应用程序

选择部署并选择 Replace 选项。选择部署的新版本,其名称必须与原始版本相同,然后单击 Finish。这会取消部署和删除部署的原始版本,然后部署新版本。

7.2.2. 使用管理控制台在受管域中部署应用

在 JBoss EAP 管理控制台的 Deployments 选项卡中,可以通过以下方法查看和管理部署:

  • 内容存储库

    所有受管和非受管部署都列在 Content Repository 部分中。可以在此处添加部署并将其部署到服务器组。

  • 服务器组

    Server Groups 部分中列出了已部署到一个或多个服务器组的部署。可以在此处启用部署并直接添加到服务器组中。

添加应用程序
  1. 从内容存储库 ,单击添加按钮
  2. 选择上传部署或添加非受管部署 来添加应用
  3. 按照提示部署应用。

    请注意,部署必须部署到服务器组,然后才能启用。

将应用程序部署到服务器组
  1. Content Repository,选择一个部署,再单击 Deploy 按钮。
  2. 选择应当要部署此部署的一个或多个服务器组。
  3. (可选)选择 选项,以启用在选定服务器组上的部署。
从服务器组取消部署应用
  1. 从服务器组中,选择相应的服务器组。
  2. 选择所需的部署,再单击取消部署按钮

也可以选择 Content Repository 中为部署的 Undeploy 按钮,一次性从多个服务器组取消部署部署。

删除应用程序
  1. 如果部署仍然部署到任何服务器组,请务必取消部署该部署。
  2. Content Repository ,选择部署并单击删除按钮

这会从内容存储库删除部署。

禁用应用程序
  1. 从服务器组中,选择相应的服务器组。
  2. 选择所需的部署,再单击禁用按钮

这会取消部署部署,但不会将它从内容存储库中移除。

替换应用程序
  1. Content Repository ,选择部署并单击替换按钮
  2. 选择部署的新版本,其名称必须与原始版本相同,然后单击 Replace

这会取消部署和删除部署的原始版本,然后部署新版本。

7.3. 使用部署扫描器部署应用

部署扫描器监控要部署的应用的部署目录。默认情况下,部署扫描器将每五秒扫描 EAP_HOME/standalone/deployments/ 目录以进行更改。标记文件用于指示部署的状态,以及触发针对部署的操作,如取消部署或重新部署。

虽然建议使用管理控制台或管理 CLI 来在生产环境中应用部署,但为开发人员提供了使用部署扫描程序进行部署。这允许用户以适合快速开发周期的方式构建和测试应用程序。此外,部署扫描程序不应与其他部署方法一起使用。

部署扫描程序仅可在将 JBoss EAP 作为单机服务器运行时使用。

7.3.1. 使用 Deployment Scanner 将应用程序部署到单机服务器

部署扫描器可以配置为允许或禁止自动部署 XML、压缩和展开的内容。如果禁用自动部署,您必须手动创建标志文件来触发部署操作。如需有关可用标志文件类型及其用途的更多信息,请参阅 Deployment Scanner Marker Files 部分。

默认情况下,启用 XML 和压缩的内容的自动部署。有关为每种内容类型配置自动部署的详情,请参阅配置 Deployment Scanner

警告

为方便开发人员,我们不建议在生产环境中使用部署扫描器进行部署。它也不应与其他部署方法一起使用。

部署应用程序

将内容复制到部署文件夹。

$ cp /path/to/test-application.war EAP_HOME/standalone/deployments/

如果启用自动部署,将自动提取此文件,并创建 a .deployed 标记文件。如果未启用自动部署,您将需要手动添加 a .dodeploy 标记文件来触发部署。

$ touch EAP_HOME/standalone/deployments/test-application.war.dodeploy
取消部署应用

通过删除 .deployed 标记文件来触发未部署。

$ rm EAP_HOME/standalone/deployments/test-application.war.deployed

如果启用了自动部署,您也可以删除 test-application.war 文件,该文件将触发取消部署。请注意,这不适用于展开式部署。

重新部署应用

创建 a .dodeploy 标记文件以启动重新部署。

$ touch EAP_HOME/standalone/deployments/test-application.war.dodeploy

7.3.2. 配置部署扫描器

部署扫描程序可以使用管理控制台或管理 CLI 进行配置。您可以配置部署扫描器的行为,如扫描间隔、部署文件夹位置和自动部署特定应用文件类型。您还可以完全禁用部署扫描程序。

有关所有可用部署扫描器属性的详情,请参阅 Deployment Scanner Attributes 部分。

使用以下管理 CLI 命令配置默认部署扫描程序:

禁用 Deployment Scanner
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-enabled,value=false)

这将禁用 默认的 部署扫描程序。

更改扫描间隔
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-interval,value=10000)

这会将扫描间隔时间从 5000 毫秒(五秒)更新为 10000 毫秒(十秒)。

更改 Deployment Folder
/subsystem=deployment-scanner/scanner=default:write-attribute(name=path,value=/path/to/deployments)

这会将部署文件夹的位置从 EAP_HOME/standalone/deployments 的默认位置更改为 /path/to/deployments

除非指定了 relative-to 属性,否则路径 将被视为绝对路径,在这种情况下,它将相对于该路径。

启用自动部署展开的内容
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-exploded,value=true)

这可实现自动部署展开式内容,这在默认情况下是禁用的。

禁用 Zipped 内容的自动部署
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-zipped,value=false)

这会禁用默认启用的 zipped 内容的自动部署。

禁用 XML 内容的自动部署
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-xml,value=false)

这禁用了 XML 内容的自动部署,默认为启用。

7.3.3. 定义自定义 Deployment Scanner

可以使用管理 CLI 或从管理控制台的 Configuration 选项卡导航到 Deployment Scanners 子系统来添加新的部署扫描程序。这将定义用于扫描部署的新目录。默认部署扫描器监控 EAP_HOME/standalone/deployments。有关 配置现有部署扫描程序的详情,请参阅配置 Deployment Scanner

以下管理 CLI 命令添加新的部署扫描器,它将每隔五秒检查 EAP_HOME/standalone/new_deployment_dir 以进行部署:

/subsystem=deployment-scanner/scanner=new-scanner:add(path=new_deployment_dir,relative-to=jboss.server.base.dir,scan-interval=5000)
注意

指定的目录必须已经存在,此命令将失败并显示错误。

已定义一个新的部署扫描器,并将监控指定的目录以监控部署。

7.4. 使用 Maven 部署应用程序

使用 Apache Maven 部署应用后,您可以将部署至 JBoss EAP 轻松整合到现有的开发工作流中。

您可以使用 Maven 使用 WildFly Maven 插件将应用部署到 JBoss EAP,它提供简单操作来部署和取消部署应用到应用服务器。

7.4.1. 使用 Maven 将应用部署到单机服务器

以下说明演示了如何使用 Maven 部署和取消部署 JBoss EAP helloworld 快速入门。

如需有关 JBoss EAP 快速入门的更多信息,请参阅 JBoss EAP 快速入门指南中的快速入门示例

部署应用程序

在 Maven pom.xml 文件中初始化 WildFly Maven 插件。这应在 JBoss EAP faststart pom.xml 文件中配置。

<plugin>
  <groupId>org.wildfly.plugins</groupId>
  <artifactId>wildfly-maven-plugin</artifactId>
  <version>${version.wildfly.maven.plugin}</version>
</plugin>

helloworld quickstart 目录,执行以下 Maven 命令:

$ mvn clean install wildfly:deploy

在发出要部署的 Maven 命令后,终端窗口将显示以下输出表示部署成功:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.981 s
[INFO] Finished at: 2015-12-23T15:06:13-05:00
[INFO] Final Memory: 21M/231M
[INFO] ------------------------------------------------------------------------

也可以通过查看活动服务器实例的服务器日志来确认部署。

WFLYSRV0027: Starting deployment of "helloworld.war" (runtime-name: "helloworld.war")
WFLYUT0021: Registered web context: /helloworld
WFLYSRV0010: Deployed "helloworld.war" (runtime-name : "helloworld.war")
取消部署应用

helloworld quickstart 目录,执行以下 Maven 命令:

$ mvn wildfly:undeploy

在发出 Maven 命令取消部署后,终端窗口将显示以下输出,指示成功取消部署:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.237 s
[INFO] Finished at: 2015-12-23T15:09:10-05:00
[INFO] Final Memory: 10M/183M
[INFO] ------------------------------------------------------------------------

也可以通过查看活动服务器实例的服务器日志来确认取消部署。

WFLYUT0022: Unregistered web context: /helloworld
WFLYSRV0028: Stopped deployment helloworld.war (runtime-name: helloworld.war) in 27ms
WFLYSRV0009: Undeployed "helloworld.war" (runtime-name: "helloworld.war")

7.4.2. 使用 Maven 在受管域中部署应用程序

以下说明演示了如何使用 Maven 在受管域中部署和取消部署 JBoss EAP helloworld 快速启动。

如需有关 JBoss EAP 快速入门的更多信息,请参阅 JBoss EAP 快速入门指南中的快速入门示例

部署应用程序

在受管域中部署应用时,您必须指定应当要将应用部署到的服务器组。这在 Maven pom.xml 文件中配置

pom.xml 中的以下配置初始化 WildFly Maven 插件,并将 main-server-group 指定为应用应部署到的服务器组。

<plugin>
  <groupId>org.wildfly.plugins</groupId>
  <artifactId>wildfly-maven-plugin</artifactId>
  <version>${version.wildfly.maven.plugin}</version>
  <configuration>
    <domain>
      <server-groups>
        <server-group>main-server-group</server-group>
      </server-groups>
    </domain>
  </configuration>
</plugin>

helloworld quickstart 目录,执行以下 Maven 命令:

$ mvn clean install wildfly:deploy

在发出要部署的 Maven 命令后,终端窗口将显示以下输出表示部署成功:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.005 s
[INFO] Finished at: 2016-09-02T14:36:17-04:00
[INFO] Final Memory: 21M/226M
[INFO] ------------------------------------------------------------------------

也可以通过查看活动服务器实例的服务器日志来确认部署。

WFLYSRV0027: Starting deployment of "helloworld.war" (runtime-name: "helloworld.war")
WFLYUT0021: Registered web context: /helloworld
WFLYSRV0010: Deployed "helloworld.war" (runtime-name : "helloworld.war")
取消部署应用

helloworld quickstart 目录,执行以下 Maven 命令:

$ mvn wildfly:undeploy

在发出 Maven 命令取消部署后,终端窗口将显示以下输出,指示成功取消部署:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.750 s
[INFO] Finished at: 2016-09-02T14:45:10-04:00
[INFO] Final Memory: 10M/184M
[INFO] ------------------------------------------------------------------------

也可以通过查看活动服务器实例的服务器日志来确认取消部署。

WFLYUT0022: Unregistered web context: /helloworld
WFLYSRV0028: Stopped deployment helloworld.war (runtime-name: helloworld.war) in 106ms
WFLYSRV0009: Undeployed "helloworld.war" (runtime-name: "helloworld.war")

7.5. 使用 HTTP API 部署应用程序

可以通过 curl 命令使用 HTTP API 将应用部署到 JBoss EAP。有关使用 HTTP API 的更多信息,请参阅 HTTP API 部分。

7.5.1. 使用 HTTP API 将应用程序部署到单机服务器

默认情况下,HTTP API 可通过 http://HOST: PORT/management 访问,例如 http://localhost:9990/management

部署应用程序
$ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "add", "address" : {"deployment" : "test-application.war"}, "content" : [{"url" : "file:/path/to/test-application.war"}]},{"operation" : "deploy", "address" : {"deployment" : "test-application.war"}}],"json.pretty":1}'
取消部署应用
$ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "undeploy", "address" : {"deployment" : "test-application.war"}},{"operation" : "remove", "address" : {"deployment" : "test-application.war"}}],"json.pretty":1}'

请参阅本红帽知识库文章,以编程方式生成 JSON 请求。

7.5.2. 使用 HTTP API 在受管域中部署应用程序

默认情况下,HTTP API 可通过 http://HOST: PORT/management 访问,例如 http://localhost:9990/management

部署应用程序
  1. 将部署添加到内容存储库。

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "add", "address" : {"deployment" : "test-application.war"}, "content" : [{"url" : "file:/path/to/test-application.war"}],"json.pretty":1}'
  2. 将部署添加到所需的服务器组。

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "add", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
  3. 将应用部署到服务器组。

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "deploy", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
取消部署应用
  1. 从分配至的所有服务器组移除部署。

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "remove", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
  2. 从内容存储库删除部署。

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "remove", "address" : {"deployment" : "test-application.war"}, "json.pretty":1}'

7.6. 自定义部署行为

7.6.1. 为部署内容定义自定义目录

您可以为 JBoss EAP 定义自定义位置,以存储已部署的内容。

为单机服务器定义自定义目录

默认情况下,单机服务器部署的内容存储在 EAP_HOME/standalone/data/content 目录中。可以通过在启动服务器时传递 -Djboss.server.deploy.dir 参数来更改此位置。

$ EAP_HOME/bin/standalone.sh -Djboss.server.deploy.dir=/path/to/new_deployed_content

在 JBoss EAP 实例中,所选位置应当是唯一的。

注意

jboss.server.deploy.dir 属性指定用于存储已使用管理控制台或管理 CLI 部署的内容的目录。要定义部署扫描程序要监控的自定义部署目录,请参阅 配置 Deployment Scanner

为受管域定义自定义目录

默认情况下,受管域部署的内容存储在 EAP_HOME/domain/data/content 目录中。可以通过在启动域时传递 -Djboss.domain.deployment.dir 参数来更改此位置。

$ EAP_HOME/bin/domain.sh -Djboss.domain.deployment.dir=/path/to/new_deployed_content

在 JBoss EAP 实例中,所选位置应当是唯一的。

7.6.2. 控制部署顺序

JBoss EAP 在服务器启动时提供精细的控制部署顺序。可以指定多个 EAR 文件中应用的部署顺序以及重启后顺序的持久性。

您可以使用 jboss-all.xml 部署描述符来声明顶级部署之间的依赖关系。

例如,如果您的 app.ear 依赖于 Framework .ear,则您可以创建一个 app.ear/META-INF/jboss-all.xml 文件,如下所示。

<jboss xmlns="urn:jboss:1.0">
  <jboss-deployment-dependencies xmlns="urn:jboss:deployment-dependencies:1.0">
    <dependency name="framework.ear" />
  </jboss-deployment-dependencies>
</jboss>
注意

您可以将部署的运行时名称用作 jboss-all.xml 文件中的依赖项名称。

这可确保在 app.ear 之前部署 Framework.ear

重要

如果您在 app.ear 中创建 jboss-all.xml 文件,并且您没有部署 框架.ear,则服务器将尝试部署 app.ear 和 失败。

7.6.3. 覆盖部署内容

部署覆盖可用于将内容覆盖到现有的部署中,而无需物理修改部署存档的内容。它允许您在运行时覆盖部署描述符、库 JAR 文件、类、JSP 页面和其他文件,而无需重新构建存档。

如果您需要为需要不同配置或设置的不同环境调整部署,这将非常有用。例如,当将部署从开发到测试、到暂存再移到生产环境时,您可能需要交换部署描述符,修改静态 Web 资源以更改应用的品牌,或者根据目标环境将 JAR 库替换为不同的版本。对于需要更改配置但因为策略或安全限制而无法修改或破解归档的安装,此功能也非常有用。

在定义部署覆盖时,您将指定将替换部署存档中的 文件的文件系统中的 文件。您还必须指定哪些部署应受到部署覆盖的影响。必须重新部署任何受影响的部署,才能使更改生效。

参数

您可以使用以下任一参数来配置部署覆盖:

  • 名称 :部署覆盖的名称。
  • 内容:: 以逗号分隔的列表,将文件系统上的 文件映射到所替换的存档中的 文件。每个条目的格式为 ARCHIVE_PATH=FILESYSTEM_PATH
  • 部署 :此覆盖所链接到的部署组合。
  • 重新部署受影响:: 重新部署所有受影响的部署。

有关完整使用详情,请执行 deployment-overlay --help

流程

  1. 使用 deployment-overlay add management CLI 命令添加部署覆盖:

    deployment-overlay add --name=new-deployment-overlay --content=WEB-INF/web.xml=/path/to/other/web.xml --deployments=test-application.war --redeploy-affected
    注意

    在受管域中,使用 --server-groups 指定适用的服务器组,或者通过 --all-server-groups 指定所有服务器组。

  2. 创建部署覆盖后,您可以将内容添加到现有覆盖中,将覆盖链接到部署,或删除覆盖。
  3. 可选:您可以在 <overlay> 元素中指定一个覆盖配置来链接包含静态 Web 资源(如 HTML、镜像或视频)的外部目录。<overlay> 元素位于应用程序 jboss-web.xml 文件中。使用这种配置时,您不需要重新打包应用程序。

    以下示例显示了 <overlay> 元素中的系统属性替换,其中 ${example.path.to.overlay} 定义 /PATH/TO/STATIC/WEB/CONTENT 位置。

    示例: jboss-web.xml 文件中的 <overlay> 元素

    <jboss-web>
            <overlay>${example.path.to.overlay}</overlay>
    </jboss-web>

    如果 jboss-descriptor-property-replacement 设为 true,则您可以在 <overlay> 元素 中指定系统属性,这是 descriptor 属性的默认值。

    要配置 jboss-descriptor-property-replacement,请使用以下命令:

    /subsystem=ee:write-attribute(name=jboss-descriptor-property-replacement,value=true)

    此命令在 JBoss EAP 配置的 ee 子系统中添加以下 XML 内容:

    <subsystem xmlns="urn:jboss:domain:ee:4.0">
        <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
    </subsystem>

7.6.4. 使用 Rollout Plans

关于 Rollout 计划

在受管域中,针对域或主机资源的操作可能会影响多个服务器。此类操作可能包括详细介绍操作应用到服务器的顺序的推出计划,以及详细描述是否可以在部分服务器上成功执行该操作的策略。如果没有指定推出计划,则会使用默认的推出部署计划

以下是涉及五个服务器组的推出计划示例:操作可以按序列、序列 并发组应用到服务器组Rollout Plan Syntax 中对语法进行了更为详细的说明。

{"my-rollout-plan" => {"rollout-plan" => {
    "in-series" => [
        {"concurrent-groups" => {
            "group-A" => {
                "max-failure-percentage" => "20",
                "rolling-to-servers" => "true"
            },
            "group-B" => undefined
        }},
        {"server-group" => {"group-C" => {
            "rolling-to-servers" => "false",
            "max-failed-servers" => "1"
        }}},
        {"concurrent-groups" => {
            "group-D" => {
                "max-failure-percentage" => "20",
                "rolling-to-servers" => "true"
            },
            "group-E" => undefined
        }}
    ],
    "rollback-across-groups" => "true"
}}}

查看上面的示例,将操作应用到域中的服务器时要分三个阶段完成。如果任何服务器组的策略触发在服务器组中回滚该操作,则所有其他服务器组也将回滚。

  1. 服务器组 group-Agroup-B 将同时应用操作。该操作将连续应用到 group-A 中的服务器,而 group-B 中的所有服务器将同时处理该操作。如果 group-A 中超过 20% 的服务器未能应用该操作,它将在整个组中回滚。如果 group-B 中的任何服务器都无法应用该操作,它将在该组间回滚。
  2. 完成 group-Agroup-B 中的所有服务器后,该操作将应用到 group-C 中的服务器。这些服务器将同时处理操作。如果 group-C 中的多个服务器无法应用该操作,它将在该组中回滚。
  3. 完成 group-C 中的所有服务器后,服务器组 group-Dgroup-E 将同时应用该操作。该操作将按顺序应用到 group-D 中的服务器,而 group-E 中的所有服务器将同时处理该操作。如果 group-D 中超过 20% 的服务器无法应用该操作,它将在整个组中回滚。如果 group-E 中的任何服务器都无法应用此操作,它将在该组间回滚。
rollout Plan Syntax

您可以通过以下任一方式指定推出部署计划。

虽然每种方法都有不同的初始命令,但这两种方法都使用 rollout 操作标头来定义推出计划。这使用以下语法:

rollout (id=PLAN_NAME | SERVER_GROUP_LIST) [rollback-across-groups]
  • PLAN_NAME 是使用 rollout-plan 命令存储的推出计划的名称。
  • SERVER_GROUP_LIST 是服务器组的列表。使用逗号分隔(,)来分隔多个服务器组,以指示应当按顺序对每一服务器组执行操作。使用脱字符(^)分隔符表示应同时对每个服务器组执行操作。

    • 对于每一服务器组,请在括号中设置以下任何策略:使用逗号分隔多个策略。

      • Rolling-to-servers :一个布尔值,如果设为 true,则按顺序将操作应用到组中的每一服务器。如果值为 false 或未指定,操作将同时应用到组中的服务器。
      • max-failed-servers :整数,它取组中的最大服务器数,无法应用该操作,然后再将它恢复到组中的所有服务器上。如果没有指定,则默认值为 0,表示任何服务器上的失败都会在组中触发回滚。
      • max-failure-percentage :0 到 100 之间的整数,表示组中服务器总数的最大百分比,在应在该组中的所有服务器上恢复操作之前无法应用该操作。如果没有指定,则默认值为 0,表示任何服务器上的失败都会在组中触发回滚。

        注意

        如果 max-failed-serversmax-failure-percentage 都被设置为非零值,则 max-failure-percentage 将具有优先权。

  • rollback-acros-groups :一个布尔值,指示一个服务器组中的所有服务器上是否需要回滚操作。默认值为 false
使用 Rollout 计划部署

您可以通过将推出(rollout) 设置 传递到 headers 参数,将部署计划的完整详情直接提供给 deploy 命令。有关格式的更多信息,请参阅 Rollout Plan Syntax

以下管理 CLI 命令利用为串行部署指定 rolling -to-servers=true 的部署计划将应用部署到 main- server-group 服务器组:

deploy /path/to/test-application.war --server-groups=main-server-group --headers={rollout main-server-group(rolling-to-servers=true)}
使用 Stored Rollout 计划部署

由于推出计划可能比较复杂,您可以选择存储推出计划的详细信息。这可让您在您要使用部署计划名称时引用推出计划的名称,而不必每次都需要部署计划的完整详情。

  1. 使用 rollout-plan 管理 CLI 命令来存储推出计划。有关格式的更多信息,请参阅 Rollout Plan Syntax

    rollout-plan add --name=my-rollout-plan --content={rollout main-server-group(rolling-to-servers=false,max-failed-servers=1),other-server-group(rolling-to-servers=true,max-failure-percentage=20) rollback-across-groups=true}

    这会创建以下部署计划:

    "rollout-plan" => {
        "in-series" => [
            {"server-group" => {"main-server-group" => {
                "rolling-to-servers" => false,
                "max-failed-servers" => 1
            }}},
            {"server-group" => {"other-server-group" => {
                "rolling-to-servers" => true,
                "max-failure-percentage" => 20
            }}}
        ],
        "rollback-across-groups" => true
    }
  2. 在部署应用时指定存储的 rollout 计划名称。

    以下管理 CLI 命令使用 my-rollout-plan 存储的推出计划将应用部署到所有服务器组:

    deploy /path/to/test-application.war --all-server-groups --headers={rollout id=my-rollout-plan}
删除 Stored Rollout Plan

您可以通过指定要删除的 rollout-plan 管理 CLI 命令,移除存储的推出部署计划。

rollout-plan remove --name=my-rollout-plan
默认 Rollout Plan

所有影响多个服务器的操作都将通过推出计划来执行。如果没有在操作请求中指定推出部署计划,则会生成默认的推出部署计划。计划将具有以下特征:

  • 只有一个高级别阶段。受操作影响的所有服务器组将同时应用操作。
  • 在每个服务器组中,操作将同时应用到所有服务器。
  • 如果服务器组中的任何服务器上发生故障,则会导致在该组内回滚。
  • 任何服务器组的故障将导致所有其他服务器组回滚。

7.7. 管理扩展部署

在 JBoss EAP 7.1 之前,您只能通过操作文件系统中的文件来管理爆炸式部署。从 JBoss EAP 7.1 开始,您可以使用管理界面管理爆炸式部署。这可让您更改展开式应用的内容,而无需部署新版本的应用。

注意

对部署中的静态文件(如 JavaScript 和 CSS 文件)的更新会立即生效。更改其他文件(如 Java 类)可能需要重新部署应用才能使更改生效。

您可以以空部署开始 ,或者展开现有的存档部署 ,然后添加或删除内容

请参阅查看部署内容,以浏览部署中的文件或读取文件的内容。

创建 Empty Exploded Deployment

您可以创建一个展开式部署,稍后根据需要添加内容。使用以下管理 CLI 命令,创建一个空的展开式部署:

/deployment=DEPLOYMENT_NAME.war:add(content=[{empty=true}])

需要 empty=true 选项来确认您是否打算创建空部署。

展开现有归档部署

您可以展开现有的存档部署,以便能更新其内容。请注意,必须先禁用部署,然后才能展开部署。使用以下管理 CLI 命令,展开部署:

/deployment=ARCHIVE_DEPLOYMENT_NAME.ear:explode

现在,您可以添加或删除此部署中的内容

注意

您也可以从管理控制台展开现有的存档部署。从 Deployments 选项卡中,选择部署并选择 Explode 下拉菜单。

将内容添加到扩展的部署中

若要向部署添加内容,可使用 add-content 管理 CLI 操作。提供添加内容的部署中的位置的路径,并提供要上传的内容。要上传的内容可以作为本地文件流、URL、JBoss EAP 内容存储库中已存在的内容哈希或内容字节数组提供。以下管理 CLI 命令使用 input-stream-index 选项将本地文件的内容上传到部署:

/deployment=DEPLOYMENT_NAME.war:add-content(content=[{target-path=/path/to/FILE_IN_DEPLOYMENT, input-stream-index=/path/to/LOCAL_FILE_TO_UPLOAD}]
注意

使用 add-content 操作将内容添加到部署中时,默认情况下会覆盖部署中的内容。您可以通过将 override 选项 设置为 false 来更改此行为。

从展开的部署中删除内容

若要从部署中删除内容,可使用 remove-content 管理 CLI 操作,并提供要移除的部署中内容的路径。

/deployment=DEPLOYMENT_NAME.war:remove-content(paths=[/path/to/FILE_1, /path/to/FILE_2])

7.8. 查看部署内容

您可以使用 JBoss EAP 管理界面浏览受管部署中文件的信息 ,并读取文件的内容

7.8.1. 浏览部署中的文件

使用 browse-content 操作来查看受管部署中的文件和目录。不提供任何参数来返回整个部署结构,或使用 path 参数提供特定目录的路径。

注意

您还可以从管理控制台浏览部署内容,导航到 Deployments 选项卡,选择部署,然后从下拉菜单中选择 View

/deployment=helloworld.war:browse-content(path=META-INF/)

这将显示 helloworld.war 部署的 META-INF/ 目录中的文件和目录。

{
    "outcome" => "success",
    "result" => [
        {
            "path" => "MANIFEST.MF",
            "directory" => false,
            "file-size" => 827L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/pom.properties",
            "directory" => false,
            "file-size" => 106L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/pom.xml",
            "directory" => false,
            "file-size" => 2713L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/",
            "directory" => true
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/",
            "directory" => true
        },
        {
            "path" => "maven/",
            "directory" => true
        },
        {
            "path" => "INDEX.LIST",
            "directory" => false,
            "file-size" => 251L
        }
    ]
}

您还可以为 browse-content 操作指定以下参数:

Archive
是否仅返回存档文件.
深度
指定要返回的文件深度.

7.8.2. 读取部署内容

您可以使用 read-content 操作读取受管部署中文件的内容。不提供任何参数来返回整个部署,或使用 path 参数提供特定文件的路径。例如:

/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)

这会返回一个文件流,它可显示在管理 CLI 中或保存到文件系统中

{
    "outcome" => "success",
    "result" => {"uuid" => "24ba8e06-21bd-4505-b4d4-bdfb16451b95"},
    "response-headers" => {"attached-streams" => [{
        "uuid" => "24ba8e06-21bd-4505-b4d4-bdfb16451b95",
        "mime-type" => "text/plain"
    }]}
}
7.8.2.1. 显示文件的内容

使用 附加 display 命令读取 MANIFEST.MF 文件的内容。

attachment display --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)

这会将 MANIFEST.MF 文件的内容从 helloworld.war 部署 显示到管理 CLI。

ATTACHMENT 8af87836-2abd-423a-8e44-e731cc57bd80:
Manifest-Version: 1.0
Implementation-Title: Quickstart: helloworld
Implementation-Version: 7.3.0.GA
Java-Version: 1.8.0_131
Built-By: username
Scm-Connection: scm:git:git@github.com:jboss/jboss-parent-pom.git/quic
 kstart-parent/helloworld
Specification-Vendor: JBoss by Red Hat
...
7.8.2.2. 保存文件的内容

使用 附加 save 命令将 MANIFEST.MF 文件的内容保存到文件系统中。

attachment save --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF) --file=/path/to/MANIFEST.MF

这会将 helloworld .war 中的 MANIFEST.MF 文件保存在 路径/到 /MANIFEST.MF 的路径/到 文件系统上。如果不使用 --file 参数指定文件路径,该文件将使用其唯一附加 ID 进行命名,并保存在管理 CLI 的工作目录中,默认为 EAP_HOME/bin/

第 8 章 域管理

本节讨论特定于受管域工作模式的概念和配置。

有关保护受管域的信息,请参阅 JBoss EAP 如何配置服务器安全性的安全受管域部分

8.1. 关于受管域

受管域工作模式允许从一个控制点管理多个 JBoss EAP 实例。

集中管理的 JBoss EAP 服务器集合称为域的成员。域中的所有 JBoss EAP 实例共享共同的管理策略。

域包含一个域控制器、一个或多个主机控制器,以及每个主机的零个或多个服务器组。

受管域.

域控制器是控制域的核心点。它确保每台服务器按照域的管理策略进行配置。域控制器也是主机控制器。

主机控制器是一种物理或虚拟主机,与域控制器交互,以控制其主机上运行的应用服务器实例的生命周期并协助域控制器管理它们。每一主机可以包含多个服务器组。

服务器组是一组 服务器实例,它们上已安装了 JBoss EAP,并且可以作为一个服务器实例进行管理和配置。域控制器管理部署到服务器组的 和 应用的配置。因此,服务器组中的每个服务器共享相同的配置和部署。

主机控制器与特定的物理或虚拟机绑定。如果您使用不同的配置,则可以在同一硬件上运行多个主机控制器,确保它们的端口和其他资源不会冲突。域控制器、单一主机控制器和多个服务器可能在同一物理系统上在同一 JBoss EAP 实例内运行。

8.1.1. 关于域控制器

域控制器是 JBoss EAP 服务器实例,充当域的中央管理点。个主机控制器实例配置为充当域控制器。

域控制器的主要职责是:

  • 维护域的中央管理策略.
  • 确保所有主机控制器都已知晓其当前内容。
  • 协助主机控制器确保所有正在运行的 JBoss EAP 服务器实例都按照此策略进行配置。

默认情况下,中央管理策略存储在 EAP_HOME/domain/configuration/domain.xml 文件中。主机控制器的此目录中需要此文件,此目录设置为作为域控制器运行。

domain.xml 文件包含可供域中服务器使用的配置集配置。配置文件包含该配置文件中提供的各种子系统的详细设置。域配置还包括套接字组的定义和服务器组定义。

注意

只要主机和服务器正在运行 JBoss EAP 6.2 或更高版本,JBoss EAP 7 域控制器就可以管理 JBoss EAP 6 主机和服务器。如需更多信息,请参阅将 JBoss EAP 7.x 域控制器配置为管理 JBoss EAP 6 实例

如需更多信息,请参阅启动受管域和 域控制器配置部分

8.1.2. 关于主机控制器

主机控制器的主要职责是服务器管理。它委派域管理任务,并负责启动和停止在其主机上运行的单个应用服务器进程。

它与域控制器交互,以帮助管理服务器和域控制器之间的通信。个域的多个主机控制器只能与一个域控制器交互。因此,在单一域模式中运行的所有主机控制器和服务器实例都有一个域控制器,必须属于同一域。

默认情况下,每一主机控制器从其主机文件系统上解压缩的 JBoss EAP 安装文件中的 EAP_HOME/domain/configuration/host.xml 文件中读取其配置。host.xml 文件包含以下特定于特定主机的配置信息:

  • 用于从此安装运行服务器实例的名称。
  • 特定于本地物理安装的配置。例如,domain .xml 中声明的 命名接口定义可映射到 host.xml 中实际的机器特定 IP 地址。和 domain.xml 中的抽象路径名称可映射到 host.xml 中的实际文件系统路径。
  • 以下任何配置:

    • 主机控制器如何联系域控制器注册自己并访问域配置。
    • 如何查找和联系远程域控制器。
    • 主机控制器是否充当域控制器

如需更多信息,请参阅 Start a Managed DomainHost Controller Configuration 部分。

8.1.3. 关于进程控制器

进程控制器是一个轻量级小进程,负责生成主机控制器进程并监控其生命周期。如果主机控制器崩溃,进程控制器将重启它。它还会按照主机控制器的指示启动服务器进程;但是,它不会自动重新启动崩溃的服务器进程。

进程控制器将日志记录到 EAP_HOME/domain/log/process-controller.log 文件。您可以使用 PROCESS_ CONTROLLER_JAVA _OPTS 变量,在 EAP_HOME /bin/domain.conf 文件中为进程控制器设置 JVM 选项。

8.1.4. 关于服务器组

服务器组是服务器实例的集合,可以作为一个服务器实例进行管理和配置。在受管域中,每个应用服务器实例属于服务器组,即使它是唯一的成员。个组中的服务器实例共享相同的配置文件配置和部署的内容。

域控制器和主机控制器在其域中每一服务器组的所有服务器实例上强制执行标准配置。

个域可以包含多个服务器组。不同的服务器组可以配置不同的配置文件和部署。例如,一个域可以配置不同的服务器层,提供不同的服务。

不同的服务器组也可以具有相同的配置文件和部署。例如,这可以实现滚动应用升级,从而在一个服务器组中升级应用,然后在第二个服务器组中更新,从而避免彻底的服务中断。

如需更多信息,请参阅 配置服务器组部分

8.1.5. 关于服务器

服务器代表应用服务器实例。在受管域中,所有服务器实例都是服务器组的成员。主机控制器在其自己的 JVM 进程中启动每个服务器实例。

如需更多信息,请参阅 配置服务器部分

8.3. 启动受管域

8.3.1. 启动受管域

可以使用 JBoss EAP 提供的 domain .sh 或 domain. bat 脚本启动域控制器和主机控制器。有关所有可用启动脚本参数及其目的的完整列表,请使用 --help 参数或查看 服务器运行时参数 部分。

域控制器必须在域中任何服务器组的任何从属服务器之前启动。首先启动域控制器,然后在域中启动任何其他关联的主机控制器。

启动域控制器

使用 host-master.xml 配置文件启动域控制器,它已针对专用域控制器进行了预配置。

$ EAP_HOME/bin/domain.sh --host-config=host-master.xml

根据域设置,您需要进行额外的配置,以允许主机控制器进行连接。另请参阅以下域设置示例:

启动主机控制器

使用 host-slave.xml 配置文件启动主机控制器,它已为从属主机控制器进行了预配置。

$ EAP_HOME/bin/domain.sh  --host-config=host-slave.xml

根据域设置,您将需要连接额外的配置,而不与域控制器冲突。另请参阅以下域设置示例:

8.3.2. 域控制器配置

您必须将域中的一个主机配置为域控制器。

重要

在使用 RPM 安装方法安装 JBoss EAP 时,不支持在同一计算机上配置多个域控制器或主机控制器。

通过在 < domain-controller > 声明中添加 <local/ > 元素,将主机配置为域控制器。<domain-controller> 应该不包含任何其他内容。

<domain-controller>
  <local/>
</domain-controller>

充当域控制器的主机必须公开一个可供域中其他主机访问的管理接口。HTTP 接口是标准的管理接口。

<management-interfaces>
  <http-interface security-realm="ManagementRealm" http-upgrade-enabled="true">
    <socket interface="management" port="${jboss.management.http.port:9990}"/>
  </http-interface>
</management-interfaces>

示例最小域控制器配置文件 EAP_HOME/domain/configuration/host-master.xml 包含这些配置设置。

8.3.3. 主机控制器配置

主机控制器必须配置为连接到域控制器,以便主机控制器能够将自身注册到域。

重要

在使用 RPM 安装方法安装 JBoss EAP 时,不支持在同一计算机上配置多个域控制器或主机控制器。

使用配置的 <domain-controller> 元素 来配置与域控制器的连接。

<domain-controller>
  <remote security-realm="ManagementRealm">
    <discovery-options>
      <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9990}"/>
    </discovery-options>
  </remote>
</domain-controller>

示例最小主机控制器配置文件 EAP_HOME/domain/configuration/host-slave.xml 包含用于连接域控制器的配置设置。该配置假定您在启动主机控制器 时提供 jboss.domain.master.address 属性。

$ EAP_HOME/bin/domain.sh --host-config=host-slave.xml -Djboss.domain.master.address=IP_ADDRESS

有关域控制器发现的更多信息,请参阅域控制器发现和故障转移部分

根据您的域设置,您可能还需要为主机控制器提供身份验证,以通过域控制器进行身份验证。如需了解有关生成具有 secret 值的管理用户以及使用该值更新主机控制器配置的详细信息,请参阅在两个机器中设置受管域

8.3.4. 配置主机的名称

受管域中运行的每个主机必须具有唯一的主机名。为简化管理并允许在多个主机上使用相同的主机配置文件,服务器在确定主机名时要使用以下优先级:

  1. 如果设置,host .xml 配置文件中的 host 元素 name 属性。
  2. jboss.host.name 系统属性的值。
  3. jboss.qualified.host.name 系统属性中最后一个句点(. )字符后面的值;如果没有最终句点(.)字符,则为整个值。
  4. 基于 POSIX 的操作系统的 HOSTNAME 环境变量中的句点(.)字符后面的值、Microsoft Windows 的 COMPUTERNAME 环境变量,或者整个值(如果没有最终句点(.)字符)。

主机控制器的名称在相关 host .xml 配置文件顶部的主机元素中配置,例如:

<host xmlns="urn:jboss:domain:8.0" name="host1">

使用以下步骤,通过管理 CLI 更新主机名。

  1. 启动 JBoss EAP 主机控制器。

    $ EAP_HOME/bin/domain.sh --host-config=host-slave.xml
  2. 启动管理 CLI,连接域控制器。

    $ EAP_HOME/bin/jboss-cli.sh --connect --controller=DOMAIN_CONTROLLER_IP_ADDRESS
  3. 使用以下命令来设置新主机名:

    /host=EXISTING_HOST_NAME:write-attribute(name=name,value=NEW_HOST_NAME)

    这会修改 host-slave.xml 文件中的主机名属性,如下所示:

    <host name="NEW_HOST_NAME" xmlns="urn:jboss:domain:8.0">
  4. 重新加载主机控制器,使更改生效。

    reload --host=EXISTING_HOST_NAME

如果主机控制器配置文件中没有设置名称,您也可以在运行时传递主机名。

$ EAP_HOME/bin/domain.sh --host-config=host-slave.xml  -Djboss.host.name=HOST_NAME

8.4. 管理服务器

8.4.1. 配置服务器组

以下是服务器组定义的示例:

<server-group name="main-server-group" profile="full">
  <jvm name="default">
    <heap size="64m" max-size="512m"/>
  </jvm>
  <socket-binding-group ref="full-sockets"/>
  <deployments>
    <deployment name="test-application.war" runtime-name="test-application.war"/>
    <deployment name="helloworld.war" runtime-name="helloworld.war" enabled="false"/>
  </deployments>
</server-group>

可以使用管理 CLI 或管理控制台 Runtime 选项卡来配置服务器组。

添加服务器组

以下管理 CLI 命令可用于添加服务器组:

/server-group=SERVER_GROUP_NAME:add(profile=PROFILE_NAME,socket-binding-group=SOCKET_BINDING_GROUP_NAME)
更新服务器组

以下管理 CLI 命令可用于更新服务器组属性:

/server-group=SERVER_GROUP_NAME:write-attribute(name=ATTRIBUTE_NAME,value=VALUE)
删除服务器组

以下管理 CLI 命令可用于移除服务器组:

/server-group=SERVER_GROUP_NAME:remove
服务器组属性

服务器组需要以下属性:

  • Name :服务器组名称。
  • profile :服务器组配置文件名称。
  • socket-binding-group :用于组中服务器的默认套接字绑定组。这可以逐个服务器覆盖。

服务器组包括以下可选属性:

  • management-subsystem-endpoint :设置为 true,使属于服务器组的服务器使用来自其远程 子系统的端点重新 连接到主机控制器。必须存在远程 子系统 才能正常工作。
  • socket-binding-default-interface :此服务器的套接字绑定组默认接口。
  • socket-binding-port-offset :添加到套接字绑定组给出的端口值的默认偏移。
  • Deployment: 要部署到组中服务器上的部署内容。
  • JVM :组中所有服务器的默认 JVM 设置。主机控制器将这些设置与 host.xml 中提供的任何其他配置合并,以派生用于启动服务器的 JVM 的设置。
  • deployment-overlays :此服务器组中定义的部署覆盖和部署之间的链接。
  • system-properties :要在组中的服务器上设置的系统属性。

8.4.2. 配置服务器

默认 host.xml 配置文件定义三个服务器:

<servers>
  <server name="server-one" group="main-server-group">
  </server>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
  <server name="server-three" group="other-server-group" auto-start="false">
    <socket-bindings port-offset="250"/>
  </server>
</servers>

名为 server-one 的服务器实例与 main-server-group 关联,并且继承该服务器组指定的子系统配置和套接字绑定。名为 server-two 的服务器实例也与 main-server-group 关联,但也定义了套接字绑定 port-offset 值,因此不会与 server-one 使用的端口值冲突。名为 server-three 的服务器实例与 other-server-group 关联并使用该组的配置。它还定义 port-offset 值,并将 auto-start 设置为 false,以便此服务器在主机控制器启动时不启动。

可以使用管理 CLI 或管理控制台运行时选项卡来配置服务器

添加服务器

以下管理 CLI 命令可用于添加服务器:

/host=HOST_NAME/server-config=SERVER_NAME:add(group=SERVER_GROUP_NAME)
更新服务器

以下管理 CLI 命令可用于更新服务器属性:

/host=HOST_NAME/server-config=SERVER_NAME:write-attribute(name=ATTRIBUTE_NAME,value=VALUE)
删除服务器

以下管理 CLI 命令可用于移除服务器:

/host=HOST_NAME/server-config=SERVER_NAME:remove
服务器属性

服务器需要以下属性:

  • name :服务器的名称。
  • Group :来自域模型的服务器组名称。

服务器包括以下可选属性:

  • auto-start :主机控制器启动时是否应启动此服务器。
  • socket-binding-group :此服务器所属的套接字绑定组。
  • socket-binding-port-offset :添加到此服务器的套接字绑定组给出的端口值的偏移。
  • update-auto-start-with-server-status将 auto-start 属性更新为服务器的状态。
  • 接口 :可在服务器上使用的完全指定的命名网络接口的列表。
  • JVM :此服务器的 JVM 设置。如果未声明,则从父服务器组或主机继承设置。
  • path :指定文件系统路径列表。
  • system- property:在此服务器上要设置的系统属性列表。

8.4.3. 启动和停止服务器

您可以通过导航到 Runtime 选项卡并选择适当的主机或服务器组,从管理控制台对服务器执行各种操作,如启动、停止和重新加载。

以下命令可以使用管理 CLI 执行这些操作。

启动服务器

您可以在特定主机上启动单个服务器。

/host=HOST_NAME/server-config=SERVER_NAME:start

您可以启动指定服务器组中的所有服务器。

/server-group=SERVER_GROUP_NAME:start-servers
停止服务器

您可以在特定主机上停止单个服务器。

/host=HOST_NAME/server-config=SERVER_NAME:stop

您可以停止指定服务器组中的所有服务器。

/server-group=SERVER_GROUP_NAME:stop-servers
重新载入服务器

您可以在特定主机上重新加载单一服务器。

/host=HOST_NAME/server-config=SERVER_NAME:reload

您可以重新加载指定服务器组中的所有服务器。

/server-group=SERVER_GROUP_NAME:reload-servers
终止服务器

您可以中断指定服务器组中的所有服务器进程。

/server-group=SERVER_GROUP_NAME:kill-servers

8.5. 域控制器发现和故障转移

在设置受管域时,每一主机控制器必须配置必要的信息以联系域控制器。在 JBoss EAP 中,每一主机控制器可以配置多个选项,以查找域控制器。主机控制器迭代选项列表,直到成功为止。

如果主域控制器出现问题,备份主机控制器可以提升为域聚合器。这使得主机控制器在新的域控制器提升后自动故障转移到它。

8.5.1. 配置域发现选项

下例中演示了如何使用查找域控制器的多个选项配置主机控制器:

示例:具有多个域控制器选项的主机控制器

<domain-controller>
  <remote security-realm="ManagementRealm">
    <discovery-options>
      <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="172.16.81.100" port="${jboss.domain.master.port:9990}"/>
      <static-discovery name="backup" protocol="${jboss.domain.master.protocol:remote}" host="172.16.81.101" port="${jboss.domain.master.port:9990}"/>
    </discovery-options>
  </remote>
</domain-controller>

静态发现选项包括以下所需属性:

name
此域控制器发现选项的名称。
主机
远程域控制器的主机名。
port
远程域控制器的端口。

在上例中,第一个发现选项是预期成功的选项。第二个选项可用于故障转移情况。

8.5.2. 使用缓存域配置启动主机控制器

可以使用 --cached-dc 选项在不连接域控制器的情况下启动主机控制器;不过,主机控制器必须之前已从域控制器在本地缓存其域控制器的域控制器配置。使用这个 --cached-dc 选项启动主机控制器将缓存主机控制器的域控制器配置。

$ EAP_HOME/bin/domain.sh --host-config=host-slave.xml --cached-dc

这会在 EAP_HOME/domain/configuration/ 目录中创建一个 domain.cached-remote.xml 文件,该文件包含此主机控制器临时管理其当前服务器而无需域控制器连接所需的信息。

注意

默认情况下,使用 --cached-dc 选项仅缓存此主机控制器使用的配置,这意味着无法提升到整个域的域控制器。有关缓存整个域配置的信息,请参阅缓存域配置,以允许主机控制器充当域控制器。

如果在使用 --cached-dc 启动此主机控制器时域控制器不可用,主机控制器将开始使用 domain.cached-remote.xml 文件中保存的缓存配置。注意此文件必须存在,或者主机控制器将无法启动。

在这种状态下,主机控制器无法修改域配置,但可以启动服务器和管理部署。

在使用缓存的配置启动后,主机控制器将继续尝试重新连接到域控制器。域控制器变为可用后,主机控制器将自动重新连接它并同步域配置。请注意,一些配置更改可能要求您重新加载主机控制器才能生效。如果发生此情况,主机控制器上将记录警告。

8.5.3. 提升主机控制器以作为域控制器

如果主域控制器出现问题,您可以提升主机控制器以充当域控制器。主机控制器必须先将域配置从域控制器本地缓存 ,然后才能提升

缓存域配置

--backup 选项用于您可能希望成为域控制器的任何主机控制器。

$ EAP_HOME/bin/domain.sh --host-config=host-slave.xml --backup

这会在 EAP_HOME/domain/configuration/ 目录中创建一个 domain.cached-remote.xml 文件,其中包含整个域配置的副本。如果主机控制器重新配置为充当域控制器,则将使用此配置。

注意

ignore-unused-configuration 属性用于确定要缓存的特定主机的配置量。值 true 表示仅缓存与此主机控制器相关的配置,这不允许它接管域控制器。值 false 表示将缓存整个域配置。

--backup 参数将此属性默认为 false,以缓存整个域。但是,如果您在 host.xml 文件中设置了此属性,则会使用该值。

您也可以单独使用 --cached-dc 选项来创建域配置的副本,但必须在 host.xml 中将 ignore-unused-configuration 设置为 false 来缓存整个域。例如:

<domain-controller>
  <remote username="$local" security-realm="ManagementRealm" ignore-unused-configuration="false">
    <discovery-options>
      ...
    </discovery-options>
  </remote>
</domain-controller>
将主机控制器提升为域控制器
  1. 确保原先的域控制器已停止。
  2. 使用管理 CLI 连接主机控制器,该主机控制器将成为新的域控制器。
  3. 执行以下命令,将主机控制器配置为充当新的域控制器:

    /host=backup:write-attribute(name=domain-controller.local, value={})
  4. 执行以下命令,以重新加载主机控制器:

    reload --host=HOST_NAME

此主机控制器现在将充当域控制器。

8.6. 受管域设置

8.6.1. 在单一机器中设置受管域

您可以使用 jboss.domain.base.dir 属性在一台计算机上运行多个主机控制器。

重要

不支持将多个 JBoss EAP 主机控制器配置为单一计算机上的系统服务。

  1. 复制域控制器的 EAP_HOME/domain 目录。

    $ cp -r EAP_HOME/domain /path/to/domain1
  2. 复制主机控制器的 EAP_HOME/domain 目录。

    $ cp -r EAP_HOME/domain /path/to/host1
  3. 使用 /path/to /domain1 启动域控制器。

    $ EAP_HOME/bin/domain.sh --host-config=host-master.xml -Djboss.domain.base.dir=/path/to/domain1
  4. 使用 /path/to /host1 启动主机控制器。

    $ EAP_HOME/bin/domain.sh --host-config=host-slave.xml -Djboss.domain.base.dir=/path/to/host1 -Djboss.domain.master.address=IP_ADDRESS -Djboss.management.http.port=PORT
    注意

    在启动主机控制器时,您必须使用 jboss.domain.master.address 属性指定域控制器的地址。

    此外,由于此主机控制器在与域控制器相同的计算机上运行,因此您必须更改管理接口,使它不会与域控制器的管理接口冲突。此命令设置 jboss.management.http.port 属性。

以这种方式启动的每个实例将共享基础安装目录中的其余资源,如 EAP_HOME/modules/,但使用 jboss.domain.base.dir 指定的目录中的域配置。

8.6.2. 在两个机器中设置受管域

注意

您可能需要配置防火墙来运行此示例。

您可以在两台计算机上创建受管域,其中一台计算机是域控制器,另一台计算机是主机。如需更多信息,请参阅关于域控制器

  • ip1 = 域控制器的 IP 地址(Machine 1)
  • ip2 = 主机的 IP 地址(Machine 2)
在两个机器中创建受管域
  1. 在机器 1 上

    1. 添加管理用户,以便主机可由域控制器进行身份验证。

      使用 add-user.sh 脚本,为主机控制器 HOST_NAME 添加管理用户。确保对最后一个提示回答 yes,并注意提供的机密值。此 secret 值将在主机控制器配置中使用,其显示类似于下面这一行:

      <secret value="SECRET_VALUE" />
    2. 启动域控制器。

      指定 host-master.xml 配置文件,它为专用域控制器进行了预配置。此外,还要设置 jboss.bind.address.management 属性,使域控制器对其他计算机可见。

      $ EAP_HOME/bin/domain.sh --host-config=host-master.xml -Djboss.bind.address.management=IP1
  2. 在 Machine 2 上

    1. 使用用户凭据更新主机配置。

      编辑 EAP_HOME/domain/configuration/host-slave.xml,并设置主机名 HOST_NAME 和 secret 值 SECRET_VALUE

      <host xmlns="urn:jboss:domain:8.0" name="HOST_NAME">
        <management>
          <security-realms>
            <security-realm name="ManagementRealm">
              <server-identities>
                <secret value="SECRET_VALUE" />
              </server-identities>
              ...
    2. 启动主机控制器。

      指定 host-slave.xml 配置文件,它为从属主机控制器进行了预配置。此外,设置 jboss.domain.master.address 属性以连接域控制器,再设置 jboss.bind.address 属性来设置主机控制器绑定地址。

      $ EAP_HOME/bin/domain.sh --host-config=host-slave.xml  -Djboss.domain.master.address=IP1  -Djboss.bind.address=IP2

现在,您可以在启动时使用 --controller 参数指定域控制器地址,从而通过管理 CLI 管理域。

$ EAP_HOME/bin/jboss-cli.sh --connect --controller=IP1

或者,您可以从位于 http://IP1:9990 的 管理控制台管理该域。

8.7. 管理多个 JBoss EAP 版本

最新版本的 JBoss EAP 可以管理运行较早版本的 JBoss EAP 服务器和主机。根据您需要管理的 JBoss EAP 版本,请参见相应的部分。

8.7.1. 将 JBoss EAP 7.x 域控制器配置为管理员 JBoss EAP 6 实例

JBoss EAP 7.1 域控制器可以管理运行 JBoss EAP 6 的主机和服务器,只要它们是 JBoss EAP 6.2 或更高版本。

注意

对于管理不同补丁版本的 JBoss EAP 7.0 域控制器,无需任何配置更改。但是,JBoss EAP 7.0 域控制器必须运行一个等于或大于其管理的主机控制器上的版本的补丁版本。

完成以下任务,在 JBoss EAP 7 受管域中成功管理 JBoss EAP 6 实例。

完成这些任务后,您可以使用管理 CLI 从 JBoss EAP 7 域控制器管理 JBoss EAP 6 服务器和配置。请注意,JBoss EAP 6 主机将无法利用新的 JBoss EAP 7 功能,如批处理。

警告

由于管理控制台针对 JBoss EAP 的最新版本进行了优化,因此您不应用它来更新 JBoss EAP 6 主机、服务器和配置文件。在从 JBoss EAP 7 受管域管理 JBoss EAP 6 配置时,应改为使用管理 CLI。

8.7.1.1. 将 JBoss EAP 6 配置添加到 JBoss EAP 7 域控制器

若要让域控制器管理 JBoss EAP 6 服务器,您必须在 JBoss EAP 7 域配置中提供 JBoss EAP 6 配置详细信息。您可以通过将 JBoss EAP 6 配置文件、套接字绑定组和服务器组复制到 JBoss EAP 7 domain.xml 配置文件来实现 此操作。

如果与 JBoss EAP 7 配置中的现有名称有任何冲突,您需要重命名资源。为确保正确行为,还需要做一些额外的调整

以下步骤使用 JBoss EAP 6 默认 配置文件、standard -sockets 套接字绑定组和 main-server-group 服务器组。

  1. 编辑 JBoss EAP 7 domain.xml 配置文件。建议先备份此文件,然后再编辑。
  2. 将适用的 JBoss EAP 6 配置文件复制到 JBoss EAP 7 domain.xml 文件。

    此流程假定 JBoss EAP 6 默认 配置文件已复制并重命名为 eap6-default

    JBoss EAP 7 domain.xml

    <profiles>
      ...
      <profile name="eap6-default">
        ...
      </profile>
    </profiles>

  3. 添加此配置集使用的必要扩展。

    如果您的 JBoss EAP 6 配置文件使用 JBoss EAP 7 中不再存在的子系统,您必须将适当的扩展添加到 JBoss EAP 域配置中。

    JBoss EAP 7 domain.xml

    <extensions>
      ...
      <extension module="org.jboss.as.configadmin"/>
      <extension module="org.jboss.as.threads"/>
      <extension module="org.jboss.as.web"/>
    <extensions>

  4. 将适用的 JBoss EAP 6 套接字绑定组复制到 JBoss EAP 7 domain.xml 文件。

    此流程假定 JBoss EAP 6 标准套接字绑定 组已复制并重命名为 eap6-standard-sockets

    JBoss EAP 7 domain.xml

    <socket-binding-groups>
      ...
      <socket-binding-group name="eap6-standard-sockets" default-interface="public">
        ...
      </socket-binding-group>
    </socket-binding-groups>

  5. 将适用的 JBoss EAP 6 服务器组复制到 JBoss EAP 7 domain.xml 文件。

    此流程假定 JBoss EAP 6 main-server-group 服务器组已复制并重命名为 eap6-main-server-group。您还必须更新此服务器组,以使用 JBoss EAP 6 配置文件、eap6-default 和 JBoss EAP 6 套接字绑定组 eap6-standard-sockets

    JBoss EAP 7 domain.xml

    <server-groups>
      ...
      <server-group name="eap6-main-server-group" profile="eap6-default">
        ...
        <socket-binding-group ref="eap6-standard-sockets"/>
      </server-group>
    </server-groups>

8.7.1.2. 更新 JBoss EAP 6 配置文件的行为

根据 JBoss EAP 版本和所需行为,需要对 JBoss EAP 6 实例使用的配置集进行其他更新。根据现有 JBoss EAP 6 实例使用的子系统和配置,您可能需要进行其他更改。

启动 JBoss EAP 7 域控制器并启动其管理 CLI,以执行下列更新:这些示例假定 JBoss EAP 6 配置文件为 eap6-default

  • 移除 bean-validation 子系统:

    JBoss EAP 7 将 bean 验证功能从 ee 子系统移到其自身的子系统 bean-validation。如果 JBoss EAP 7 域控制器看到 legacy ee 子系统,它将添加新的 bean-validation 子系统。但是,JBoss EAP 6 主机将不会识别此子系统,因此必须移除它。

    JBoss EAP 7 域控制器 CLI

    /profile=eap6-default/subsystem=bean-validation:remove

  • 设置 CDI 1.0 行为。

    仅当您想要用于 JBoss EAP 6 服务器的 CDI 1.0 行为时,这才是必需的,而不是 JBoss EAP 7 中之后使用的 CDI 版本的行为。如果您希望 CDI 1.0 的行为,请对 weld 子系统进行以下更新:

    JBoss EAP 7 域控制器 CLI

    /profile=eap6-default/subsystem=weld:write-attribute(name=require-bean-descriptor,value=true)
    
    /profile=eap6-default/subsystem=weld:write-attribute(name=non-portable-mode,value=true)

  • 启用 JBoss EAP 6.2 的数据源统计信息.

    仅当您的配置文件供 JBoss EAP 6.2 服务器使用时才需要。JBoss EAP 6.3 引入了 支持 statistics 的属性,默认为 false,不收集统计数据;但是,JBoss EAP 6.2 的行为是收集统计数据。如果 JBoss EAP 6.2 主机和运行较新的 JBoss EAP 版本的主机使用此配置文件,则主机之间的行为会不一致,这是不允许的。因此,供 JBoss EAP 6.2 主机使用的配置文件应对其数据源进行以下更改:

    JBoss EAP 7 域控制器 CLI

    /profile=eap6-default/subsystem=datasources/data-source=ExampleDS:write-attribute(name=statistics-enabled,value=true)

8.7.1.3. 设置 JBoss EAP 6 服务器的服务器组

如果您重命名了服务器组,您需要更新 JBoss EAP 6 主机配置,以使用 JBoss EAP 7 配置中指定的新服务器组。本例使用 JBoss EAP 7 domain.xml 中指定的 eap6-main-server-group 服务器组。

JBoss EAP 6 host-slave.xml

<servers>
    <server name="server-one" group="eap6-main-server-group"/>
    <server name="server-two" group="eap6-main-server-group">
        <socket-bindings port-offset="150"/>
    </server>
</servers>

注意

与主机正在运行的版本相比,主机无法使用较新版本的 JBoss EAP 中引入的功能或配置设置。

8.7.1.4. 阻止 JBoss EAP 6 实例接收 JBoss EAP 7 更新

受管域中的域控制器将配置更新转发到其主机控制器。您必须使用 host-exclude 配置来指定应在特定版本中隐藏的资源。为您的 JBoss EAP 6 版本选择适当的预配置 host-exclude 选项: EAP62EAP63EAP64EAP64z

host -exclude 配置的 active- server-groups 属性指定特定版本使用的服务器组的列表。这些服务器组及其关联的配置文件、套接字绑定组和部署资源将提供给此版本的主机,但所有其他内容都将从这些主机中隐藏。

本例假定版本为 JBoss EAP 6.4.z,并将 JBoss EAP 6 服务器组 eap6-main-server-group 添加为活动服务器组。

JBoss EAP 7 域控制器 CLI

/host-exclude=EAP64z:write-attribute(name=active-server-groups,value=[eap6-main-server-group])

如果需要,您可以使用 active-socket-binding-groups 属性指定供服务器使用的额外套接字绑定组。这只适用于没有与 active-server-groups 中指定的服务器组关联的套接字绑定组

8.7.2. 将 JBoss EAP 7.3 域控制器配置为 JBoss EAP 的管理员次要版本

JBoss EAP 7.3 域控制器可以管理从之前的 JBoss EAP 次要版本运行的主机和服务器。

注意

对于管理位于不同补丁版本的 JBoss EAP 7.2 主机的 JBoss EAP 7.3 域控制器,您无需进行任何配置更改。但是,您必须在等于或大于其管理的主机控制器上的版本补丁版本上运行 JBoss EAP 7.2 域控制器。

完成以下任务,在 JBoss EAP 7.3 受管域中成功管理 JBoss EAP 7.2 实例。

完成这些任务后,您可以使用管理 CLI 从 JBoss EAP 7.3 域控制器管理 JBoss EAP 7.2 服务器和配置。

警告

由于管理控制台针对 JBoss EAP 的最新版本进行了优化,因此您必须使用 CLI 从 JBoss EAP 7.3 受管域管理 JBoss EAP 7.2 配置。不要使用管理控制台更新 JBoss EAP 7.2 主机、服务器和配置文件。

8.7.2.1. 将 JBoss EAP 7.2 配置添加到 JBoss EAP 7.3 域控制器

若要让域控制器管理 JBoss EAP 7.2 服务器,您必须在 JBoss EAP 7.3 域配置中提供 JBoss EAP 7.2 配置详细信息。您可以通过将 JBoss EAP 7.2 配置文件、套接字绑定组和服务器组复制到 JBoss EAP 7.3 domain.xml 配置文件来实现 此操作。

如果资源的名称与 JBoss EAP 7.3 配置中的资源名称冲突,则必须重命名资源。

以下步骤使用 JBoss EAP 7.2 默认 配置文件、standard -sockets 套接字绑定组和 main-server-group 服务器组。

先决条件

  • 您已将 JBoss EAP 7.2 默认配置 文件复制并重命名为 eap72-default
  • 您已将 JBoss EAP 7.2 标准套接字绑定 组复制并重命名为 eap72-standard-sockets
  • 您已将 JBoss EAP 7.2 main-server-group 服务器组复制并重命名为 eap72-main-server-group

    • 您已更新了服务器组,以使用 JBoss EAP 7.2 配置文件 eap72-default,再使用 JBoss EAP 7.2 套接字绑定组 eap72-standard-sockets

流程

  1. 编辑 JBoss EAP 7.3 domain.xml 配置文件。

    重要

    在编辑 文件之前,备份 JBoss EAP 7.3 domain.xml 配置文件。

  2. 将适用的 JBoss EAP 7.2 配置文件复制到 JBoss EAP 7.3 domain.xml 文件。例如:

    <profiles>
      ...
      <profile name="eap72-default">
        ...
      </profile>
    </profiles>
  3. 将适用的 JBoss EAP 7.2 套接字绑定组复制到 JBoss EAP 7.3 domain.xml 文件。例如:

    <socket-binding-groups>
      ...
      <socket-binding-group name="eap72-standard-sockets" default-interface="public">
        ...
      </socket-binding-group>
    </socket-binding-groups>
  4. 将适用的 JBoss EAP 7.2 服务器组复制到 JBoss EAP 7.3 domain.xml 文件。例如:

    <server-groups>
      ...
      <server-group name="eap72-main-server-group" profile="eap72-default">
        ...
        <socket-binding-group ref="eap72-standard-sockets"/>
      </server-group>
    </server-groups>
8.7.2.2. 设置 JBoss EAP7.2 服务器的服务器组

如果重命名了服务器组,您需要更新 JBoss EAP 7.2 主机配置,以使用 JBoss EAP 7.3 配置中指定的新服务器组。本例使用 JBoss EAP 7.3 domain.xml 中指定的 eap72-main-server-group 服务器组。

JBoss EAP 7.2 host-slave.xml

<servers>
    <server name="server-one" group="eap72-main-server-group"/>
    <server name="server-two" group="eap72-main-server-group">
        <socket-bindings port-offset="150"/>
    </server>
</servers>

注意

与主机正在运行的版本相比,主机无法使用较新版本的 JBoss EAP 中引入的功能或配置设置。

8.7.2.3. 阻止 JBoss EAP 7.2 实例接收 JBoss EAP 7.3 更新

受管域控制器将配置更新转发到其主机控制器,这样 JBoss EAP 7.2 主机不会接收专用于 JBoss EAP 7.3 的配置和资源。您必须配置 JBoss EAP 7.2 主机来忽略这些资源。您可以通过在 JBoss EAP 7.2 主机上设置 ignore-unused-configuration 属性来完成此操作。

注意

您也可以使用 host-exclude 配置来指示域控制器从运行某些 JBoss EAP 版本的主机中隐藏某些资源。有关如何使用 host-exclude 配置的示例,请参阅 从接收 JBoss EAP 7 更新中防止 JBoss EAP 6 实例。对于 JBoss EAP 7.2,您将使用 EAP72 host-exclude 选项。

在 JBoss EAP 7.2 主机控制器连接配置中,将 ignore-unused-configuration 属性设置为 true

JBoss EAP 7.2 host-slave.xml

<domain-controller>
    <remote security-realm="ManagementRealm" ignore-unused-configuration="true">
        <discovery-options>
            <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9990}"/>
        </discovery-options>
    </remote>
</domain-controller>

通过此设置,仅此主机使用的服务器组及其关联的配置文件、套接字绑定组和部署资源可供主机使用。所有其他资源都会被忽略。

8.8. 管理 JBoss EAP 配置文件

8.8.1. 关于配置集

JBoss EAP 使用配置文件来组织服务器可用的子系统。配置文件由一组可用的子系统以及各个子系统的特定配置组成。具有大量子系统的配置文件将产生具有大量功能的服务器。具有一组小、重点的子系统的配置集将获得较少的功能,但占用空间比较小。

JBoss EAP 附带五个预定义配置文件,应满足大多数用例的要求:

default
包括常用的子系统,如 日志记录安全性数据源、 infinispanwebservicesee、ejb3、事务等
ha
包含 默认配置 集中提供的子系统,同时添加了 jgroupsmodcluster 子系统以实现高可用性
full
包括 default 配置文件中提供的子系统,同时添加了 messaging-activemqiiop-openjdk 子系统
full-ha
包含 完整 配置集中提供的子系统,同时添加了 jgroupsmodcluster 子系统以实现高可用性
load-balancer
包括使用内置 mod_cluster 前端负载平衡器对其他 JBoss EAP 实例进行负载平衡所需的最小子系统。
注意

JBoss EAP 通过从现有配置文件的配置中删除子系统,提供手动禁用扩展或卸载驱动程序和其他服务的功能。然而,在大多数情况下,这是不必要的。由于 JBoss EAP 根据需要动态加载子系统,如果服务器或应用从未使用子系统,它就不会加载。

在现有配置文件不提供必要的功能的情况下,JBoss EAP 也提供定义自定义配置文件的功能。

8.8.2. 克隆配置集

JBoss EAP 允许您通过克隆现有的配置文件在受管域中创建新配置文件。这将创建原始配置文件的配置和子系统的副本。

可以使用管理 CLI 对所需配置集的 克隆操作进行克隆,以克隆配置集。

/profile=full-ha:clone(to-profile=cloned-profile)

您也可以从管理控制台克隆配置集,方法是选择要克隆的所需配置集并单击 Clone

8.8.3. 创建层次结构配置集

在受管域中,您可以创建配置文件层次结构。这可让您使用其他配置集可以继承的通用扩展来创建基础配置文件。

受管域在 domain.xml 中定义多个配置文件。如果多个配置集将相同的配置用于特定的子系统,您只需在一个位置进行配置,而不必配置不同的配置文件。父配置文件中的值不能被覆盖。

此外,每个配置文件都必须可自助使用。如果引用了元素或子系统,则必须在引用它的配置文件中定义它。

配置集可以使用 management CLI 在层次结构中包含其他配置集,方法是使用 list-add 操作并提供要包含的配置集。

/profile=new-profile:list-add(name=includes, value=PROFILE_NAME)

第 9 章 配置 JVM 设置

Java 虚拟机(JVM)设置的配置与独立 JBoss EAP 服务器或受管域中的 JBoss EAP 服务器不同。

对于独立 JBoss EAP 服务器实例,服务器启动进程在启动时将 JVM 设置传递到 JBoss EAP 服务器。可以在启动 JBoss EAP 之前从命令行声明它们,或者使用管理控制台中 Configuration 下的 System Properties 页面。

在受管域中,JVM 设置在 host.xmldomain.xml 配置文件中声明,可以在主机、服务器组或服务器级别上配置。

注意

系统属性必须在 JAVA_OPTS 中配置,以便在启动期间由 JBoss EAP 模块(如日志记录管理器)使用。

9.1. 为单机服务器配置 JVM 设置

单机 JBoss EAP 服务器实例的 JVM 设置可以在运行时声明,方法是在启动服务器之前设置 JAVA_OPTS 环境变量。

在 Linux 上设置 JAVA_OPTS 环境变量的示例如下所示:

$ export JAVA_OPTS="-Xmx1024M"

同一设置可用于 Microsoft Windows 环境:

set JAVA_OPTS="Xmx1024M"

或者,可以在 EAP_HOME/bin 文件夹中添加 JVM 设置到 standalone.conf 文件或 Windows Server 的 standalone.conf.bat,其中包含要传递给 JVM 的选项示例。

警告

设置 JAVA_OPTS 环境变量将覆盖 standalone.conf 中的默认值,这可能会造成 JBoss EAP 启动问题。

9.2. 为受管域配置 JVM 设置

在 JBoss EAP 受管域中,您可以在多个级别上定义 JVM 设置。您可以在特定主机上定义自定义 JVM 设置,然后将这些设置应用到服务器组或个别服务器实例。

默认情况下,服务器组和个别服务器将继承其父级的 JVM 设置,但您可以选择覆盖每个级别的 JVM 设置。

注意

domain .conf 或 domain. conf.bat 中的 JVM 设置应用于 JBoss EAP 主机控制器的 Java 进程,而非由该主机控制器控制的单个 JBoss EAP 服务器实例。

9.2.1. 在主机控制器上定义 JVM 设置

您可以在主机控制器上定义 JVM 设置,并将这些设置应用到服务器组或个别服务器上。JBoss EAP 附带 默认的 JVM 设置,但以下管理 CLI 命令演示了使用一些自定义 JVM 设置和选项创建名为 production_jvm 的新 JVM 设置:

/host=HOST_NAME/jvm=production_jvm:add(heap-size=2048m, max-heap-size=2048m, max-permgen-size=512m, stack-size=1024k, jvm-options=["-XX:-UseParallelGC"])

有关所有可用选项的说明,请参阅受管域 JVM 配置属性

您还可以导航到 RuntimeHosts,选择主机并单击 View,然后选择 JVM 选项卡,在 JBoss EAP 管理控制台中创建和编辑 JVM 设置。

这些设置存储在 host.xml 中的 <jvm> 标签内。

9.2.2. 将 JVM 设置应用到服务器组

在创建服务器组时,您可以指定组中的所有服务器都将使用的 JVM 配置。以下管理 CLI 命令演示了使用上例中显示的 production_jvm JVM 设置创建服务器组名称 groupA

/server-group=groupA:add(profile=default, socket-binding-group=standard-sockets)
/server-group=groupA/jvm=production_jvm:add

服务器组中的所有服务器都将从 production_jvm 继承 JVM 设置。

您也可以覆盖服务器组级别上的特定 JVM 设置。例如,要设置不同的堆大小,您可以使用以下命令:

/server-group=groupA/jvm=production_jvm:write-attribute(name=heap-size,value="1024m")

应用上述命令后,服务器组 groupA 将从 production_jvm 继承 JVM 设置,但堆大小除外,其值为 1024m

有关所有可用选项的说明,请参阅受管域 JVM 配置属性

您还可以导航到 RuntimeServer Groups,选择服务器组并单击 View,再选择 JVM 选项卡,以编辑 JBoss EAP 管理控制台中的服务器组 JVM 设置。

服务器组的这些设置存储在 domain.xml 中。

9.2.3. 将 JVM 设置应用到单个服务器

默认情况下,单个 JBoss EAP 服务器实例将继承它所属的服务器组的 JVM 设置。不过,您可以选择使用来自主机控制器的另一个完整的 JVM 设置定义覆盖继承的设置,或者选择覆盖特定的 JVM 设置。

例如,以下命令覆盖 上例中服务器组的 JVM 定义,并将 server-one JVM 设置 设置为默认 JVM 定义:

/host=HOST_NAME/server-config=server-one/jvm=default:add

此外,与服务器组类似,您可以在服务器级别上覆盖特定的 JVM 设置。例如,要设置不同的堆大小,您可以使用以下命令:

/host=HOST_NAME/server-config=server-one/jvm=default:write-attribute(name=heap-size,value="1024m")

有关所有可用选项的说明,请参阅受管域 JVM 配置属性

您还可以导航到 RuntimeHosts,选择主机,单击服务器上的 View,然后选择 JVM 选项卡,在 JBoss EAP 管理控制台中编辑服务器 JVM 设置。

单个服务器的这些设置存储在 host.xml 中。

9.3. 显示 JVM 状态

您可以从管理控制台查看单机或受管域服务器的 JVM 资源的状态,如堆和线程使用情况。虽然实时不显示统计数据,但您可以单击 Refresh 以提供 JVM 资源的最新概述。

显示独立 JBoss EAP 服务器的 JVM 状态:

  • 导航到 Runtime 选项卡,选择服务器,然后选择 Status

显示受管域中 JBoss EAP 服务器的 JVM 状态:

  • 导航到 RuntimeHosts,选择主机和服务器,然后选择 Status

这显示了以下堆使用情况信息:

Max
内存管理的最大内存量。
Used
已用内存量。
已提交
提交用于 Java 虚拟机的内存量。

也提供其他信息,如 JVM 正常运行时间和线程使用情况。

9.4. 调优 JVM

有关优化 JVM 性能的提示,请参阅性能调优指南中的 JVM 调优部分

第 10 章 邮件子系统

10.1. 配置邮件子系统

邮件 子系统允许您在 JBoss EAP 中配置邮件会话,然后使用 JNDI 将这些会话注入到应用中。它还支持使用 Jakarta EE @MailSessionDefinitions 注释和 @MailSessionDefinitions 注释进行配置。

配置要在应用程序中使用的 SMTP 服务器
  1. 使用以下 CLI 命令配置 SMTP 服务器和出站套接字绑定,例如:

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp:add(host=localhost, port=25)
    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp, username=user, password=pass, tls=true)
  2. 在应用程序中调用配置的邮件会话

    @Resource(lookup="java:jboss/mail/MySession")
    private Session session;

有关可用于配置邮件会话和服务器的属性的完整列表,请参阅邮件子系统属性。

10.2. 配置自定义传输

使用标准邮件服务器(如 POP3 或 IMAP)时,邮件服务器具有一组可以定义的属性。其中一些属性是必需的。其中最重要的是 出站-socket-binding-ref,它是对出站邮件套接字绑定的引用,通过主机地址和端口号定义。

对于使用多个主机进行负载平衡的用户,定义 出站-socket-binding-ref 可能不是最有效的解决方案。标准 Jakarta Mail 不支持使用多个主机进行负载平衡的主机配置。因此,使用多个主机进行此配置的用户需要实施自定义邮件传输。这些自定义邮件传输不需要 出站-socket-binding-ref,也允许自定义主机属性格式。

您可以从管理 CLI 配置自定义邮件传输。

  1. 添加新邮件会话并指定 JNDI 名称。

    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
  2. 添加出站套接字绑定并指定主机和端口。

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp-binding:add(host=localhost, port=25)
  3. 添加 SMTP 服务器并指定出站套接字绑定、用户名和密码。

    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding, username=user, password=pass, tls=true)
注意

您可以使用类似的步骤配置 POP3 或 IMAP 服务器。

POP3 服务器

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-pop3-binding:add(host=localhost, port=110)
/subsystem=mail/mail-session=mySession/server=pop3:add(outbound-socket-binding-ref=my-pop3-binding, username=user, password=pass)

IMAP 服务器

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-imap-binding:add(host=localhost, port=143)
/subsystem=mail/mail-session=mySession/server=imap:add(outbound-socket-binding-ref=my-imap-binding, username=user, password=pass)

要使用自定义服务器,请创建不含出站套接字绑定的自定义邮件服务器。您可以在自定义邮件服务器的属性定义中指定主机信息。例如:

/subsystem=mail/mail-session=mySession/custom=myCustomServer:add(username=user,password=pass, properties={"host" => "myhost", "my-property" =>"value"})

如果您定义了自定义协议,包含句点(.)的任何属性名都将被视为完全限定名称,并直接传递。任何其他格式,如 my-property, 都使用以下格式进行转换:mail .server-name.my-property

以下 XML 是包含自定义服务器的邮件配置示例:

<subsystem xmlns="urn:jboss:domain:mail:3.0">
   <mail-session name="default" jndi-name="java:jboss/mail/Default">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
   </mail-session>
    <mail-session name="myMail" from="user.name@domain.org" jndi-name="java:/Mail">
        <smtp-server password="password" username="user" tls="true" outbound-socket-binding-ref="mail-smtp"/>
        <pop3-server outbound-socket-binding-ref="mail-pop3"/>
        <imap-server password="password" username="nobody" outbound-socket-binding-ref="mail-imap"/>
    </mail-session>
    <mail-session name="custom" jndi-name="java:jboss/mail/Custom" debug="true">
        <custom-server name="smtp" password="password" username="username">
            <property name="host" value="mail.example.com"/>
        </custom-server>
    </mail-session>
    <mail-session name="custom2" jndi-name="java:jboss/mail/Custom2" debug="true">
        <custom-server name="pop3" outbound-socket-binding-ref="mail-pop3">
            <property name="custom-prop" value="some-custom-prop-value"/>
        </custom-server>
    </mail-session>
</subsystem>

10.3. 为密码使用凭证存储

除了在 mail 子系统中提供明文密码外,您还可以使用凭据存储来提供密码。elytron 子系统提供创建凭据存储的功能,以便在整个 JBoss EAP 中安全存放和使用您的密码。您可以在 How to Configure Server SecurityCredential Store 部分中找到有关创建和使用凭证存储的更多详细信息。

使用管理 CLI 使用凭证存储

/subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding, username=user, credential-reference={store=exampleCS, alias=mail-session-pw}, tls=true)

注意

以下是如何指定使用明文密码 的 credential-reference 属性的示例:

credential-reference={clear-text="MASK-Ewcyuqd/nP9;A1B2C3D4;351"}

使用管理控制台使用凭证存储

  1. 访问管理控制台。如需更多信息,请参阅管理控制台
  2. 导航到 ConfigurationSubsystemsMail
  3. 选择适当的邮件会话,再单击 View
  4. 选择"服务器"并选择相应的邮件服务器。您可以在 Credential Reference 选项卡中配置凭据引用,并在 Attributes 选项卡中编辑其他属性。

第 11 章 使用 JBoss EAP 记录

JBoss EAP 提供高度可配置的日志记录设施,供其自身的内部使用和部署的应用使用。logging 子系统基于 JBoss LogManager,除了 JBoss Logging 外还支持多个第三方应用日志框架。

11.1. 关于服务器日志记录

11.1.1. 服务器日志记录

默认情况下,所有 JBoss EAP 日志条目都写入 server.log 文件。该文件的位置取决于您的操作模式。

  • 单机服务器: EAP_HOME/standalone/log/server.log
  • 受管域: EAP_HOME/domain/servers/SERVER_NAME/log/server.log

此文件通常称为服务器日志。如需更多信息,请参阅 Root Logger 部分。

11.1.2. 引导日志记录

在启动期间,JBoss EAP 会记录有关 Java 环境和每个服务的启动信息。此日志在故障排除时非常有用。默认情况下,所有日志条目写入服务器日志中

启动日志记录配置在 logging.properties 配置文件中指定,该文件处于活动状态,直到 JBoss EAP 日志记录 子系统启动并接管为止。该文件的位置取决于您的操作模式。

  • 单机服务器: EAP_HOME/standalone/configuration/logging.properties
  • 受管域:

    域控制器和每一服务器都有一个 logging.properties 文件。

    • 域控制器: EAP_HOME/domain/configuration/logging.properties
    • Server: EAP_HOME/domain/servers/SERVER_NAME/data/logging.properties
警告

建议您不要直接编辑 logging.properties 文件,除非您了解需要它的特定用例。在进行此操作前,建议您从红帽客户门户网站创建一个支持问题单

在启动时会覆盖对 logging.properties 文件手动进行的更改。

11.1.2.1. 查看引导错误

对 JBoss EAP 进行故障排除时,首先要执行的步骤之一是检查启动过程中发生的错误。然后,您可以使用提供的信息来诊断和解决其原因。在对启动错误进行故障排除时,打开支持案例。

有两种方法可以查看引导错误,每种方法都各有优点。您可以使用 read- boot-errors 管理 CLI 命令检查 server.log 文件 或读取 引导错误。

检查服务器日志文件

您可以打开 server.log 文件,以查看启动期间发生的任何错误。

通过这个方法,您可以查看每个错误消息以及可能的相关信息,以便您获取有关为何发生错误的更多信息。它还允许您以纯文本格式查看错误消息。

  1. 在文件查看器中打开 server.log 文件。
  2. 导航到文件的末尾。
  3. 向后搜索 WFLYSRV0049 消息标识符,该标识符标记最新启动序列的开始。
  4. 从该刻搜索日志,以查找 for ERROR 实例。每个实例都将包含错误的描述并列出涉及的模块。

以下是 server.log 日志文件中的示例错误描述:

2016-03-16 14:32:01,627 ERROR [org.jboss.msc.service.fail] (MSC service thread 1-7) MSC000001: Failed to start service jboss.undertow.listener.default: org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
        at org.wildfly.extension.undertow.ListenerService.start(ListenerService.java:142)
        at org.jboss.msc.service.ServiceControllerImpl$StartTask.startService(ServiceControllerImpl.java:1948)
        at org.jboss.msc.service.ServiceControllerImpl$StartTask.run(ServiceControllerImpl.java:1881)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at java.lang.Thread.run(Thread.java:745)
Caused by: java.net.BindException: Address already in use
        ...
从管理 CLI 中读取引导错误

您可以在服务器启动时使用 read-boot-errors 管理 CLI 命令查看错误。

此方法不需要访问服务器文件系统,这对于负责监控没有文件系统访问权限的错误的任何人都有用。由于它是管理 CLI 命令,因此可以在 脚本中使用。例如,您可以编写一个启动多个 JBoss EAP 实例的脚本,然后检查启动时发生的错误。

运行以下管理 CLI 命令:

/core-service=management:read-boot-errors

将列出启动过程中出现的任何错误。

{
    "outcome" => "success",
    "result" => [
        {
            "failed-operation" => {
                "operation" => "add",
                "address" => [
                    ("subsystem" => "undertow"),
                    ("server" => "default-server"),
                    ("http-listener" => "default")
                ]
            },
            "failure-description" => "{\"WFLYCTL0080: Failed services\" => {\"jboss.undertow.listener.default\" => \"org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
    Caused by: java.net.BindException: Address already in use\"}}",
            "failed-services" => {"jboss.undertow.listener.default" => "org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
    Caused by: java.net.BindException: Address already in use"}
        }
        ...
    ]
}

11.1.3. 垃圾收集器日志记录

垃圾回收日志记录将所有垃圾回收活动记录到纯文本日志文件。这些日志文件可用于诊断目的。默认情况下,除 IBM Java 开发工具包外,所有支持的配置上的 JBoss EAP 单机服务器都启用了垃圾回收日志记录。

垃圾收集日志的位置为 EAP_HOME/standalone/log/gc.log.DIGIT.current。垃圾回收日志的收集日志限制为 3 MB,最多五个文件会被轮转。

强烈建议启用垃圾回收日志记录,因为垃圾回收日志记录在故障排除中非常有用,它的开销应最小。但是,您可以在启动服务器前将 GC_LOG 变量设置为 false,为单机服务器禁用垃圾回收日志。例如:

$ export GC_LOG=false
$ EAP_HOME/bin/standalone.sh

11.1.4. 默认日志文件位置

为默认日志记录配置创建以下日志文件:默认配置使用定期日志处理程序写入服务器日志文件。

表 11.1. 单机服务器的默认日志文件
日志文件描述

EAP_HOME/standalone/log/server.log

包含服务器日志消息,包括服务器启动消息。

EAP_HOME/standalone/log/gc.log.DIGIT.current

包含垃圾回收详细信息。

表 11.2. 受管域的默认日志文件
日志文件描述

EAP_HOME/domain/log/host-controller.log

包含与主机控制器启动相关的日志消息。

EAP_HOME/domain/log/process-controller.log

包含与进程控制器启动相关的日志消息。

EAP_HOME/domain/servers/SERVER_NAME/log/server.log

包含指定服务器的日志消息,包括服务器启动消息。

11.1.5. 设置服务器的默认位置

您可以通过在相应的启动配置文件中设置 JVM 属性来配置 JBoss EAP 的默认区域设置。启动配置文件是单机服务器的 EAP_HOME/bin/standalone.conf,或者受管域的 EAP_HOME/bin/domain.conf

注意

对于 Windows Server,JBoss EAP 启动配置文件为 standalone.conf.batdomain.conf.bat

已国际化和本地化的日志消息将使用此默认区域设置。有关创建国际化日志消息的信息,请参见 JBoss EAP 开发指南

设置语言

通过使用 JAVA_OPTS 变量设置 user.language 属性,以指定语言。例如,向启动配置文件添加以下行以设置法语区域设置:

JAVA_OPTS="$JAVA_OPTS -Duser.language=fr"

已国际化和本地化的日志消息现在将以法语输出。

设置语言和地区

除了语言之外,还可能需要通过设置 用户.国家属性来指定国家/ 地区。例如,在启动配置文件中添加以下行,为巴西设置葡萄牙区域设置:

JAVA_OPTS="$JAVA_OPTS -Duser.language=pt -Duser.country=BR"

已国际化和本地化的日志消息现在将在巴西葡萄牙语中输出。

使用 org.jboss.logging.locale 属性设置服务器位置

您可以配置 org.jboss.logging.locale 属性,以覆盖使用 JBoss Logging 记录的消息的区域设置,包括来自 JBoss EAP 的所有消息及其拥有的依赖关系。其他依赖项(如 JSF)无法获得覆盖的区域设置。

若要使用不同于系统默认值的区域设置启动 JBoss EAP 服务器,您可以编辑 EAP_HOME/bin/standalone.confEAP_HOME/bin/domain.conf 文件,具体取决于您的操作模式,并附加以下命令来为所需的区域设置 JVM 参数:属性的值必须以 BCP 47 格式指定。例如,要设置巴西葡萄牙语,请使用 pt-BR。

JAVA_OPTS="$JAVA_OPTS -Dorg.jboss.logging.locale=pt-BR"

11.2. 查看日志文件

查看服务器和应用程序日志非常重要,以帮助诊断错误、性能问题和其他问题。有些用户可能更喜欢直接在服务器文件系统中查看日志。对于无法直接访问文件系统或更喜欢图形界面的用户,JBoss EAP 允许您从管理控制台查看日志。您还可以使用管理 CLI 查看日志。

若要从其中一个管理接口访问日志,它必须位于服务器的 jboss.server.log.dir 属性指定的目录中,并且定义为文件、定期轮转、大小轮转或定期轮转日志处理程序。RBAC 角色分配也会被遵守,因此登录管理控制台或 CLI 的用户只能查看被授权访问的日志。

从管理控制台查看日志

您可以直接从管理控制台查看日志。

  1. 选择 Runtime 选项卡,然后选择相应的服务器。
  2. 选择 Log Files,然后从列表中选择一个日志文件。
  3. 单击 View 查看和搜索日志内容,或者从下拉菜单中选择 Download 以将日志文件下载到本地文件系统。
警告

管理控制台日志查看器不应成为文本编辑器,用于查看非常大的日志文件,例如大于 100MB。系统会提示您确认您是否尝试打开大于 15MB 的日志文件。在管理控制台中打开一个非常大的文件可能会使浏览器崩溃,因此您应始终在本地下载大型日志文件,并在文本编辑器中打开这些文件。

通过管理 CLI 查看日志

您可以使用 read- log-file 命令从管理 CLI 中读取 日志文件的内容。默认情况下,这会显示指定日志文件的最后 10 行。

/subsystem=logging/log-file=LOG_FILE_NAME:read-log-file
注意

在受管域中,在此命令前加上 /host=HOST_NAME/server=SERVER_NAME

您可以使用以下参数自定义日志输出:

编码
用于读取文件的字符编码。
要从文件中读取的行数。值 -1 将读取所有日志行。默认值为 10
skip
阅读前要跳过的行数。默认为 0
tail
是否从文件末尾读取 .默认值为 true

例如,以下管理 CLI 命令从 server.log 日志文件顶部读取前 5 行:

/subsystem=logging/log-file=server.log:read-log-file(lines=5,tail=false)

这会生成以下输出:

{
    "outcome" => "success",
    "result" => [
        "2016-03-24 08:49:26,612 INFO  [org.jboss.modules] (main) JBoss Modules version 1.5.1.Final-redhat-1",
        "2016-03-24 08:49:26,788 INFO  [org.jboss.msc] (main) JBoss MSC version 1.2.6.Final-redhat-1",
        "2016-03-24 08:49:26,863 INFO  [org.jboss.as] (MSC service thread 1-7) WFLYSRV0049: JBoss EAP 7.0.0.GA (WildFly Core 2.0.13.Final-redhat-1) starting",
        "2016-03-24 08:49:27,973 INFO  [org.jboss.as.server] (Controller Boot Thread) WFLYSRV0039: Creating http management service using socket-binding (management-http)",
        "2016-03-24 08:49:27,994 INFO  [org.xnio] (MSC service thread 1-1) XNIO version 3.3.4.Final-redhat-1"
    ]
}

11.3. 关于 Logging 子系统

JBoss EAP logging 子系统使用 日志类别和日志 处理程序 系统进行配置。日志类别定义要捕获的消息。日志处理程序定义如何处理这些消息,例如写入磁盘或发送到控制台。

日志记录配置集允许创建唯一的日志配置集合,并将其分配给独立于任何其他日志配置的应用程序。记录配置文件的配置与主要的 logging 子系统几乎相同。

11.3.1. 根日志记录器

JBoss EAP root 日志记录器捕获指定日志级别或更高级别的所有日志消息,发送到未被日志类别捕获的服务器。

默认情况下,根日志记录器配置为使用控制台和定期日志处理程序。定期日志处理程序配置为写入 server.log 文件。此文件通常称为服务器日志。

如需更多信息,请参阅配置 Root 日志器

11.3.2. 日志类别

日志类别定义要捕获的一组日志消息,以及一个或多个处理消息的日志处理程序。

要捕获的日志消息由指定的 Java 原始软件包和日志级别定义。来自该软件包及日志级别或更高级别的类的消息将被日志类别捕获并发送到指定的日志处理程序。

注意

虽然日志类别通常是 Java 软件包和类名称,但可以是 Logger.getLogger(LOGGER_NAME) 方法指定的任何名称。

日志类别可以选择使用根日志记录器的日志处理程序,而不使用自己的处理程序。

如需更多信息,请参阅配置日志类别

11.3.3. 日志处理程序

日志处理程序定义如何记录捕获的日志消息。可用的日志处理程序类型有 console、fileperiodic、sizeperiodic size、syslog、customasync

注意

日志处理程序必须添加到至少一个日志记录器才能处于活动状态。

日志处理程序类型
控制台(Console)
控制台日志处理程序将日志消息写入主机操作系统的标准输出、stdout 或标准 错误、stderr、流。在通过命令行提示符运行 JBoss EAP 时,将显示这些消息。除非操作系统配置为捕获标准输出或标准错误流,否则不会保存来自控制台日志处理程序的消息。
File
文件日志处理程序将日志消息写入到指定的文件中。
periodic
定期日志处理程序将日志消息写入到指定的文件,直到指定的时间段已过。过了时间段后,通过附加指定的时间戳来重命名文件,处理程序将继续写入到具有原始名称的新创建的日志文件中。
Size
大小日志处理程序将日志消息写入到指定的文件,直到文件达到指定的大小。当文件达到指定的大小时,将使用数字后缀对其进行重命名,处理程序将继续写入到具有原始名称的新创建的日志文件中。每个大小日志处理程序都必须以这种方式指定要保留的最大文件数。
定期大小

定期大小日志处理程序将日志消息写入到指定文件,直到文件达到指定的大小或指定的时间段已过。然后,文件重命名为,处理程序继续写入到具有原始名称的新创建的日志文件。

这是定期日志处理程序和大小日志处理程序的组合,并支持它们的组合属性。

Syslog
系统日志处理程序可用于发送消息到远程记录服务器。这使得多个应用可以发送其日志消息到同一服务器,它们都可以在上面一起解析。
socket
套接字日志处理程序可用于通过套接字发送日志消息到远程记录服务器。这可以是 TCP 或 UDP 套接字。
Custom
通过自定义日志处理程序,您可以配置已实施的新类型的日志处理程序。自定义处理程序必须作为 Java 类实施,扩展 java.util.logging.Handler 并包含在模块中。您还可以使用 Log4J 附加程序作为自定义日志处理程序。
Async
异步日志处理程序是一种打包程序日志处理程序,可为一个或多个其他日志处理程序提供异步行为。这可用于日志处理程序,它们可能具有较高的延迟或其他性能问题,例如将日志文件写入网络文件系统。

有关配置每个日志处理程序的详情,请参考 配置日志处理程序 部分。

11.3.4. 日志级别

日志级别是一个枚举的值,指示日志消息的性质及严重性。作为开发人员,您可以使用所选日志记录框架的适当方法指定给定日志消息级别,以发送消息。

JBoss EAP 支持受支持的应用程序日志记录框架使用的所有日志级别。最常使用的从最低到最高日志级别为 TRACEDEBUGINFOWARNERRORFATAL

日志类别和处理程序使用日志级别来限制它们所负责的消息。每个日志级别都有一个已分配的数字值,表示它相对于其他日志级别的顺序。日志级别和处理程序分配有日志级别,它们仅处理该级别或更高级别的日志消息。例如,级别为WARN的日志处理程序将仅记录 levels WARN ERRORFATAL 的消息。

支持的日志级别
日志级别描述

ALL

Integer.MIN_VALUE

提供所有日志消息.

FINEST

300

-

FINER

400

-

TRACE

400

TRACE 级别日志消息提供关于应用的运行状态的详细信息,通常仅在调试期间捕获。

DEBUG

500

DEBUG 级别的日志消息指示各个请求或应用活动的进度,通常仅在调试期间捕获。

OK

500

-

CONFIG

700

-

INFO

800

INFO 级别的日志消息指示应用的整体进度。通常用于应用程序启动、关闭和其他主要生命周期事件。

WARN

900

WARN 级别的日志消息指出的情况是不出错,但不被视为理想情况。WARN 日志消息可能会指示将来可能导致错误的情况。

WARNING

900

-

ERROR

1000

ERROR 级别日志消息指出发生了阻止当前活动或请求完成但不会阻止应用运行的错误。

严重性

1000

-

FATAL

1100

FATAL 级别的日志消息指示可能导致关键服务故障和应用关闭的事件,并可能导致 JBoss EAP 关闭。

OFF

Integer.MAX_VALUE

不显示任何日志消息。

注意

ALL 是最低日志级别,包含所有日志级别的消息。这可提供最多的日志量。

FATAL 是最高级别,仅包含该级别的消息。这可提供最小的日志量。

11.3.5. 日志格式

格式器用于格式化日志消息。可以使用 named-formatter 属性将格式化器分配到日志记录处理程序。如需有关日志记录处理程序配置的更多信息,请参阅 配置日志处理程序

logging 子系统包括四种格式:

Pattern Formatter

模式格式器用于以纯文本格式记录日志消息。除了将 formatter 用作日志处理程序 的 named-formatter 属性外,它还可用作 formatter 属性,而无需先创建 formatter 资源。有关模式语法的更多信息,请参阅 Pattern Formatter 的格式字符

有关如何配置模式格式化器的详情,请参阅配置模式格式器。

JSON Formatter

JSON 格式器用于在 JSON 中格式化日志消息。

如需有关如何配置 JSON 格式器的信息,请参阅配置 JSON 日志格式器

XML Formatter

XML 日志格式器用于在 XML 中格式化日志消息。

有关如何配置 XML 日志格式器的详情,请参阅配置 XML 日志格式器。

自定义格式

用于处理程序的自定义格式器。请注意,大多数日志记录都采用 printf 格式格式化。格式器可能需要调用 org.jboss.logmanager.ExtLogRecord#getFormattedMessage() 才能正确格式化消息。

有关如何配置自定义日志格式器的详情,请参阅配置自定义日志格式器。

11.3.6. filter Expressions

使用 filter-spec 属性配置的过滤器表达式用于根据各种条件记录日志消息。过滤器检查始终在原始未格式化的消息上完成。您可以为日志记录器或处理程序包含过滤器,但日志记录器过滤器优先于处理程序上放置的过滤器。

注意

为根日志记录器指定的 filter-spec 不会被其他日志记录器继承。相反,每个处理程序都必须指定 filter-spec

表 11.3. Logging 的 filter Expressions
filter Expression描述

accept

接受所有日志消息。

deny

拒绝所有日志消息。

不 [filter 表达式]

返回单个过滤器表达式倒置的值。例如:

not(match("WFLY"))

all[filter 表达式]

从以逗号分隔的过滤器表达式列表中返回串联值。例如:

all(match("WFLY"),match("WELD"))

任意[filter 表达式]

从以逗号分隔的过滤器表达式列表中返回一个值。例如:

any(match("WFLY"),match("WELD"))

levelChange[level]

使用指定的级别更新日志记录。例如:

levelChange(WARN)

levels[levels]

使用逗号分隔级别列表中列出的级别过滤日志消息。例如:

级别(DEBUG、INFO、WARN、ERROR)

levelRange[minLevel,maxLevel]

过滤指定级别的日志消息。[] 字符用于表示包含的级别。 字符用于表示专用级别。例如:

  • levelRange[INFO,ERROR]

    • 最小级别必须大于或等于 INFO,最高级别必须小于或等于 ERROR
  • levelRange[DEBUG,ERROR)

    • 最小级别必须大于或等于 DEBUG,最高级别必须小于 ERROR

match["pattern"]

使用提供的正则表达式过滤日志消息。例如:

match("WFLY\d+")

substitute["pattern","replacement value"]

使用替换文本(第二个参数)替换第一个匹配模式的过滤器(第一个参数)。例如:

substitute("WFLY","EAP")

substituteAll["pattern","replacement value"]

将模式的所有匹配项(第一个参数)替换为替换文本(第二个参数)的过滤器。例如:

substituteAll("WFLY","EAP")

注意

在使用管理 CLI 配置过滤器表达式时,请确保在过滤器文本中转义逗号和引号,以便该值作为字符串正确处理。您必须在逗号和引号前加上反斜杠(\),并将整个表达式括在引号中。以下是正确转义 replace All("WFLY","YLFW"的示例

/subsystem=logging/console-handler=CONSOLE:write-attribute(name=filter-spec, value="substituteAll(\"WFLY\"\,\"YLFW\")")

11.3.7. 隐式日志记录依赖项

默认情况下,JBoss EAP 日志记录 子系统为部署添加隐式日志记录 API 依赖项。您可以使用 add-logging-api-dependencies 属性(默认为 true )来控制这些隐式依赖项是否添加到部署中。

使用管理 CLI,您可以将 add-logging-api-dependencies 属性 设置为 false,从而不会将隐式日志记录 API 依赖项添加到部署中。

/subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)

有关 logging 子系统隐式依赖项的信息,请参阅 JBoss EAP 开发指南 中的 Implicit Module 依赖项 部分。

11.4. 配置日志类别

本节介绍如何使用管理 CLI 配置日志类别。您还可以使用管理控制台配置日志类别,方法是导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 Categories

在配置日志类别时要执行的主要任务有:

重要

如果您要为日志记录配置集配置此日志类别,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加日志类别

日志类别名称由 Java 原始软件包定义。来自该软件包中类的消息将捕获,只要它们遵循其他设置,例如日志级别。

/subsystem=logging/logger=LOG_CATEGORY:add
配置日志类别设置

根据您的需要,您可能需要设置一个或多个以下日志类别属性:有关可用日志类别属性及其描述的完整列表,请参阅 Log Category Attributes

  • 设置日志级别。

    为日志级别设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=level,value=LEVEL)
  • 设置此类别是否应使用根日志记录器的日志处理程序。

    默认情况下,日志类别除使用根日志记录器的处理程序外,还会使用自己的处理程序。如果日志类别应仅使用其分配的处理程序,则将 use-parent-handlers 属性设为 false

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=use-parent-handlers,value=USE_PARENT_HANDLERS)
  • 设置过滤器表达式。

    设置表达式,以过滤日志类别的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

分配处理程序

将日志处理程序分配到日志类别。

/subsystem=logging/logger=LOG_CATEGORY:add-handler(name=LOG_HANDLER_NAME)
删除日志类别

可以使用 remove 操作删除日志类别。

/subsystem=logging/logger=LOG_CATEGORY:remove

11.5. 配置日志处理程序

日志处理程序定义如何记录捕获的日志消息。有关配置您需要的日志处理程序类型,请参见相应的部分。

11.5.1. 配置控制台日志处理程序

本节介绍如何使用管理 CLI 配置控制台日志处理程序。您还可以使用管理控制台配置控制台日志处理程序,方法是导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerConsole Handler

在配置控制台日志处理程序时要执行的主要任务有:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加控制台日志处理程序
/subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:add
配置控制台日志处理程序设置

根据您的需要,您可能需要设置以下一个或多个控制台日志处理程序属性:有关可用控制台日志处理程序属性及其描述的完整列表,请参阅 Console Log Handler Attributes

  • 设置日志级别。

    为处理程序设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • 设置目标。

    设置处理程序的目标,可以是 System.out、System.errconsole 之一。默认值为 System.out

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=target,value=TARGET)
  • 设置编码.

    设置处理程序的编码,如 utf-8

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • 设置日志格式器。

    设置处理程序的格式字符串。例如,默认格式字符串为 %d{HH:mm:ss,SSS} %-5p [%c](%t)%s%e%n。务必在引号中包含 FORMAT 值。

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    注意
  • 设置自动刷新.

    设置是否在每次写入后自动清空。默认值为 true

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • 设置过滤器表达式。

    设置表达式,以过滤处理程序的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

将控制台日志处理程序分配给日志记录器

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将控制台日志处理程序分配到根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=CONSOLE_HANDLER_NAME)

以下管理 CLI 命令将控制台日志处理程序分配到其名称由 CATEGORY 指定的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=CONSOLE_HANDLER_NAME)
删除控制台日志处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器或异步日志处理程序,则无法移除日志处理程序。

/subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:remove

11.5.2. 配置文件日志处理程序

本节介绍如何使用管理 CLI 配置文件日志处理程序。您还可以使用管理控制台配置文件日志处理程序,方法是导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerFile Handler

在配置文件日志处理程序时要执行的主要任务有:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加文件日志处理程序

在添加文件日志处理程序时,您必须使用 file 属性指定文件路径,该属性由 path 和 relative -to 属性组成。使用 path 属性设置日志的文件路径,包括名称,如 my-log.log。(可选)使用 relative-to 属性设置 路径 相对于指定路径,如 jboss.server.log.dir

/subsystem=logging/file-handler=FILE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH})
配置文件日志处理程序设置

根据您的需要,您可能需要设置以下一个或多个文件日志处理程序属性:有关可用文件日志处理程序属性及其描述的完整列表,请参阅 File Log Handler Attributes

  • 设置日志级别。

    为处理程序设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • 设置附加行为。

    默认情况下,JBoss EAP 将在服务器重启时将日志消息附加到同一文件中。您可以将 append 属性设置为 false,使其在服务器重启时覆盖文件。

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • 设置编码.

    设置处理程序的编码,如 utf-8

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • 设置日志格式器。

    设置处理程序的格式字符串。例如,默认格式字符串为 %d{HH:mm:ss,SSS} %-5p [%c](%t)%s%e%n。务必在引号中包含 FORMAT 值。

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    注意
  • 设置自动刷新.

    设置是否在每次写入后自动清空。默认值为 true

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • 设置过滤器表达式。

    设置表达式,以过滤处理程序的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

将文件日志处理程序分配给日志器

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将文件日志处理程序分配到根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=FILE_HANDLER_NAME)

以下管理 CLI 命令将文件日志处理程序分配到其名称由 CATEGORY 指定的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=FILE_HANDLER_NAME)
删除文件日志处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器或异步日志处理程序,则无法移除日志处理程序。

/subsystem=logging/file-handler=FILE_HANDLER_NAME:remove

11.5.3. 配置定期轮转日志处理程序

本节介绍如何使用管理 CLI 配置定期轮转日志处理程序。您还可以使用管理控制台配置定期日志处理程序,方法是导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerPeriodic Handler

用于配置定期日志处理器的主要任务有:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加定期日志处理程序

在添加定期日志处理程序时,您必须使用 file 属性指定文件路径,该属性由 path 和 relative -to 属性组成。使用 path 属性设置日志的文件路径,包括名称,如 my-log.log。(可选)使用 relative-to 属性设置 路径 相对于指定路径,如 jboss.server.log.dir

您还必须使用 suffix 属性为轮转日志设置后缀。这的格式必须可以被 java.text.SimpleDateFormat(.yyyyyy-MM-dd-HH) 理解。轮转期间会基于此后缀自动计算。

/subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH},suffix=SUFFIX)
配置定期日志处理程序设置

根据您的需要,您可能需要设置以下一个或多个定期日志处理程序属性:有关可用定期日志处理程序属性及其描述的完整列表,请参阅 Periodic Log Handler Attributes

  • 设置日志级别。

    为处理程序设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • 设置附加行为。

    默认情况下,JBoss EAP 将在服务器重启时将日志消息附加到同一文件中。您可以将 append 属性设置为 false,使其在服务器重启时覆盖文件。

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • 设置编码.

    设置处理程序的编码,如 utf-8

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • 设置日志格式器。

    设置处理程序的格式字符串。例如,默认格式字符串为 %d{HH:mm:ss,SSS} %-5p [%c](%t)%s%e%n。务必在引号中包含 FORMAT 值。

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    注意
  • 设置自动刷新.

    设置是否在每次写入后自动清空。默认值为 true

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • 设置过滤器表达式。

    设置表达式,以过滤处理程序的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

将定期日志处理程序分配给日志记录器

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将定期日志处理程序分配到根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=PERIODIC_HANDLER_NAME)

以下管理 CLI 命令将定期日志处理程序分配到其名称由 CATEGORY 指定的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=PERIODIC_HANDLER_NAME)
删除定期日志处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器或异步日志处理程序,则无法移除日志处理程序。

/subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:remove

11.5.4. 配置大小轮转日志处理程序

本节介绍如何使用管理 CLI 配置大小轮转日志处理程序。您还可以使用管理控制台配置大小日志处理程序,方法是导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerSize Handler

在配置大小日志处理器时要执行的主要任务有:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加大小日志处理程序

在添加大小日志处理程序时,您必须使用 file 属性指定文件路径,该属性由 path 和 relative -to 属性组成。使用 path 属性设置日志的文件路径,包括名称,如 my-log.log。(可选)使用 relative-to 属性设置 路径 相对于指定路径,如 jboss.server.log.dir

/subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH})
配置大小日志处理程序设置

根据您的需要,您可能需要设置以下一个或多个大小日志处理程序属性:有关可用大小日志处理程序属性及其描述的完整列表,请参阅 Size Log Handler Attributes

  • 设置日志级别。

    为处理程序设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • 设置轮转日志的后缀。

    设置后缀字符串,格式为 java.text.SimpleDateFormat,如 .yyyyy-MM-dd-HH。轮转期间会基于此后缀自动计算。

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=suffix, value=SUFFIX)
  • 设置轮转大小。

    设置在轮转之前文件能够达到的最大大小。默认值为 2m (2 MB)。

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=rotate-size, value=ROTATE_SIZE)
  • 设置要保留的最大备份日志数。

    设置要保留的备份数。默认值为 1

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=max-backup-index, value=MAX_BACKUPS)
  • 设置是否在引导时轮转日志。

    默认情况下,服务器重启时不会创建新的日志文件。您可以将此项设置为 true,以在服务器重启时轮转日志。

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=rotate-on-boot, value=ROTATE_ON_BOOT)
  • 设置附加行为。

    默认情况下,JBoss EAP 将在服务器重启时将日志消息附加到同一文件中。您可以将 append 属性设置为 false,使其在服务器重启时覆盖文件。

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • 设置编码.

    设置处理程序的编码,如 utf-8

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • 设置日志格式器。

    设置处理程序的格式字符串。例如,默认格式字符串为 %d{HH:mm:ss,SSS} %-5p [%c](%t)%s%e%n。务必在引号中包含 FORMAT 值。

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    注意
  • 设置自动刷新.

    设置是否在每次写入后自动清空。默认值为 true

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • 设置过滤器表达式。

    设置表达式,以过滤处理程序的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

将 Size Log Handler 分配给日志器

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将大小日志处理程序分配到根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=SIZE_HANDLER_NAME)

以下管理 CLI 命令将大小日志处理程序分配给名称由 CATEGORY 指定的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=SIZE_HANDLER_NAME)
删除大小日志处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器或异步日志处理程序,则无法移除日志处理程序。

/subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:remove

11.5.5. 配置 Periodic 大小轮转日志处理程序

本节介绍如何使用管理 CLI 配置定期大小轮转日志处理程序。您还可以通过使用管理控制台配置定期大小日志处理程序,导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerPeriodic Size Handler

用于配置定期大小日志处理器的主要任务有:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加定期大小日志处理程序

在添加定期大小日志处理程序时,您必须使用 file 属性指定文件路径,该属性由 path 和 relative -to 属性组成。使用 path 属性设置日志的文件路径,包括名称,如 my-log.log。(可选)使用 relative-to 属性设置 路径 相对于指定路径,如 jboss.server.log.dir

您还必须使用 suffix 属性为轮转日志设置后缀。这的格式必须可以被 java.text.SimpleDateFormat(.yyyyyy-MM-dd-HH) 理解。轮转期间会基于此后缀自动计算。

/subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH},suffix=SUFFIX)
配置定期大小日志处理程序设置

根据您的需要,您可能需要设置以下一个或多个定期大小日志处理程序属性:有关可用定期大小日志处理程序属性及其描述的完整列表,请参阅 Periodic Sandler Attributes

  • 设置日志级别。

    为处理程序设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • 设置轮转大小。

    设置在轮转之前文件能够达到的最大大小。默认值为 2m (2 MB)。

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=rotate-size, value=ROTATE_SIZE)
  • 设置要保留的最大备份日志数。

    设置要保留的备份数。默认值为 1

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=max-backup-index, value=MAX_BACKUPS)
  • 设置是否在引导时轮转日志。

    默认情况下,服务器重启时不会创建新的日志文件。您可以将此项设置为 true,以在服务器重启时轮转日志。

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=rotate-on-boot, value=ROTATE_ON_BOOT)
  • 设置附加行为。

    默认情况下,JBoss EAP 将在服务器重启时将日志消息附加到同一文件中。您可以将 append 属性设置为 false,使其在服务器重启时覆盖文件。

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • 设置编码.

    设置处理程序的编码,如 utf-8

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • 设置日志格式器。

    设置处理程序的格式字符串。例如,默认格式字符串为 %d{HH:mm:ss,SSS} %-5p [%c](%t)%s%e%n。务必在引号中包含 FORMAT 值。

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    注意
  • 设置自动刷新.

    设置是否在每次写入后自动清空。默认值为 true

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • 设置过滤器表达式。

    设置表达式,以过滤处理程序的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

将 Periodic Size Log Handler 分配给日志记录器

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将定期大小日志处理程序分配给根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=PERIODIC_SIZE_HANDLER_NAME)

以下管理 CLI 命令将定期大小日志处理程序分配给由 CATEGORY 指定名称的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=PERIODIC_SIZE_HANDLER_NAME)
删除定期大小日志处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器或异步日志处理程序,则无法移除日志处理程序。

/subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:remove

11.5.6. 配置 Syslog 处理程序

本节介绍如何使用管理 CLI 配置 syslog 处理程序,该 CLI 可用于将消息发送到支持 Syslog 协议的远程记录服务器,可以是 RFC-3164 或 RFC-5424。您还可以使用管理控制台配置 syslog 处理程序,方法是导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerSyslog Handler

在配置 syslog 处理程序时要执行的主要任务有:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加 Syslog 处理程序
/subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:add
配置 Syslog 处理程序设置

根据您的需要,您可能需要设置以下一个或多个 syslog 处理程序属性:有关可用 syslog 处理程序属性及其描述的完整列表,请参阅 Syslog Handler Attributes

  • 设置处理程序的日志级别。默认级别为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • 设置正在记录的应用的名称。默认名称为 java

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=app-name,value=APP_NAME)
  • 设置 syslog 服务器的地址。默认地址为 localhost

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=server-address,value=SERVER_ADDRESS)
  • 设置 syslog 服务器的端口。默认端口为 514

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=port,value=PORT)
  • 设置 syslog 格式,如 RFC 规范所定义。默认格式为 RFC5424

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=syslog-format,value=SYSLOG_FORMAT)
  • 指定 named-formatter 属性,以格式化 syslog 有效负载的消息。

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=named-formatter, value=FORMATTER_NAME)
将 Syslog Handler 分配给日志记录器

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将 syslog 处理程序分配给根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=SYSLOG_HANDLER_NAME)

以下管理 CLI 命令将 syslog 处理程序分配给名称由 CATEGORY 指定的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=SYSLOG_HANDLER_NAME)
删除 Syslog 处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器或异步日志处理程序,则无法移除日志处理程序。

/subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:remove

11.5.7. 配置套接字日志处理程序

本节介绍如何使用管理 CLI 配置套接字日志处理程序,它可用于通过套接字发送消息。这可以是 TCP 或 UDP 套接字。您还可以使用管理控制台配置套接字日志处理程序,方法是导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerSocket Handler

注意

如果服务器以 admin-only 模式启动,则会丢弃日志消息。

配置套接字日志处理器时要执行的主要任务有:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加 Socket Binding

定义 remote-destination-outbound-socket-bindinglocal-destination-outbound-socket-binding,作为 要使用的套接字绑定

/socket-binding-group=SOCKET_BINDING_GROUP/remote-destination-outbound-socket-binding=SOCKET_BINDING_NAME:add(host=HOST, port=PORT)
添加日志格式

定义要使用的日志格式器,如 JSON 格式器。

/subsystem=logging/json-formatter=FORMATTER:add
添加套接字日志处理程序

在添加套接字日志处理程序时,您必须指定要使用的套接字绑定和格式化器。

/subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:add(outbound-socket-binding-ref=SOCKET_BINDING_NAME,named-formatter=FORMATTER)
配置套接字日志处理程序设置

根据您的需要,您可能需要设置以下一个或多个套接字日志处理程序属性:有关可用套接字日志处理程序属性及其描述的完整列表,请参阅 Socket Log Handler Attributes

  • 设置协议.

    设置要使用的协议。默认值为 TCP

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=protocol,value=PROTOCOL)
  • 设置日志级别。

    为处理程序设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
    注意

    在服务器启动期间,套接字日志处理程序处理的日志消息排入队列,直到配置了套接字绑定并且初始化 logging 子系统。如果日志级别设置为低级别,如 TRACEDEBUG,这可能会导致启动时消耗大量内存。

  • 设置编码.

    设置处理程序的编码,如 utf-8

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • 设置自动刷新.

    设置是否在每次写入后自动清空。默认值为 true

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • 设置过滤器表达式。

    设置表达式,以过滤处理程序的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

将 Socket Log Handler 分配给 Logger

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将套接字日志处理程序分配到根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=SOCKET_HANDLER_NAME)

以下管理 CLI 命令将套接字日志处理程序分配给名称由 CATEGORY 指定的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=SOCKET_HANDLER_NAME)
删除套接字日志处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器或异步日志处理程序,则无法移除日志处理程序。

/subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:remove
使用 SSL/TLS 通过套接字发送日志消息

下列步骤演示了如何设置套接字日志处理程序以使用 SSL_TCP 协议通过套接字发送日志消息的示例。本例在 elytron 子系统中配置密钥存储、信任管理器和客户端 SSL 上下文,供套接字日志处理程序使用。来自根日志记录器的日志消息通过指定的套接字发送,格式为 JSON 格式。

有关配置 Elytron 组件的更多信息,请参阅如何为 JBoss EAP 配置服务器安全性的 Elytron Subsystem

  1. 配置 Elytron 设置。

    1. 添加 密钥存储。

      /subsystem=elytron/key-store=log-server-ks:add(path=/path/to/keystore.jks, type=JKS, credential-reference={clear-text=mypassword})
    2. 添加信任管理器。

      /subsystem=elytron/trust-manager=log-server-tm:add(key-store=log-server-ks)
    3. 添加客户端 SSL 上下文。

      /subsystem=elytron/client-ssl-context=log-server-context:add(trust-manager=log-server-tm, protocols=["TLSv1.2"])
  2. 添加套接字绑定。

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=log-server:add(host=localhost, port=4560)
  3. 添加 JSON 格式器。

    /subsystem=logging/json-formatter=json:add
  4. 添加 socket 日志处理程序。

    /subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server, protocol=SSL_TCP, ssl-context=log-server-context)
  5. 将日志处理程序分配到根日志记录器。

    /subsystem=logging/root-logger=ROOT:add-handler(name=log-server-handler)

11.5.8. 配置自定义日志处理程序

本节介绍如何使用管理 CLI 配置自定义日志处理程序。您还可以使用管理控制台配置自定义日志处理程序,方法是导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerCustom Handler

用于配置自定义日志处理器的主要任务有:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加自定义日志处理程序

在添加自定义日志处理程序时,您必须指定处理程序的 Java 类以及包含它的 JBoss EAP 模块。该类必须扩展 java.util.logging.Handler

注意
/subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:add(class=CLASS_NAME,module=MODULE_NAME)
配置自定义日志处理程序设置

根据您的需要,您可能需要设置以下一个或多个自定义日志处理程序属性:有关可用自定义日志处理程序属性及其描述的完整列表,请参阅自定义日志处理程序属性。

  • 设置日志级别。

    为处理程序设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • 设置属性.

    设置日志处理程序所需的属性。属性必须能够通过 setter 方法访问。

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=properties.PROPERTY_NAME,value=PROPERTY_VALUE)
  • 设置编码.

    设置处理程序的编码,如 utf-8

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • 设置日志格式器。

    设置处理程序的格式字符串。例如,默认格式字符串为 %d{HH:mm:ss,SSS} %-5p [%c](%t)%s%e%n。务必在引号中包含 FORMAT 值。

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    注意
  • 设置过滤器表达式。

    设置表达式,以过滤处理程序的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

将自定义日志处理程序分配给日志记录器

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将自定义日志处理程序分配到根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=CUSTOM_HANDLER_NAME)

以下管理 CLI 命令将自定义日志处理程序分配到其名称由 CATEGORY 指定的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=CUSTOM_HANDLER_NAME)
删除自定义日志处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器或异步日志处理程序,则无法移除日志处理程序。

/subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:remove

11.5.9. 配置 Async 日志处理程序

本节介绍如何使用管理 CLI 配置 async 日志处理程序。您还可以通过使用管理控制台配置 async 日志处理程序,导航到 ConfigurationSubsystemsLoggingConfiguration,点 View,然后选择 HandlerAsync Handler

在配置 async 日志处理程序时要执行的主要任务是:

重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加 Async 日志处理程序

在添加 async 日志处理程序时,您必须指定队列长度。这是队列中可以保留的最大日志请求数。

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:add(queue-length=QUEUE_LENGTH)
添加 Sub-handler

您可以添加一个或多个处理程序作为此 async 日志处理程序的子句柄。请注意,处理程序必须已存在于配置中,否则此命令将失败。

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:add-handler(name=HANDLER_NAME)
配置 Async 日志处理程序设置

根据您的需要,您可能需要设置以下一个或多个 async 日志处理程序属性:有关可用 async 日志处理程序属性及其描述的完整列表,请参阅 Async Log Handler Attributes

  • 设置日志级别。

    为处理程序设置适当的日志级别。默认值为 ALL有关所有可用选项,请参阅日志级别

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • 设置溢出操作。

    设置溢出时要执行的操作。默认值为 BLOCK,即当有完整队列时线程会阻止。您可以将此值更改为 DISCARD,这意味着如果已满队列,日志消息将被丢弃。

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=overflow-action,value=OVERFLOW_ACTION)
  • 设置过滤器表达式。

    设置表达式,以过滤处理程序的日志消息。务必用引号转义任何逗号和引号。例如,对于过滤器表达式 not (match("WFLY"),需要将以下 FILTER_EXPRESSION 可替换变量替换为"not(match(\" WFLY\")"。

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    有关可用过滤器表达式的更多信息,请参阅 Filter Expressions 部分。

将 Async 日志处理程序分配给日志记录器

要激活日志处理程序,您必须将其分配到日志记录器。

以下管理 CLI 命令将 async 日志处理程序分配给根日志记录器:

/subsystem=logging/root-logger=ROOT:add-handler(name=ASYNC_HANDLER_NAME)

以下管理 CLI 命令将 async 日志处理程序分配给由 CATEGORY 指定名称的日志记录器:

/subsystem=logging/logger=CATEGORY:add-handler(name=ASYNC_HANDLER_NAME)
删除 Async 日志处理程序

可以使用 remove 操作移除日志处理程序。如果当前分配给日志记录器,则无法移除日志处理程序。

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:remove

11.6. 配置根日志记录器

root 日志记录器捕获指定日志级别或更高级别的所有日志消息,发送到未被日志类别捕获的服务器。

本节介绍如何使用管理 CLI 配置根日志记录器。您还可以通过导航到 Configuration → SubsystemsLoggingConfiguration,点 View,然后选择 Root Logger ,使用管理控制台配置根日志记录器

配置 Root 日志器
重要

如果您要为日志记录配置集配置此日志处理程序,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

  1. 将日志处理程序分配到根日志记录器。

    添加日志处理程序。

    /subsystem=logging/root-logger=ROOT:add-handler(name=LOG_HANDLER_NAME)

    移除日志处理程序。

    /subsystem=logging/root-logger=ROOT:remove-handler(name=LOG_HANDLER_NAME)
  2. 设置日志级别。

    /subsystem=logging/root-logger=ROOT:write-attribute(name=level,value=LEVEL)

有关可用根日志记录器属性及其描述的完整列表,请参阅根日志记录器属性。

11.7. 配置日志格式

日志格式ter 定义来自该处理程序的日志消息的外观。日志记录 子系统允许您配置以下类型的日志格式器:

11.7.1. 配置模式格式

您可以创建名为模式格式器,可在日志处理程序之间用于格式化日志消息。

重要

如果您要为日志记录配置集配置此日志格式器,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

创建模式格式

在定义模式格式器时,您可以提供一个用于格式化日志消息的模式字符串。如需有关模式语法的更多信息,请参阅 Pattern Formatter 的格式字符

/subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:add(pattern=PATTERN)

例如,默认配置使用以下日志格式器字符串将消息记录到服务器日志: %d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c](%t)%s%s%e%e%n。这会创建类似于下方格式的日志消息。

2016-03-18 15:49:32,075 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990

您还可以定义颜色映射,为不同的日志级别分配颜色。格式为以逗号分隔的 LEVEL :COLOR 列表。

  • 有效的级别: ter ter fineconfigtracedebuginfo、warning error fatal严重
  • 有效颜色: 绿色红色黄色、蓝色、mag enta、c yan、白色、亮色、亮度 亮色、亮色、亮色、 亮色亮色亮色、亮色亮度、精英代理、度、 亮度、 亮度
/subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:write-attribute(name=color-map,value="LEVEL:COLOR,LEVEL:COLOR")

您还可以使用管理控制台配置模式日志格式器:

  1. 在浏览器中打开管理控制台。
  2. 选择 ConfigurationSubsystemsLogging
  3. 选择 Configuration,然后单击 View
  4. 选择 Formatter,然后选择 Pattern Formatter 选项。

11.7.2. 配置 JSON 日志格式器

您可以创建一个 JSON 日志格式器,以将日志消息格式化为 JSON。

重要

如果您要为日志记录配置集配置此日志格式器,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加 JSON 日志格式
/subsystem=logging/json-formatter=JSON_FORMATTER_NAME:add(pretty-print=true, exception-output-type=formatted)

这会创建类似于下方格式的日志消息。

{
    "timestamp": "2018-10-18T13:53:43.031-04:00",
    "sequence": 62,
    "loggerClassName": "org.jboss.as.server.logging.ServerLogger_$logger",
    "loggerName": "org.jboss.as",
    "level": "INFO",
    "message": "WFLYSRV0025: JBoss EAP 7.3.0.GA (WildFly Core 10.0.0.Final-redhat-20190924) started in 5672ms - Started 495 of 679 services (331 services are lazy, passive or on-demand)",
    "threadName": "Controller Boot Thread",
    "threadId": 22,
    "mdc": {
    },
    "ndc": "",
    "hostName": "localhost.localdomain",
    "processName": "jboss-modules.jar",
    "processId": 7461
}
添加 Logstash JSON 日志格式ter
注意

您可以修改 JSON 日志格式输出键并添加静态元数据。JSON 日志格式器的主要用途是在 JSON 中格式化日志消息。logstash 会消耗这个 JSON 输出,并搜索字段 @timestamp@version。以下示例创建了 JSON 日志格式,用于格式化 Logstash 的信息。

/subsystem=logging/json-formatter=logstash:add(exception-output-type=formatted, key-overrides=[timestamp="@timestamp"], meta-data=[@version=1])

您可以使用 JSON 格式属性,如下所述:

  • key-overrides 属性可用于覆盖定义的键的名称。
  • 例外可以通过将 exception-output-type 属性设置为 格式化来格式化 为对象。
  • 可以通过将 exception-output-type 属性设置为 detailed 来包含异常堆栈追踪。
  • 通过将 exception-output-type 设置为 详细和格式,可以包含例外,作为对象和堆栈追踪。
  • 可以使用 meta-data 属性将元数据添加到日志记录中。

如需有关 JSON 格式器属性的更多信息,请参阅 JSON 日志格式ter Attributes

您还可以使用管理控制台配置 JSON 日志格式器:

  1. 在浏览器中打开管理控制台。
  2. 选择 ConfigurationSubsystemsLogging
  3. 选择 Configuration,然后单击 View
  4. 选择 Formatter,然后选择 JSON Formatter 选项。

11.7.3. 配置 XML 日志格式

您可以创建一个 XML 日志格式器,以将日志消息格式化为 XML。

重要

如果您要为日志记录配置集配置此日志格式器,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

添加 XML 日志格式
/subsystem=logging/xml-formatter=XML_FORMATTER_NAME:add(pretty-print=true, exception-output-type=detailed-and-formatted)

这会创建类似于下方所示的日志消息。

<record>
    <timestamp>2018-10-18T13:55:53.419-04:00</timestamp>
    <sequence>62</sequence>
    <loggerClassName>org.jboss.as.server.logging.ServerLogger_$logger</loggerClassName>
    <loggerName>org.jboss.as</loggerName>
    <level>INFO</level>
    <message>WFLYSRV0025: JBoss EAP 7.3.0.GA (WildFly Core 10.0.0.Final-redhat-20190924) started in 6271ms - Started 495 of 679 services (331 services are lazy, passive or on-demand)</message>
    <threadName>Controller Boot Thread</threadName>
    <threadId>22</threadId>
    <mdc>
    </mdc>
    <ndc></ndc>
    <hostName>localhost.localdomain</hostName>
    <processName>jboss-modules.jar</processName>
    <processId>7790</processId>
</record>
添加密钥覆盖 XML 日志格式
/subsystem=logging/xml-formatter=XML_FORMATTER_NAME:add(pretty-print=true, print-namespace=true, namespace-uri="urn:custom:1.0", key-overrides={message=msg, record=logRecord, timestamp=date}, print-details=true)

您可以使用 XML 格式属性,如下所述:

  • key-overrides 属性可用于覆盖定义的键的名称。
  • 例外可以通过将 exception-output-type 属性设置为 格式化来格式化 为对象。
  • 可以通过将 exception-output-type 属性设置为 detailed 来包含异常堆栈追踪。
  • 通过将 exception-output-type 设置为 详细和格式,可以包含例外,作为对象和堆栈追踪。
  • 可以使用 meta-data 属性将元数据添加到日志记录中。

有关 XML 格式器属性的更多信息,请参阅 XML 日志格式条件属性

您还可以使用管理控制台配置 XML 日志格式器:

  1. 在浏览器中打开管理控制台。
  2. 选择 ConfigurationSubsystemsLogging
  3. 选择 Configuration,然后单击 View
  4. 选择 Formatter,然后选择 XML Formatter 选项。

11.7.4. 配置自定义日志格式器

您可以创建自定义日志格式器,供日志处理程序用于格式化日志消息。

本节介绍如何使用管理 CLI 配置自定义日志格式器。

配置自定义日志格式器
重要

如果您要为日志记录配置集配置此日志格式器,则命令的开头为 /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ 而不是 /subsystem=logging/

此外,如果您在受管域中运行,请在命令前加上 /profile=PROFILE_NAME

  1. 添加自定义日志格式器。

    在添加自定义日志格式器时,您必须指定格式器的 Java 类以及包含它的 JBoss EAP 模块。该类必须扩展 java.util.logging.Formatter

    注意

    您必须已创建了包含自定义格式的模块,否则此命令将失败。

    /subsystem=logging/custom-formatter=CUSTOM_FORMATTER_NAME:add(class=CLASS_NAME, module=MODULE_NAME)
  2. 设置日志格式器所需的属性。

    属性必须能够通过 setter 方法访问。

    /subsystem=logging/custom-formatter=CUSTOM_FORMATTER_NAME:write-attribute(name=properties.PROPERTY_NAME,value=PROPERTY_VALUE)
  3. 将自定义格式器分配到日志处理程序。

    以下管理 CLI 命令分配可由定期轮转文件处理程序使用的自定义格式器:

    /subsystem=logging/periodic-rotating-file-handler=FILE_HANDLER_NAME:write-attribute(name=named-formatter, value=CUSTOM_FORMATTER_NAME)
自定义 XML 格式示例

以下示例配置了自定义 XML 格式。它使用 org.jboss .logmanager 模块中提供的 java.util.logging. XMLFormatter 类,并将它分配给控制台日志处理程序。

/subsystem=logging/custom-formatter=custom-xml-formatter:add(class=java.util.logging.XMLFormatter, module=org.jboss.logmanager)
/subsystem=logging/console-handler=CONSOLE:write-attribute(name=named-formatter, value=custom-xml-formatter)

使用此格式器的日志消息将如下格式:

<record>
  <date>2016-03-23T12:58:13</date>
  <millis>1458752293091</millis>
  <sequence>93963</sequence>
  <logger>org.jboss.as</logger>
  <level>INFO</level>
  <class>org.jboss.as.server.BootstrapListener</class>
  <method>logAdminConsole</method>
  <thread>22</thread>
  <message>WFLYSRV0051: Admin console listening on http://%s:%d</message>
  <param>127.0.0.1</param>
  <param>9990</param>
</record>
使用管理控制台配置自定义日志格式器

您还可以使用管理控制台配置日志格式器。

  1. 在浏览器中打开管理控制台。
  2. 选择 ConfigurationSubsystemsLogging
  3. 选择 Configuration,然后单击 View
  4. 选择 Formatter,然后选择 Custom Formatter 选项。

11.8. 关于应用程序日志

可以使用 JBoss EAP logging 子系统或每一部署来配置应用的日志记录。

有关日志记录子系统,请参阅使用 JBoss EAP 日志类别和处理程序来获取日志消息。

有关应用日志记录的更多信息,如受支持的应用日志框架和部署日志配置,请参阅 JBoss EAP 开发指南中的 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#logging_for_developers 日志记录章节

11.8.1. 按部署日志记录

通过按部署日志记录,开发人员可以提前为其应用配置日志配置。部署应用时,根据定义的配置开始日志记录。通过此配置创建的日志文件仅包含有关应用程序行为的信息。

注意

如果未执行按部署的日志配置,则所有应用和服务器都使用来自 logging 子系统的配置。

与使用整个系统日志记录相比,这种方法具有优缺点。优点是 JBoss EAP 实例的管理员不需要配置服务器日志记录之外的任何其他日志记录。个缺点是每个部署的日志配置仅在服务器启动时读取,因此在运行时无法更改。

有关在应用程序中使用按部署登录的说明,请参阅 JBoss EAP 开发指南中的 https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#add_per_deployment_logging_to_an_application 将 Per-deployment Logging 添加至应用

11.8.1.1. 禁用 Per-deployment Logging

您可以使用以下方法之一禁用每个部署日志:

11.8.2. 日志记录配置集

日志记录配置集是独立的日志配置集合,可以分配给已部署的应用。与常规的 logging 子系统一样,日志记录配置文件可以定义处理程序、类别和根日志记录器,但它不能引用其他配置文件或主要 日志记录 子系统中的配置。日志配置文件的设计模仿 logging 子系统以方便配置。

通过日志记录配置文件,管理员可以创建专用于一个或多个应用的日志记录配置,而不影响任何其他日志配置。由于每个配置集都在服务器配置中定义,因此可以更改日志记录配置,而无需重新部署受影响的应用。

每个日志记录配置集都可以有:

  • 唯一的名称。此值是必需的。
  • 任意数量的日志处理程序.
  • 任何数量的日志类别。
  • 最多一个根日志记录器.

应用可以使用 Logging-Profile 属性在其 MANIFEST.MF 文件中指定要使用的日志记录配置文件。

11.8.2.1. 配置日志记录配置集

日志记录配置文件可以使用日志处理程序、类别和根日志记录器进行配置。配置日志记录配置集使用与配置 日志记录 子系统相同的语法,但以下不同之处除外:

  • 根配置路径为 /subsystem=logging/logging-profile=NAME
  • 日志配置集无法包含其他日志配置集。
  • logging 子系统具有以下无法用于日志记录配置集的属性:

    • add-logging-api-dependencies
    • use-deployment-logging-config
创建和配置日志配置集

以下流程使用管理 CLI 创建日志记录配置集并设置文件处理程序和日志记录器类别。也可以使用管理控制台配置日志记录配置集,方法是导航到 ConfigurationSubsystemsLoggingLogging Profiles

  1. 创建日志记录配置文件。

    /subsystem=logging/logging-profile=PROFILE_NAME:add
  2. 创建 文件处理程序。

    /subsystem=logging/logging-profile=PROFILE_NAME/file-handler=FILE_HANDLER_NAME:add(file={path=>"LOG_NAME.log", "relative-to"=>"jboss.server.log.dir"})
    /subsystem=logging/logging-profile=PROFILE_NAME/file-handler=FILE_HANDLER_NAME:write-attribute(name="level", value="DEBUG")

    有关文件处理程序属性列表,请参阅文件日志处理程序属性列表

  3. 创建日志记录器类别。

    /subsystem=logging/logging-profile=PROFILE_NAME/logger=CATEGORY_NAME:add(level=TRACE)

    有关日志类别属性列表,请参阅 Log Category Attributes

  4. 将文件处理程序分配到该类别。

    /subsystem=logging/logging-profile=PROFILE_NAME/logger=CATEGORY_NAME:add-handler(name="FILE_HANDLER_NAME")

然后,您可以将日志记录配置集设置为由应用在其 MANIFEST.MF 文件中使用。如需更多信息,请参阅《JBoss EAP 开发指南 》中的应用指定日志配置文件

11.8.2.2. 日志配置集配置示例

本例显示了日志记录配置文件和使用它的应用的配置。它显示管理 CLI 命令、生成的 XML 和应用 MANIFEST.MF 文件。

日志记录配置集示例有以下特征:

  • 名称为 accounts-app-profile
  • 日志类别为 com.company.accounts.ejbs
  • 日志级别 TRACE.
  • 日志处理程序是使用文件 ejb-trace.log 的文件处理程序。

管理 CLI 会话

/subsystem=logging/logging-profile=accounts-app-profile:add

/subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:add(file={path=>"ejb-trace.log", "relative-to"=>"jboss.server.log.dir"})

/subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:write-attribute(name="level", value="DEBUG")

/subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add(level=TRACE)

/subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add-handler(name="ejb-trace-file")

XML 配置

<logging-profiles>
   <logging-profile name="accounts-app-profile">
      <file-handler name="ejb-trace-file">
         <level name="DEBUG"/>
         <file relative-to="jboss.server.log.dir" path="ejb-trace.log"/>
      </file-handler>
      <logger category="com.company.accounts.ejbs">
         <level name="TRACE"/>
         <handlers>
            <handler name="ejb-trace-file"/>
         </handlers>
      </logger>
   </logging-profile>
</logging-profiles>

应用程序 MANIFEST.MF 文件

Manifest-Version: 1.0
Logging-Profile: accounts-app-profile

11.8.3. 查看部署配置

您可以使用以下管理 CLI 命令获取有关特定部署的日志记录配置的信息。

/deployment=DEPLOYMENT_NAME/subsystem=logging/configuration=CONFIG:read-resource

部署的日志记录配置值 CONFIG 可以是以下三个值之一:

例如,以下管理 CLI 命令显示 MYPROFILE 日志配置文件的配置,该配置集由指定部署使用。

/deployment=mydeployment.war/subsystem=logging/configuration=profile-MYPROFILE:read-resource(recursive=true,include-runtime=true)

这将输出以下信息:

{
    "outcome" => "success",
    "result" => {
        "error-manager" => undefined,
        "filter" => undefined,
        "formatter" => {
            "MYFORMATTER" => {
                "class-name" => "org.jboss.logmanager.formatters.PatternFormatter",
                "module" => undefined,
                "properties" => {"pattern" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n"}
            }
        },
        "handler" => {
            "MYPERIODIC" => {
                "class-name" => "org.jboss.logmanager.handlers.PeriodicRotatingFileHandler",
                "encoding" => undefined,
                "error-manager" => undefined,
                "filter" => undefined,
                "formatter" => "MYFORMATTER",
                "handlers" => [],
                "level" => "ALL",
                "module" => undefined,
                "properties" => {
                    "append" => "true",
                    "autoFlush" => "true",
                    "enabled" => "true",
                    "suffix" => ".yyyy-MM-dd",
                    "fileName" => "EAP_HOME/standalone/log/deployment.log"
                }
            }
        },
        "logger" => {"MYCATEGORY" => {
            "filter" => undefined,
            "handlers" => [],
            "level" => "DEBUG",
            "use-parent-handlers" => true
        }},
        "pojo" => undefined
    }
}

您还可以使用递归 read-resource 操作来读取日志记录配置和有关部署的其他信息。

/deployment=DEPLOYMENT_NAME/subsystem=logging:read-resource(include-runtime=true, recursive=true)

11.9. 调整 Logging 子系统

有关监控 日志 子系统性能并优化性能的提示,请参阅 性能调优指南中 的日志子系统 调优部分。

第 12 章 数据源管理

12.1. 关于 JBoss EAP 数据源

关于 JDBC

JDBC API 是定义 Java 应用如何访问数据库的标准。应用配置引用 JDBC 驱动程序的数据源。然后,可以针对驱动程序而非数据库编写应用程序代码。驱动程序将代码转换为数据库语言。这意味着,如果安装了正确的驱动程序,应用可以与任何受支持的数据库一起使用。

如需更多信息,请参见 JDBC 4.0 规范

支持的数据库

如需 JBoss EAP 7 支持的 JDBC 兼容数据库列表,请参阅 JBoss EAP 支持的配置。

数据源类型

两种常规类型的资源称为数据源和 XA 数据源。

非 XA 数据源
用于不使用事务的应用程序,或者使用与单个数据库进行事务的应用程序。
XA 数据源
由将多个数据库或其他 XA 资源作为 XA 事务一部分的应用使用.XA 数据源会带来额外的开销。

您可以指定在使用 JBoss EAP 管理接口创建数据源时要使用的数据源类型。

ExampleDS 数据源

JBoss EAP 附带了数据源配置示例 ExampleDS,用于演示如何定义数据源。此数据源使用 H2 数据库,这是一个轻量级关系数据库管理系统,可为开发人员提供快速构建应用的能力。

警告

在生产环境中不应该使用 ExampleDS 数据源和 H2 数据库。这是一个非常小、自包含的数据源,支持测试和构建应用程序所需的所有标准,但安全性不足以用于生产用途。

12.2. JDBC Drivers

在 JBoss EAP 中定义数据源以供您的应用使用之前,必须先安装相应的 JDBC 驱动程序。

12.2.1. 将 JDBC 驱动程序作为核心模块安装

若要将 JDBC 驱动程序作为核心模块安装,您必须首先 将 JDBC 驱动程序添加为核心模块,然后在 datasources 子系统中 注册 JDBC 驱动程序

12.2.1.1. 将 JDBC 驱动程序添加为核心模块

JDBC 驱动程序可以作为核心模块安装,使用管理 CLI 可以执行下列步骤:

  1. 下载 JDBC 驱动程序。

    从您的数据库供应商下载适当的 JDBC 驱动程序。有关常见数据库的 JDBC 驱动程序的标准下载位置,请参阅 JDBC 驱动程序下载位置。

    如果 JDBC 驱动程序 JAR 文件包含在 ZIP 或 TAR 存档中,请确保提取存档。

  2. 启动 JBoss EAP 服务器。
  3. 启动管理 CLI。

    $ EAP_HOME/bin/jboss-cli.sh
  4. 使用 模块 add management CLI 命令,添加新的核心模块。

    module add --name=MODULE_NAME --resources=PATH_TO_JDBC_JAR --dependencies=DEPENDENCIES

    例如,以下命令添加 MySQL JDBC 驱动程序模块:

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    重要

    使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

    技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

    如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

    执行 模块 --help 获取关于使用此命令添加和删除模块的更多详细信息。

接下来,您必须将它注册为 JDBC 驱动程序,供应用数据源引用。

12.2.1.2. 注册 JDBC 驱动程序

驱动程序作为核心模块安装之后,您必须使用以下管理 CLI 命令将它注册为 JDBC 驱动程序:在受管域中运行时,请确保在此命令前加上 /profile=PROFILE_NAME

/subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME, driver-class-name=DRIVER_CLASS_NAME)
注意

只有 JDBC 驱动程序 jar 在 /META-INF/services/java.sql.Driver 文件中定义了多个类,才需要 driver- class-name 参数。

例如,MySQL 5.1.36 JDBC 驱动程序 JAR 中的 /META-INF/services/java.sql.Driver 文件定义了两个类:

  • com.mysql.cj.jdbc.Driver
  • com.mysql.fabric.jdbc.FabricMySQLDriver

在本例中,您将传递 driver-class-name=com.mysql.cj.jdbc.Driver

例如,以下命令注册了 MySQL JDBC 驱动程序:

/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)

JDBC 驱动程序现在可供应用数据源引用。

12.2.2. 将 JDBC 驱动程序安装为 JAR 部署

JDBC 驱动程序可以使用管理 CLI 或管理控制台作为 JAR 部署进行安装。只要驱动程序符合 JDBC 4 规范,部署时将自动识别并作为 JDBC 驱动程序安装。

下列步骤介绍了如何使用管理 CLI 安装 JDBC 驱动程序。

注意
  1. 下载 JDBC 驱动程序。

    从您的数据库供应商下载适当的 JDBC 驱动程序。有关常见数据库的 JDBC 驱动程序的标准下载位置,请参阅 JDBC 驱动程序下载位置。

    如果 JDBC 驱动程序 JAR 文件包含在 ZIP 或 TAR 存档中,请确保提取存档。

  2. 如果 JDBC 驱动程序不兼容 JDBC 4,请参阅将 JDBC 驱动程序 JAR 更新为 JDBC 4-Compliant 的步骤。
  3. 将 JAR 部署到 JBoss EAP.

    deploy PATH_TO_JDBC_JAR
    注意

    在受管域中,指定适当的服务器组。

    例如,以下命令将部署 MySQL JDBC 驱动程序:

    deploy /path/to/mysql-connector-java-8.0.12.jar

    JBoss EAP 服务器日志中将显示一条消息,显示部署的驱动程序名称,该名称将在定义数据源时使用。

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-8.0.12.jar

JDBC 驱动程序现在可供应用数据源引用。

将 JDBC 驱动程序 JAR 更新为 JDBC 4-Compliant

如果 JDBC 驱动程序 JAR 不兼容 JDBC 4,可以通过下列步骤使它可部署:

  1. 创建一个空临时目录。
  2. 创建 META-INF 子目录。
  3. 创建 META-INF/services 子目录。
  4. 创建 META-INF/services/java.sql.Driver 文件,再添加一行来指示 JDBC 驱动程序的完全限定类名称。

    例如,MySQL JDBC 驱动程序将添加下面这一行:

    com.mysql.cj.jdbc.Driver
  5. 使用 JAR 命令行工具将此新文件添加到 JAR。

    jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver

12.2.3. JDBC 驱动程序下载位置

下表提供了用于 JBoss EAP 的常见数据库的 JDBC 驱动程序的标准下载位置。

注意

这些链接指向不受红帽控制或主动监控的第三方网站。有关数据库的最新驱动程序,请查看您的数据库供应商文档和网站。

表 12.1. JDBC 驱动程序下载位置
vendor下载位置

MySQL

http://www.mysql.com/products/connector/

PostgreSQL

http://jdbc.postgresql.org/

Oracle

http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html

IBM

http://www-01.ibm.com/support/docview.wss?uid=swg21363866

Sybase

jConnect JDBC 驱动程序是用于 SAP ASE 安装的 SDK 的一部分。目前此驱动程序本身没有单独的下载网站。

Microsoft

http://msdn.microsoft.com/data/jdbc/

12.2.4. 访问供应商特定类

在某些情况下,应用需要使用不属于 JDBC API 的供应商特定功能。在这些情况下,您可以通过在该应用程序中声明依赖项来访问特定于供应商的 API。

警告

这是高级使用。只有 JDBC API 中没有功能的应用才应实施此过程。

重要

在使用重新身份验证机制和访问特定于供应商的类时,此过程是必需的。

您可以使用 MANIFEST.MF 文件或 jboss-deployment-structure.xml 文件定义应用的依赖项。

如果您还没有这样做,请将 JDBC 驱动程序作为核心模块安装

使用 MANIFEST.MF 文件
  1. 编辑应用的 META-INF/MANIFEST.MF 文件。
  2. 添加 Dependencies 行,并指定模块名称。

    例如,下面这一行将 com.mysql 模块声明为依赖项:

    Dependencies: com.mysql
使用 jboss-deployment-structure.xml 文件
  1. 在应用的 META -INF/ 或 WEB-INF/ 文件夹中创建名为 jboss-deployment- structure.xml 的文件。
  2. 使用 dependencies 元素指定模块。

    例如,以下示例 jboss-deployment-structure.xml 文件将 com.mysql 模块声明为依赖项:

    <jboss-deployment-structure>
      <deployment>
        <dependencies>
          <module name="com.mysql"/>
        </dependencies>
      </deployment>
    </jboss-deployment-structure>

以下示例代码将访问 MySQL API:

import java.sql.Connection;
...
Connection c = ds.getConnection();
if (c.isWrapperFor(com.mysql.jdbc.Connection.class)) {
    com.mysql.jdbc.Connection mc = c.unwrap(com.mysql.jdbc.Connection.class);
}
重要

随着连接由 IronJacamar 容器控制,请严格遵循特定于供应商的 API 准则。

12.3. 创建数据源

可以使用管理控制台或管理 CLI 创建数据源。

JBoss EAP 7 允许您在数据源属性值中使用表达式,如 enabled 属性。有关在配置中使用表达式的详情,请参阅属性替换部分

12.3.1. 创建非 XA 数据源

您可以使用管理 CLI 或管理控制台创建非 XA 数据源。

使用管理控制台定义非 XA 数据源
  1. 导航到 ConfigurationSubsystemsDatasources & DriversDatasources
  2. 单击添加(+)按钮,然后选择 Add Datasource
  3. 它将打开 Add Datasource 向导,您可以在其中选择数据源类型并点击 Next。这会为您的数据库创建一个模板。向导的以下页面预先填充了特定于所选数据源的值。这使得数据源创建过程变得简单。
  4. 您可以在 Test Connection 页面上测试您的连接,然后完成数据源创建过程。
  5. 检查详情,再单击 Finish 以创建数据源。
使用管理 CLI 定义非 XA 数据源

可以使用 数据源添加管理 CLI 命令来定义非 X A 数据源。

  1. 如果您还没有这样做,请安装相应的 JDBC 驱动程序并将其注册为核心模块
  2. 使用 data-source add 命令定义数据源,并指定适当的参数值。

    data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME  --connection-url=CONNECTION_URL
    注意

    在受管域中,您必须指定 --profile=PROFILE_NAME 参数。

    有关这些参数值的提示,请参见下面的 Datasource Parameters 部分。

具体示例,请参阅支持的数据库的 Datasource 配置示例

数据源参数
jndi-name
数据源的 JNDI 名称必须以 java:/ 或 java :jboss/ 开头。例如,java:jboss/datasources/ExampleDS.
driver-name

驱动程序名称值取决于 JDBC 驱动程序是作为核心模块安装的还是 JAR 部署。

  1. 对于核心模块,驱动程序名称值将是其注册时为 JDBC 驱动程序提供的名称。
  2. 对于 JAR 部署,如果其 /META-INF/services/java.sql.Driver 文件中仅列出一个类,则驱动程序名称是 JAR 的名称。如果列出多个类,则值为 JAR_NAME + "_ " + DRIVER_CLASS_NAME + "_ " + MAJOR_VERSION + "_" + MINOR_VERSION (例如,) mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1).

    部署 JDBC JAR 时,您还可以查看 JBoss EAP 服务器日志中的驱动程序名称。

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
connection-url
有关支持的数据库的连接 URL 格式的详情,请查看 Datasource Connection URL 列表。

有关所有可用数据源属性的完整列表,请参阅 Datasource Attributes 部分。

12.3.2. 创建 XA 数据源

您可以使用管理 CLI 或管理控制台创建 XA 数据源。

使用管理控制台定义 XA 数据源
  1. 导航到 ConfigurationSubsystemsDatasources & DriversDatasources
  2. 单击添加(+)按钮,然后选择 Add XA Datasource
  3. 它打开 Add XA Datasource 向导,您可以在其中选择数据源类型并点击 Next。这会为您的数据库创建一个模板。向导的以下页面预先填充了特定于所选数据源的值。这使得数据源创建过程变得简单。
  4. 您可以在 Test Connection 页面上测试您的连接,然后完成数据源创建过程。
  5. 检查详情,再单击 Finish 以创建数据源。
使用管理 CLI 定义 XA 数据源

XA 数据源可以使用 the xa-data-source add management CLI 命令来定义。

注意

在受管域中,您将需要指定要使用的配置文件。根据管理 CLI 命令的格式,您将在命令前面使用 /profile=PROFILE_NAME,或者传递 --profile=PROFILE_NAME 参数。

  1. 如果您还没有这样做,请安装相应的 JDBC 驱动程序并将其注册为核心模块
  2. 使用 the xa-data-source add 命令定义数据源,并指定适当的参数值。

    xa-data-source add --name=XA_DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasource-class=XA_DATASOURCE_CLASS --xa-datasource-properties={"ServerName"=>"HOST_NAME","DatabaseName"=>"DATABASE_NAME"}

    有关这些参数值的提示,请参见下面的 Datasource Parameters 部分。

  3. 设置 XA 数据源属性.

    定义 XA 数据源时至少需要一个 XA 数据源属性,或者在上一步中添加数据源时会收到错误。在定义 XA 数据源时未设置的任何属性都可以在之后单独设置。

    1. 设置服务器名称。

      /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=ServerName:add(value=HOST_NAME)
    2. 设置数据库名称。

      /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=DatabaseName:add(value=DATABASE_NAME)

具体示例,请参阅支持的数据库的 Datasource 配置示例

数据源参数
jndi-name
数据源的 JNDI 名称必须以 java:/ 或 java :jboss/ 开头。例如,java:jboss/datasources/ExampleDS.
driver-name

驱动程序名称值取决于 JDBC 驱动程序是作为核心模块安装的还是 JAR 部署。

  1. 对于核心模块,驱动程序名称值将是其注册时为 JDBC 驱动程序提供的名称。
  2. 对于 JAR 部署,如果其 /META-INF/services/java.sql.Driver 文件中仅列出一个类,则驱动程序名称是 JAR 的名称。如果列出了多个类,则值为 JAR_NAME + "_ " + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION,例如: mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1.

    部署 JDBC JAR 时,您还可以查看 JBoss EAP 服务器日志中的驱动程序名称。

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
xa-datasource-class
指定 javax.sql.XADataSource 类的 JDBC 驱动程序实施的 XA 数据源类。
xa-datasource-properties
定义 XA 数据源时至少需要一个 XA 数据源属性,否则在尝试添加时会收到错误。其他属性也可以在定义后添加到 XA 数据源中。

有关所有可用数据源属性的完整列表,请参阅 Datasource Attributes 部分。

12.4. 修改数据源

可以使用管理控制台或管理 CLI 配置数据源设置。

JBoss EAP 7 允许您在数据源属性值中使用表达式,如 enabled 属性。有关在配置中使用表达式的详情,请参阅属性替换部分

12.4.1. 修改非 XA 数据源

可以使用数据源 管理 CLI 命令更新非 X A 数据源设置。您还可以导航到 ConfigurationSubsystems → Datasources → DatasourcesDatasources → Datasources,从管理控制台更新数据源属性

注意

非 XA 数据源可与 JTA 事务集成。要将数据源与 JTA 集成,请确保 jta 参数设为 true

可以通过以下管理 CLI 命令更新数据源的设置:

data-source --name=DATASOURCE_NAME --ATTRIBUTE_NAME=ATTRIBUTE_VALUE
注意

在受管域中,您必须指定 --profile=PROFILE_NAME 参数。

可能需要重新加载服务器才能使更改生效。

12.4.2. 修改 XA 数据源

XA 数据源设置可以使用 xa-data-source 管理 CLI 命令更新。您还可以导航到 ConfigurationSubsystems → Datasources → DatasourcesDatasources → Datasources,从管理控制台更新数据源属性

  • 可以使用以下管理 CLI 命令更新 XA 数据源的设置:

    xa-data-source --name=XA_DATASOURCE_NAME --ATTRIBUTE_NAME=ATTRIBUTE_VALUE
    注意

    在受管域中,您必须指定 --profile=PROFILE_NAME 参数。

  • XA 数据源属性可以通过以下管理 CLI 命令添加:

    /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=PROPERTY:add(value=VALUE)
    注意

    在受管域中,您必须在此命令前加上 /profile=PROFILE_NAME

可能需要重新加载服务器才能使更改生效。

12.5. 删除数据源

可以使用管理控制台或管理 CLI 删除数据源。

12.5.1. 删除非 XA 数据源

可以使用 数据源删除管理 CLI 命令来删除非 X A 数据源。您还可以通过导航到 ConfigurationSubsystems → Datasources → DatasourcesDatasources 来使用管理控制台删除数据源

data-source remove --name=DATASOURCE_NAME
注意

在受管域中,您必须指定 --profile=PROFILE_NAME 参数。

删除数据源后,服务器将需要重新加载。

12.5.2. 删除 XA 数据源

XA 数据源可以使用 the xa-data-source remove management CLI 命令删除。您还可以通过导航到 ConfigurationSubsystems → Datasources → DatasourcesDatasources 来使用管理控制台删除数据源

xa-data-source remove --name=XA_DATASOURCE_NAME
注意

在受管域中,您必须指定 --profile=PROFILE_NAME 参数。

在 XA 数据源被删除后,服务器将需要重新加载。

12.6. 测试数据源连接

您可以使用管理 CLI 或管理控制台测试数据源连接,以验证其设置是否正确。

使用管理 CLI 测试数据源连接

以下管理 CLI 命令可用于测试数据源的连接:

/subsystem=datasources/data-source=DATASOURCE_NAME:test-connection-in-pool
注意

在受管域中,您必须在此命令前加上 /host=HOST_NAME/server=SERVER_NAME。如果您要测试 XA 数据源,请将 data-source=DATASOURCE_NAME 替换为 xa-data-source=XA_DATASOURCE_NAME

使用管理控制台测试数据源连接

在管理控制台中使用 Add Datasource 向导时,您有机会在创建数据源前测试连接。在向导的 Test Connection 屏幕上,单击 Test Connection 按钮。

添加数据源后,您可以通过导航到 ConfigurationSubsystems → DatasourcesDatasourcesDatasources、选择数据源并从下拉菜单中选择 Test Connection 来测试连接

12.7. 清空数据源连接

您可以使用以下管理 CLI 命令清空数据源连接。

注意

在受管域中,您必须在这些命令前使用 /host=HOST_NAME/server=SERVER_NAME

  • 清空池中的所有连接。

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-all-connection-in-pool
  • 正常清空池中的所有连接。

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-gracefully-connection-in-pool

    服务器将等待连接闲置,然后清空连接。

  • 清空池中的所有空闲连接。

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-idle-connection-in-pool
  • 清空池中的所有无效连接。

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-invalid-connection-in-pool

    服务器将清空其认为无效的所有连接,例如,由 valid-connection-checker-class-namecheck-valid-connection-sql 验证 机制清除。

您还可以使用管理控制台刷新连接。从 Runtime 选项卡中,选择服务器,选择 Datasources,选择数据源,然后使用下拉菜单选择相应的操作。

12.8. XA 数据源恢复

XA 数据源是可参与 XA 全局交易的数据源,由交易经理协调,并可在单个交易中跨越多个资源。如果其中一位参与者未能提交更改,则其他参与者中止交易并恢复交易发生前的状态。这是为了保持一致性,避免潜在的数据丢失或损坏。

XA 恢复是一个确保更新或回滚受交易影响的所有资源的过程,即使任何资源或交易参与者崩溃或不可用。XA 恢复发生,无需用户干预。

每个 XA 资源都需要关联一个恢复模块及其配置。恢复模块是执行恢复时执行的代码。JBoss EAP 自动注册 JDBC XA 资源的恢复模块。如果要实施自定义恢复代码,您可以使用 XA 数据源注册自定义模块。恢复模块必须扩展类 com.arjuna.ats.jta.recovery.XAResourceRecovery

12.8.1. 配置 XA 恢复

对于大多数 JDBC 资源,恢复模块自动与资源关联。在这些情况下,您只需要配置允许恢复模块连接到资源以执行恢复的选项。

下表描述了特定于 XA 恢复的 XA 数据源参数。这些配置属性可以在数据源创建期间或之后设置。您可以使用管理控制台或管理 CLI 进行设置。有关配置 XA 数据源的详情,请参阅修改 XA 数据源。

表 12.2. XA 恢复的数据源参数
属性描述

restore-username

用于连接资源以进行恢复的用户名。请注意,如果没有指定,将使用数据源安全设置。

restore-password

用于连接资源以进行恢复的密码。请注意,如果没有指定,将使用数据源安全设置。

recovery-security-domain

用于连接资源以进行恢复的安全域。

recovery-plugin-class-name

如果需要使用自定义恢复模块,将此属性设置为模块的完全限定类名称。模块应扩展类 com.arjuna.ats.jta.recovery.XAResourceRecovery

recovery-plugin-properties

如果您使用需要设置属性的自定义恢复模块,请将此属性设置为属性的逗号分隔 KEY=VALUE 对的列表。

禁用 XA 恢复

如果多个 XA 数据源连接到同一物理数据库,则通常只需要为其中一个配置 XA 恢复。

使用以下命令来禁用 XA 数据源的恢复:

/subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME:write-attribute(name=no-recovery,value=true)

12.8.2. 特定于厂商的 XA 恢复

特定厂商配置

些数据库需要特定的配置,才能在由 JBoss EAP 事务管理器管理的 XA 交易中协作。有关详细信息和最新信息,请查看您的数据库供应商文档。

MySQL
不需要特殊配置。如需更多信息,请参阅 MySQL 文档。
PostgreSQL 和 Postgres Plus Advanced Server
要使 PostgreSQL 能够处理 XA 事务,请将配置参数 max_prepared_transactions 改为大于 0 的值,等于或大于 max_connections
Oracle

确保 Oracle 用户 USER 有权访问恢复所需的表。

GRANT SELECT ON sys.dba_pending_transactions TO USER;
GRANT SELECT ON sys.pending_trans$ TO USER;
GRANT SELECT ON sys.dba_2pc_pending TO USER;
GRANT EXECUTE ON sys.dbms_xa TO USER;

如果 Oracle 用户没有正确的权限,您可能会看到类似如下的错误:

WARN  [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery  got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERR
Microsoft SQL Server
如需更多信息,请参阅 Microsoft SQL Server 文档,包括 http://msdn.microsoft.com/en-us/library/aa342335.aspx
IBM DB2
不需要特殊配置。如需更多信息,请参阅 IBM DB2 文档。
Sybase

Sybase 希望在数据库中启用 XA 事务。如果没有正确的数据库配置,XA 事务将无法工作。enable xact 协调 参数启用或禁用自适应服务器事务协调服务。启用此参数后,自适应服务器服务器可确保对远程适配器服务器数据提交或回滚原始事务的更新。

要启用事务协调,请使用:

sp_configure 'enable xact coordination', 1
MariaDB
不需要特殊配置。如需更多信息,请参阅 MariaDB 文档。
已知问题

这些处理 XA 事务的已知问题与 JBoss EAP 7 支持的特定数据库和 JDBC 驱动程序版本有关。有关支持的数据库的最新信息,请参阅 JBoss EAP 支持的配置

MySQL
MySQL 无法完全处理 XA 事务。如果客户端与 MySQL 断开连接,则此类交易的所有信息都将丢失。如需更多信息,请参阅此 MySQL 错误。请注意,这个问题已在 MySQL 5.7 中解决。
PostgreSQL 和 Postgres Plus Advanced Server

当两阶段提交(2PC)的提交阶段发生网络故障时,JDBC 驱动程序会返回 XAER_RMERR XAException 错误代码。此错误向交易管理器表明一个无法恢复的灾难性事件,但事务保留在数据库端的 in doubt 状态,并在网络连接再次建立后易于更正。正确的返回代码应当是 XAER_RMFAIL 或 XAER_RETRY。错误代码不正确会导致事务保持在 JBoss EAP 侧的 Heuristic 状态,并在数据库中锁定需要人工干预。如需更多信息,请参阅此 PostgreSQL 错误

如果使用单阶段提交优化时发生连接失败,JDBC 驱动程序将返回 XAER_RMERR,但应当返回 XAER_RMFAIL 错误代码。如果数据库在一阶提交期间提交数据并且连接在停机时中断,这可能会导致数据不一致,然后客户端被通知事务被回滚。

Postgres Plus JDBC 驱动程序为 Postgres Plus Server 中存在的所有准备事务返回 XID,因此无法确定 XID 所属的数据库。如果您在 JBoss EAP 中为同一数据库定义多个数据源,则内部事务恢复尝试可能会在错误的帐户下运行,这会导致恢复失败。

Oracle

当恢复管理器使用配置了一些用户凭据的数据源调用恢复时,JDBC 驱动程序会返回属于数据库实例上所有用户的 XID。JDBC 驱动程序抛出异常 ORA-24774:无法切换到指定的事务,因为它试图恢复属于其他用户的 XID。

这个问题的解决方法是向在恢复数据源配置中使用凭证的用户授予 FORCE ANY TRANSACTION 特权。有关配置权限的更多信息,请参阅 http://docs.oracle.com/database/121/ADMIN/ds_txnman.htm#ADMIN12259

Microsoft SQL Server

当两阶段提交(2PC)的提交阶段发生网络故障时,JDBC 驱动程序会返回 XAER_RMERR XAException 错误代码。此错误向交易管理器表明一个无法恢复的灾难性事件,但事务保留在数据库端的 in doubt 状态,并在网络连接再次建立后易于更正。正确的返回代码应当是 XAER_RMFAIL 或 XAER_RETRY。错误代码不正确会导致事务保持在 JBoss EAP 侧的 Heuristic 状态,并在数据库中锁定需要人工干预。如需更多信息,请参阅此 Microsoft SQL Server 问题报告

如果使用单阶段提交优化时发生连接失败,JDBC 驱动程序将返回 XAER_RMERR,但应当返回 XAER_RMFAIL 错误代码。如果数据库在一阶提交期间提交数据并且连接在停机时中断,这可能会导致数据不一致,然后客户端被通知事务被回滚。

IBM DB2
如果在单阶段提交期间发生连接失败,JDBC 驱动程序将返回 XAER_RETRY,但应当返回 XAER_RMFAIL 错误代码。如果数据库在一阶提交期间提交数据并且连接在停机时中断,这可能会导致数据不一致,然后客户端被通知事务被回滚。
Sybase

当两阶段提交(2PC)的提交阶段发生网络故障时,JDBC 驱动程序会返回 XAER_RMERR XAException 错误代码。此错误向交易管理器表明一个无法恢复的灾难性事件,但事务保留在数据库端的 in doubt 状态,并在网络连接再次建立后易于更正。正确的返回代码应当是 XAER_RMFAIL 或 XAER_RETRY。错误代码不正确会导致事务保持在 JBoss EAP 侧的 Heuristic 状态,并在数据库中锁定需要人工干预。

如果使用单阶段提交优化时发生连接失败,JDBC 驱动程序将返回 XAER_RMERR,但应当返回 XAER_RMFAIL 错误代码。如果数据库在一阶提交期间提交数据并且连接在停机时中断,这可能会导致数据不一致,然后客户端被通知事务被回滚。

如果在 Sybase 事务分支处于就绪状态之前包含插入 Sybase 15.7 或 16 数据库的 XA 事务失败,则重复 XA 事务并插入具有相同主键的相同记录会失败,并出现 com.sybase.jdbc4.jdbc.SybSQLException: Attempt 以插入重复密钥行。这个异常将被抛出,直到原始的未完成 Sybase 事务分支回滚。

MariaDB
MariaDB 无法完全处理 XA 事务。如果客户端与 MariaDB 断开连接,则此类交易的所有信息都将丢失。
MariaDB Galera Cluster
MariaDB Galera 集群中不支持 XA 事务。

12.9. 数据库连接验证

数据库维护、网络问题或其他中断事件可能会导致 JBoss EAP 丢失与数据库的连接。为了从这些情形中恢复,您可以为数据源启用数据库连接验证。

要配置数据库连接验证,您可以指定验证时序方法、用于确定执行验证的方式的验证机制,以及用于定义异常处理方式的异常分类器。

  1. 选择一种验证计时方法

    validate-on-match

    validate-on-match 选项设为 true 时,每次使用下一步中指定的验证机制从连接池中签出时,都会验证数据库连接。

    如果连接无效,则会向日志写入警告,并检索池中的下一个连接。此过程将继续,直到找到了有效的连接。如果您不希望循环池中的每一连接,您可以使用 use-fast-fail 选项。如果池中找不到有效的连接,则会创建一个新连接。如果连接创建失败,则会向请求的应用返回异常。

    此设置可产生最快的恢复速度,但会给数据库造成最高负载。但是,如果对最低性能影响不是问题,则这是最安全的选择。

    background-validation

    background-validation 选项设为 true 时,会在使用前在后台线程中定期验证连接。验证的频率由 background-validation-millis 属性指定。background-validation-millis 的默认值为 0,表示它已被禁用。

    在确定 background-validation-millis 属性的值时,请考虑以下几点:

    • 这个值不应设置为与您 idle-timeout-minutes 设置相同的值。
    • 数值越低,池的验证频率越高,无效连接越早从池中移除。
    • 数值越低,会占用更多的数据库资源。数值越高,连接验证检查频率越少,使用的数据库资源更少,但死连接在较长时间内不会被检测到。
    注意

    这些选项是互斥的。如果 validate-on-match 设为 true,则 background-validation 必须设为 false。如果 background-validation 设为 true,则 validate-on-match 必须设置为 false

  2. 选择一种验证机制

    valid-connection-checker-class-name

    使用 valid-connection-checker-class-name 是首选的验证机制。这指定了一个连接检查器类,用于验证正在使用的特定数据库的连接。JBoss EAP 提供以下连接检查器:

    • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
    check-valid-connection-sql

    使用 check-valid-connection-sql 时,您将提供用于验证连接的 SQL 语句。

    以下是可以用来验证 Oracle 连接的 SQL 语句示例。

    select 1 from dual

    以下是可以用来验证 MySQL 或 PostgreSQL 连接的示例 SQL 语句:

    select 1
  3. 设置异常分类器类名称。

    当异常标记为致命时,即使连接参与交易,也会立即关闭连接。使用异常排序器类选项,在连接异常后正确地检测和清理。为您的数据源类型选择相应的 JBoss EAP 异常分类器。

    • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.informix.InformixExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter

12.10. 数据源安全

数据源安全性指的是为数据源连接加密或模糊密码。这些密码可以以纯文本形式存储在配置文件中,但这代表了安全风险。

您可以通过多种方法实现数据源安全性。下面列出了每个示例。

使用安全域保护数据源

使用以下步骤通过安全域保护数据源:

  1. 创建新的安全域。

    /subsystem=security/security-domain=DsRealm:add(cache-type=default)
    /subsystem=security/security-domain=DsRealm/authentication=classic:add(login-modules=[{code=ConfiguredIdentity,flag=required,module-options={userName=sa,
    principal=sa, password=sa}}])

    定义了数据源的安全域。以下 XML 提取是调用 CLI 命令的结果。

     <security-domain name="DsRealm" cache-type="default">
      <authentication>
        <login-module code="ConfiguredIdentity" flag="required">
          <module-option name="userName" value="sa"/>
          <module-option name="principal" value="sa"/>
          <module-option name="password" value="sa"/>
        </login-module>
      </authentication>
    </security-domain>
  2. 添加新数据源.

    data-source add --name=securityDs
    --jndi-name=java:jboss/datasources/securityDs
    --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 --driver-name=h2
    --new-connection-sql="select current_user()"
  3. 设置数据源上的安全域。

    data-source --name=securityDs --security-domain=DsRealm
  4. 重新加载服务器,让更改生效。

    reload
注意

如果您使用具有多个数据源的安全域,请在安全域中禁用缓存。这可以通过将 cache-type 属性的值设置为 none 或完全删除属性来完成;但是,如果需要缓存,请为每个数据源使用单独的安全域。

以下 XML 提取显示了通过 DsRealm 保护的数据源。

<datasources>
  <datasource jndi-name="java:jboss/datasources/securityDs"
    pool-name="securityDs">
    <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
      <driver>h2</driver>
      <new-connection-sql>select current_user()</new-connection-sql>
      <security>
        <security-domain>DsRealm</security-domain>
      </security>
    </datasource>
</datasources>

有关使用安全域的更多信息,请参阅如何配置身份管理

使用密码 Vault 保护数据源

使用以下步骤使用密码 vault 保护数据源:

  1. 为 ExampleDS 数据源设置密码库。

    data-source --name=ExampleDS
    --password=${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}
  2. 重新加载服务器以实施更改。

    reload

以下 XML 安全元素添加到使用密码库保护的 ExampleDS 数据源中:

<security>
  <user-name>admin</user-name>
  <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password>
</security>

有关使用密码库的更多信息,请参阅 JBoss EAP How to Configure Server Security 指南中的 Password Vault 部分。

使用凭证存储保护数据源

您还可以使用凭据存储来提供密码。elytron 子系统提供创建凭据存储的功能,以便在整个 JBoss EAP 中安全存放和使用您的密码。您可以在 JBoss EAP How to Configure Server Security 指南的 Credential Store 部分中找到关于创建和使用凭据存储的更多详细信息。

为示例DS 添加凭证存储参考

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=credential-reference,value={store=exampleCS, alias=example-ds-pw})

使用身份验证上下文保护数据源

您还可以使用 Elytron 身份验证上下文来提供用户名和密码。

使用以下步骤配置和使用数据源安全性的身份验证上下文。

  1. 删除 密码user-name

    /subsystem=datasources/data-source=ExampleDS:undefine-attribute(name=password)
    /subsystem=datasources/data-source=ExampleDS:undefine-attribute(name=user-name)
  2. 为数据源启用 Elytron 安全性。

    /subsystem=datasources/data-source=ExampleDS:write-attribute(name=elytron-enabled,value=true)
    
    reload
  3. 为您的凭证创建 身份验证配置

    身份验证配置包含您希望在进行连接时使用的数据源的凭据。以下示例使用对凭据存储的引用,但也可以使用 Elytron 安全域。

    /subsystem=elytron/authentication-configuration=exampleAuthConfig:add(authentication-name=sa,credential-reference={clear-text=sa})
  4. 创建 身份验证上下文.

    /subsystem=elytron/authentication-context=exampleAuthContext:add(match-rules=[{authentication-configuration=exampleAuthConfig}])
  5. 更新数据源以使用身份验证上下文。

    以下示例更新了 ExampleDS 以使用身份验证上下文。

    /subsystem=datasources/data-source=ExampleDS:write-attribute(name=authentication-context,value=exampleAuthContext)
    
    reload
    注意

    如果没有设置 authentication-context 属性,且 elytron-enabled 属性设为 true,则 JBoss EAP 将使用当前上下文进行身份验证。

使用 Kerberos 保护数据源

要使用 kerberos 身份验证保护数据源,需要以下配置:

  • Kerberos 在数据库服务器上配置。
  • JBoss EAP 主机服务器具有数据库服务器的 keytab 条目。

使用 kerberos 保护数据源:

  1. 将 JBoss EAP 配置为使用 kerberos.

    /system-property=java.security.krb5.conf:add(value="/path/to/krb5.conf")
    /system-property=sun.security.krb5.debug:add(value="false")
    /system-property=sun.security.spnego.debug:add(value="false")

    若要进行调试,请将 sun.security.krb5.debugsun.security.spnego.debug 的值更改为 true。在生产环境中,建议将值设为 false

  2. 配置安全性.

    您可以使用旧安全性或 Elytron 安全来保护数据源。

    • 将 kerberos 与旧安全性一起使用:

      1. 配置 infinispan 缓存,以定期从缓存中删除过期的票据。

        batch
        /subsystem=infinispan/cache-container=security:add(default-cache=auth-cache)
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache:add()
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache/expiration=EXPIRATION:add(lifespan=3540000,max-idle=3540000)
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache/memory=object:add(size=1000)
        run-batch

        以下属性定义 ticket 过期:

        • Life span:间隔,以毫秒为单位,从 KDC 请求新证书。将lifespan 属性 的值设置为比 KDC 定义的寿命小。
        • max-idle : Interval,以毫秒为单位,如果缓存未使用,则应从缓存中删除有效票据。
        • max-entries :要保留在缓存中的 kerberos ticket 的最大数量副本。该值对应于数据源中配置的连接数量。
      2. 创建安全域.

        batch
        /subsystem=security/security-domain=KerberosDatabase:add(cache-type=infinispan)
        /subsystem=security/security-domain=KerberosDatabase/authentication=classic:add
        /subsystem=security/security-domain=KerberosDatabase/authentication=classic/login-module="KerberosDatabase-Module":add(code="org.jboss.security.negotiation.KerberosLoginModule",module="org.jboss.security.negotiation",flag=required, module-options={ "debug" => "false", "storeKey" => "false", "useKeyTab" => "true", "keyTab" => "/path/to/eap.keytab", "principal" => "PRINCIPAL@SERVER.COM", "doNotPrompt" => "true", "refreshKrb5Config" => "true", "isInitiator" => "true", "addGSSCredential" => "true", "credentialLifetime" => "-1"})
        run-batch
        • 将 Microsoft JDBC 驱动程序用于 SQL 服务器时,请在 module-options 中添加属性和值 "wrapGSSCredential" SAS "true"。
        • 为进行调试,请将 module-optionsdebug 属性的值更改为 true
    • 在 Elytron 中使用 kerberos:

      1. 在 Elytron 中设置 kerberos 工厂。

        /subsystem=elytron/kerberos-security-factory=krbsf:add(debug=false, principal=PRINCIPAL@SERVER.COM, path=/path/to/keytab, request-lifetime=-1, obtain-kerberos-ticket=true, server=false)
      2. 创建身份验证配置以使用 kerberos 工厂。

        /subsystem=elytron/authentication-configuration=kerberos-conf:add(kerberos-security-factory=krbsf)
      3. 创建身份验证上下文.

        /subsystem=elytron/authentication-context=ds-context:add(match-rules=[{authentication-configuration=kerberos-conf}])
  3. 使用 Kerberos 保护数据源.

    • 如果您使用旧安全性:

      1. 将数据源配置为使用安全域。

        /subsystem=datasources/data-source=KerberosDS:add(connection-url="URL", min-pool-size=0, max-pool-size=10, jndi-name="java:jboss/datasource/KerberosDS", driver-name=<jdbc-driver>.jar, security-domain=KerberosDatabase, allow-multiple-users=false, pool-prefill=false, pool-use-strict-min=false, idle-timeout-minutes=2)
      2. 配置特定于供应商的连接属性。

        /subsystem=datasources/data-source=KerberosDS/connection-properties=<connection-property-name>:add(value="(<kerberos-value>)")

        示例:Oracle 数据库的连接属性.

        /subsystem=datasources/data-source=KerberosDS/connection-properties=oracle.net.authentication_services:add(value="(KERBEROS5)")
    • 如果使用 Elytron:

      1. 配置数据源以使用身份验证上下文。

        /subsystem=datasources/data-source=KerberosDS:add(connection-url="URL", min-pool-size=0, max-pool-size=10, jndi-name="java:jboss/datasource/KerberosDS", driver-name=<jdbc-driver>.jar, elytron-enabled=true, authentication-context=ds-context, allow-multiple-users=false, pool-prefill=false, pool-use-strict-min=false, idle-timeout-minutes=2)
      2. 配置特定于供应商的连接属性。

        /subsystem=datasources/data-source=KerberosDS/connection-properties=<connection-property-name>:add(value="(<kerberos-value>)")

        示例:Oracle 数据库的连接属性

        /subsystem=datasources/data-source=KerberosDS/connection-properties=oracle.net.authentication_services:add(value="(KERBEROS5)")

      在使用 kerberos 身份验证时,建议对数据源使用以下属性和值:

      • pool-prefill=false
      • pool-use-strict-min=false
      • idle-timeout-minutes

    如需支持的属性列表,请参阅 Datasource Attributes

12.11. Datasource Statistics

为数据源启用统计集合后 ,您可以查看数据源的运行时统计信息

12.11.1. 启用数据源统计信息

默认情况下不启用数据源统计您可以使用管理 CLI 或管理控制台启用数据源统计信息收集

使用管理 CLI 启用数据源统计信息

以下管理 CLI 命令启用 ExampleDS 数据源的统计信息收集:

注意

在受管域中,在此命令前加上 /profile=PROFILE_NAME

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=statistics-enabled,value=true)

重新加载服务器以使更改生效。

使用管理控制台启用数据源统计信息

使用以下步骤,通过管理控制台为数据源启用统计信息收集。

  1. 导航到 ConfigurationSubsystemsDatasources & DriversDatasources
  2. 选择数据源并点击 View
  3. 单击属性选项卡下的 编辑
  4. Statistics Enabled 字段设置为 ON,再单击 Save。此时会出现一个弹出窗口,表示更改需要重新加载才能生效。
  5. 重新加载服务器:

    • 对于单机服务器,请单击弹出窗口中的重新加载链接,以重新加载服务器。
    • 对于受管域,单击弹出窗口中的 Topology 链接。从 Topology 选项卡中,选择相应的服务器,再选择重新加载服务器的重新加载选项

12.11.2. 查看数据源统计信息

您可以使用管理 CLI 或管理控制台查看数据源的运行时统计信息

使用管理 CLI 查看数据源统计信息

以下管理 CLI 命令检索 ExampleDS 数据源的核心 统计信息:

注意

在受管域中,在这些命令前加上 /host=HOST_NAME/server=SERVER_NAME

/subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "ActiveCount" => 1,
        "AvailableCount" => 20,
        "AverageBlockingTime" => 0L,
        "AverageCreationTime" => 122L,
        "AverageGetTime" => 128L,
        "AveragePoolTime" => 0L,
        "AverageUsageTime" => 0L,
        "BlockingFailureCount" => 0,
        "CreatedCount" => 1,
        "DestroyedCount" => 0,
        "IdleCount" => 1,
        ...
}

以下管理 CLI 命令检索 ExampleDS 数据源的 JDBC 统计数据:

/subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "PreparedStatementCacheAccessCount" => 0L,
        "PreparedStatementCacheAddCount" => 0L,
        "PreparedStatementCacheCurrentSize" => 0,
        "PreparedStatementCacheDeleteCount" => 0L,
        "PreparedStatementCacheHitCount" => 0L,
        "PreparedStatementCacheMissCount" => 0L,
        "statistics-enabled" => true
    }
}
注意

由于统计信息是运行时信息,因此务必指定 include-runtime=true 参数。

如需了解所有可用统计数据的详细列表,请参阅数据源统计信息

使用管理控制台查看数据源统计信息

若要从管理控制台查看数据源统计信息,可从 Runtime 选项卡中导航到 Datasources 子系统,选择数据源,再单击 View

如需了解所有可用统计数据的详细列表,请参阅数据源统计信息

12.12. 数据源调优

有关监控和优化 数据源子 系统性能的提示,请参阅 性能调优指南 中的数据源和资源适配器 调优小节。

12.13. 容量策略

JBoss EAP 支持定义 Jakarta Connectors 部署的容量策略,包括数据源。容量策略定义池的物理连接的创建方式,称为容量递增和销毁,称为容量递减。默认策略设置为为每个请求创建一个连接以增加容量,并在为容量增加调度闲置超时时销毁所有连接。

要配置容量策略,您需要指定一个容量递增器类、容量递减器类或两者。

示例:定义容量策略

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-incrementer-class, value="org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer")

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-decrementer-class, value="org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer")

您还可以对指定容量递增器或递减器类配置属性。

示例: 为容量策略配置属性

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-incrementer-properties.size, value=2)

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-decrementer-properties.size, value=2)

MaxPoolSize Incrementer Policy

类名称org.jboss.jca.core.connectionmanager.pool.capacity.MaxPoolSizeIncrementer

MaxPoolSize incrementer 策略将为每个请求填充池的最大大小。当您希望始终保持最大连接数时,此策略很有用。

大小增加器策略

类名称org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer

大小递增器策略将根据每个请求的指定连接数填充池。如果您想增加每个请求的连接数以增加连接数,从而预期下一个请求还需要连接,此策略很有用。

表 12.3. 大小策略属性
名称描述

Size

应创建的连接数

注意

这是默认的递增策略,大小值为 1。

水印提高器策略

类名称org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkIncrementer

Watermark incrementer 策略会将池填入每个请求的指定连接数。如果要让池中始终保持指定数量的连接,此策略很有用。

表 12.4. 水印策略属性
名称描述

spalmark

连接数的水位线

MinPoolSize Decrementer Policy

类名称org.jboss.jca.core.connectionmanager.pool.capacity.MinPoolSizeDecrementer

MinPoolSize 修剪器策略会将池减小到每个请求的最小大小。如果要限制每个空闲超时请求后的连接数量,此策略很有用。池将以先出先出(FIFO)的方式运行。

大小延迟策略

类名称org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer

Size 减少程序策略会根据每个空闲超时请求的指定连接数来减少池。

表 12.5. 大小策略属性
名称描述

Size

应销毁的连接数

如果要减少每个空闲超时请求的连接数,以预计池使用量随着时间的推移会降低,此策略很有用。

池将以先出先出(FIFO)的方式运行。

TimedOut Decrementer 策略

类名称org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutDecrementer

TimedOut 减少程序策略将删除每个空闲超时请求已从池中超时的所有连接。该池将以第一个 In Last Out(FILO)方式运行。

注意

此策略是默认的递减策略。

TimedOut/FIFO 发布者策略

类名称org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutFIFODecrementer

TimedOutFIFO 减少crementer 策略将删除每个空闲超时请求已从池中超时的所有连接。池将以先出先出(FIFO)的方式运行。

水印 Decrementer 策略

类名称org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkDecrementer

Watermark 减少者策略会将池数减少到每个空闲超时请求的指定连接数。如果要让池中始终保持指定数量的连接,此策略很有用。池将以先出先出(FIFO)的方式运行。

表 12.6. 水印策略属性
名称描述

spalmark

连接数的水位线

12.14. 加入跟踪

可以记录 enlistment trace,以帮助查找在 XAResource 实例获取期间发生的错误情况。启用插入跟踪后,jca 子系统会为每个池操作创建一个异常对象,以便在需要时生成准确的堆栈追踪;但也会产生性能开销。

自 JBoss EAP 7.1 起,默认情况下禁用了注册跟踪。您可以通过将 enlistment -trace 属性设置为 true 来使用管理 CLI 为数据源启用条目记录。

为非 XA 数据源启用加入跟踪。

data-source --name=DATASOURCE_NAME --enlistment-trace=true

启用 XA 数据源的加入跟踪。

xa-data-source --name=XA_DATASOURCE_NAME --enlistment-trace=true
警告

启用加入跟踪可能会对性能造成影响。

12.15. 数据源配置示例

12.15.1. MySQL Datasource 示例

以下是具有连接信息、基本安全性和验证选项的 MySQL 数据源配置示例。

示例:MySQL Datasource 配置
<datasources>
  <datasource jndi-name="java:jboss/MySqlDS" pool-name="MySqlDS">
    <connection-url>jdbc:mysql://localhost:3306/jbossdb</connection-url>
    <driver>mysql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <driver-class>com.mysql.cj.jdbc.Driver</driver-class>
      <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
示例:MySQL JDBC Driver module.xml 文件
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-8.0.12.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>
管理 CLI 命令示例

此示例配置可通过以下管理 CLI 命令来实现:

  1. 添加 MySQL JDBC 驱动程序作为核心模块。

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    重要

    使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

    技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

    如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

  2. 注册 MySQL JDBC 驱动程序。

    /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
  3. 添加 MySQL 数据源。

    data-source add --name=MySqlDS --jndi-name=java:jboss/MySqlDS --driver-name=mysql --connection-url=jdbc:mysql://localhost:3306/jbossdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter

12.15.2. MySQL XA 数据源示例

这是带有 XA 数据源属性、基本安全性和验证选项的 MySQL XA 数据源配置示例。

示例:MySQL XA 数据源配置
<datasources>
  <xa-datasource jndi-name="java:jboss/MySqlXADS" pool-name="MySqlXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      mysqldb
    </xa-datasource-property>
    <driver>mysql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <driver-class>com.mysql.cj.jdbc.Driver</driver-class>
      <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
示例:MySQL JDBC Driver module.xml 文件
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-8.0.12.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>
管理 CLI 命令示例

此示例配置可通过以下管理 CLI 命令来实现:

  1. 添加 MySQL JDBC 驱动程序作为核心模块。

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    重要

    使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

    技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

    如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

  2. 注册 MySQL JDBC 驱动程序。

    /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
  3. 添加 MySQL XA 数据源。

    xa-data-source add --name=MySqlXADS --jndi-name=java:jboss/MySqlXADS --driver-name=mysql --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mysqldb"}

12.15.3. PostgreSQL 数据源示例

以下是具有连接信息、基本安全性和验证选项的 PostgreSQL 数据源配置示例。

示例:PostgreSQL 数据源配置
<datasources>
  <datasource jndi-name="java:jboss/PostgresDS" pool-name="PostgresDS">
    <connection-url>jdbc:postgresql://localhost:5432/postgresdb</connection-url>
    <driver>postgresql</driver>
    <security>
        <user-name>admin</user-name>
        <password>admin</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
        <validate-on-match>true</validate-on-match>
        <background-validation>false</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="postgresql" module="com.postgresql">
        <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
示例:PostgreSQL JDBC Driver module.xml 文件
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.postgresql">
  <resources>
    <resource-root path="postgresql-42.x.y.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

在上例中,请确保将¼x.y 替换为您的驱动程序版本号

其他资源

管理 CLI 命令示例

您可以使用以下 CLI 命令将 PostgreSQL JDBC 驱动程序和 PostgreSQL 数据源添加到 JDBC API 中:

  1. 添加 PostgreSQL JDBC 驱动程序作为核心模块。

    module add --name=com.postgresql --resources=/path/to/postgresql-42.x.y.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api

    在上例中,请确保将¼x.y 替换为您的驱动程序版本号

    重要

    使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

    技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

    如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

  2. 注册 PostgreSQL JDBC 驱动程序。

    /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=com.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
  3. 添加 PostgreSQL 数据源。

    data-source add --name=PostgresDS --jndi-name=java:jboss/PostgresDS --driver-name=postgresql --connection-url=jdbc:postgresql://localhost:5432/postgresdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter

12.15.4. PostgreSQL XA Datasource 示例

这是带有 XA 数据源属性、基本安全性和验证选项的 PostgreSQL XA 数据源配置示例。

示例:PostgreSQL XA 数据源配置
<datasources>
  <xa-datasource jndi-name="java:jboss/PostgresXADS" pool-name="PostgresXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="PortNumber">
      5432
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      postgresdb
    </xa-datasource-property>
    <driver>postgresql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="postgresql" module="com.postgresql">
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
示例:PostgreSQL JDBC Driver module.xml 文件
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.postgresql">
  <resources>
    <resource-root path="postgresql-42.x.y.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

在上例中,请确保将¼x.y 替换为您的驱动程序版本号

其他资源

管理 CLI 命令示例

您可以使用以下 CLI 命令将 PostgreSQL JDBC 驱动程序和 PostgreSQL 数据源添加到 JDBC API 中:

  1. 添加 PostgreSQL JDBC 驱动程序作为核心模块。

    module add --name=com.postgresql --resources=/path/to/postgresql-42.x.y.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api

    在上例中,请确保将¼x.y 替换为您的驱动程序版本号

    重要

    使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

    技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

    如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

  2. 注册 PostgreSQL JDBC 驱动程序。

    /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=com.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
  3. 添加 PostgreSQL XA 数据源。

    xa-data-source add --name=PostgresXADS --jndi-name=java:jboss/PostgresXADS --driver-name=postgresql --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","PortNumber"=>"5432","DatabaseName"=>"postgresdb"}

12.15.5. Oracle Datasource 示例

以下是具有连接信息、基本安全性和验证选项的 Oracle 数据源配置的示例。

示例:甲骨文数据源配置
<datasources>
  <datasource jndi-name="java:jboss/OracleDS" pool-name="OracleDS">
    <connection-url>jdbc:oracle:thin:@localhost:1521:XE</connection-url>
    <driver>oracle</driver>
    <security>
        <user-name>admin</user-name>
        <password>admin</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
        <validate-on-match>true</validate-on-match>
        <background-validation>false</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
        <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
示例:Oracle JDBC Driver module.xml 文件
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
    <resources>
        <resource-root path="ojdbc7.jar"/>
    </resources>
    <dependencies>
      <module name="javaee.api"/>
      <module name="sun.jdk"/>
      <module name="ibm.jdk"/>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
    </dependencies>
</module>
管理 CLI 命令示例

此示例配置可通过以下管理 CLI 命令来实现:

  1. 添加 Oracle JDBC 驱动程序作为核心模块。

    module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    重要

    使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

    技术预览功能不包括在红帽生产服务级别协议(SLA)中,且其功能可能并不完善。因此,红帽不建议在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。

    如需有关技术预览功能支持范围的信息,请参阅红帽客户门户网站中的技术预览功能支持范围。

  2. 注册 Oracle JDBC 驱动程序。

    /subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
  3. 添加 Oracle 数据源。

    data-source add --name=OracleDS --jndi-name=java:jboss/OracleDS --driver-name=oracle --connection-url=jdbc:oracle:thin:@localhost:1521:XE --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter

12.15.6. Oracle XA 数据源示例

重要

要让 XA 恢复正常工作,必须应用以下设置才能访问 Oracle XA 数据源的用户:value 用户 定义为从 JBoss EAP 连接到 Oracle 的用户:

  • GRANT SELECT ON sys.dba_pending_transactions TO user;
  • GRANT SELECT ON sys.pending_trans$ TO user;
  • GRANT SELECT ON sys.dba_2pc_pending TO user;
  • GRANT EXECUTE ON sys.dbms_xa TO user;

这是带有 XA 数据源属性、基本安全性和验证选项的 Oracle XA 数据源配置的示例。

示例:Oracle XA 数据源配置
<datasources>
  <xa-datasource jndi-name="java:jboss/OracleXADS" pool-name="OracleXADS">
    <xa-datasource-property name="URL">
      jdbc:oracle:thin:@oracleHostName:1521:orcl
    </xa-datasource-property>
    <driver>oracle</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
      <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
示例:Oracle JDBC Driver module.xml 文件
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
    <resources>
        <resource-root path="ojdbc7.jar"/>
    </resources>
    <dependencies>
      <module name="javaee.api"/>
      <module name="sun.jdk"/>
      <module name="ibm.jdk"/>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
    </dependencies>
</module>
管理 CLI 命令示例

此示例配置可通过以下管理 CLI 命令来实现:

  1. 添加 Oracle JDBC 驱动程序作为核心模块。

    module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    重要

    使用 模块 管理 CLI 命令添加和删除模块,仅作为技术预览提供。此命令不适合在受管域中使用,或在远程连接管理 CLI 时使用。在生产环境中,应当手动添加 和删除模块

    技术预览功