Germinate's Blog

Jboss eap7.1 配置部署入门

发表于 | | 阅读量 次

本文介绍了Linux系统下Jboss-eap-7.1服务器 standalone 模式的配置部署入门。90%的内容来自jboss的官方配置文档，只不过从初学者的角度对配置过程进行了梳理，介绍了部署应用时普遍会用到的配置项。参考本文，大多数应用可以在Jboss-eap-7.1上成功运行。
下文出现的命令、代码和文件地址中，${JBOSS_HOME}指代Jboss-eap-7.1所处的根目录。

安装与启动、停止

安装：所谓“安装”，就是把下载好的包解压到某个地址即可。
启动：进入${JBOSS_HOME}/bin目录，执行 standalone.sh 脚本，看到输出started in XXXXms，就证明服务器已经成功启动。
停止：服务器的进程通常都是后台运行。停止时，在${JBOSS_HOME}/bin目录下执行 ./jboss-cli.sh --connect，进入命令行管理页面，输入shutdown命令，即可停止服务器。（也可以合并为一条语句：./jboss-cli.sh --connect command=:shutdown）
配置：修改${JBOSS_HOME}/bin下的 standalone.conf 文件，可以改变Jboss启动的配置。
在文件中加入 JAVA_HOME="/path/jdk"，可以指定使用的jdk，而不必依赖于系统默认的java环境变量。
在文件中加入 LANG=Zh_CN.GB18030，可以设定语言环境为中文
修改JAVA_OPTS，可以设置JVM的启动参数

基本概念

  • jboss-eap-7.1有两种运行模式，standalone——单机模式 和 domain——集群模式。本文介绍了单机模式的部署。
  • jboss启动服务器时，默认读取的配置文件是${JBOSS_HOME}/standalone/configuration/standalone.xml。也可以指定读取其他配置文件，命令是./standalone.sh --server-config=standalone-custom.xml
  • jboss-cli（command line interface），是jboss的命令行管理工具。执行${JBOSS_HOME}/bin/jboss-cli.sh即可进入。通过命令行实现部署卸载应用、配置系统设置和执行管理任务的功能。使用该工具修改系统配置时，最终也会作用到standalone.xml中。直接改xml的方式非常直观，所以更受本人青睐，本文所有配置示例均是直接修改xml。
  • Management Console，管理控制台。是jboss提供的web管理系统，地址在http://localhost:9990/console/App.html， 所有的操作均可通过jboss-cli实现，本文不再介绍该工具。

standalone.xml配置

地址配置

默认的配置，服务器启动后只能通过localhost访问。通过网卡IP地址访问时，需修改配置文件。找到下面的配置片段

1
2
3
4
5
6
7
8
<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>
</interfaces>

将 public 标签下的地址修改为网卡ip地址，这样就能通过IP地址访问。也可以设置为0.0.0.0，机器上所有可用的ip地址均可以访问。
不建议修改 management 标签下的地址，个人认为远程的管理存在一定风险，还是直接在机器上做比较好。

端口配置

修改监听的端口，找到下面的配置片段：

1
2
3
4
5
6
7
<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="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    ………… ………… …………
</socket-binding-group>

根据需要修改不同协议监听的端口。管理控制台的端口默认是9990，也可以在此处修改。

数据源配置

数据源配置如下面代码所示，标签的含义非常明晰，不再针对标签做解释说明。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<subsystem xmlns="urn:jboss:domain:datasources:5.0">
    <datasources>
	    ………… ………… …………	
        <datasource jndi-name="java:jboss/datasources/MyDB" pool-name="MyDB" enabled="true" use-java-context="true" use-ccm="true">
            <connection-url>jdbc:jtds:sybase://10.2.55.16:11100/testDB;charset=cp936</connection-url>
            <driver>jtds124</driver>
            <pool>
                <min-pool-size>1</min-pool-size>
                <max-pool-size>20</max-pool-size>
                <prefill>true</prefill>
            </pool>
            <security>
                <user-name>user</user-name>
                <password>password</password>
            </security>
            <validation>
                <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"/>
                <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
                <validate-on-match>true</validate-on-match>
                <exception-sorter class-name="org.jboss.resource.adapter.jdbc.vendor.SybaseExceptionSorter"/>
            </validation>
            <timeout>
                <blocking-timeout-millis>30000</blocking-timeout-millis>
                <idle-timeout-minutes>1</idle-timeout-minutes>
            </timeout>
            <statement>
                <track-statements>true</track-statements>
            </statement>
        </datasource>
        <drivers>
			………… ………… …………		
            <driver name="jtds124" module="net.sourceforge.jtds.jdbc.124">
                <xa-datasource-class>net.sourceforge.jtds.jdbcx.JtdsDataSource</xa-datasource-class>
            </driver>
        </drivers>
    </datasources>
</subsystem>

配置好数据源后，需要将数据库驱动jar包放在 ${JBOSS_HOME}/modules 下正确的位置，才能成功绑定数据源。驱动的放置目录要和driver标签中module的值保持一致，以上面的配置为例，驱动jar包的路径应该是
${JBOSS_HOME}/modules/modules/net/sourceforge/jtds/jdbc/124/main/
main不要体现在属性中，124文件夹下必须要有main文件夹，jar包在main文件夹中。
main文件夹下还要有module.xml，配置示例如下：

1
2
3
4
5
6
7
8
9
10
11
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="net.sourceforge.jtds.jdbc.124">
    <resources>
        <resource-root path="jtds-1.2.4.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
        <module name="org.jboss.as.connector"/>
    </dependencies>
</module>

module.xml中module标签的 name 属性要和standalone.xml中driver标签的 module 属性保持一致。
符合JDBC标准的数据源如此就配置完成。但本例中使用的是jtds，所以还要做额外的操作，否则无法正确绑定数据源。在驱动jar包的META-INF文件夹中新建 services 文件夹，然后新建名为 java.sql.Driver 的文件，在文件第一行写下Driver的路径。本例中，java.sql.Driver文件的内容如下：
net.sourceforge.jtds.jdbc.Driver
经过上述配置，在启动服务器时，看到输出Started Driver service with driver-name = jtds124，证明数据源配置成功。

Undertow容器配置

经过下面的配置操作，修改了接收http请求的设置、容器默认的字符集，移除了jboss默认的欢迎页面，开启了http访问的日志以及输出http请求和响应的信息。
找到如下配置片段，默认配置为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
            </server>
    <servlet-container name="default">
        ………… ………… …………
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        ………… ………… …………
    </filters>
</subsystem>

修改后的配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true" url-charset="GBK" decode-url="false"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <!-- <location name="/" handler="welcome-content"/> -->
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
            <http-invoker security-realm="ApplicationRealm"/>
            <filter-ref name="request-dumper"/>
            <access-log pattern="combined" directory="${jboss.home.dir}/standalone/log"/>
        </host>
            </server>
    <servlet-container name="default" default-encoding="GBK" use-listener-encoding="true">
        ………… ………… …………
    </servlet-container>
    <!-- <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers> -->
    <filters>
        ………… ………… …………
        <filter name="request-dumper" class-name="io.undertow.server.handlers.RequestDumpingHandler" module="io.undertow.core"/>
    </filters>
</subsystem>

  1. 修改http请求设置：在http-listener标签中，增加了url-charset和decode-url。其中url-charset默认使用的UTF-8，可以根据需要修改。decode-url指是否使用字符集解码url和参数，默认为true。设为false则交由后续代码进行解码处理。http-listener的详细配置属性点击这里。
  2. 修改容器默认字符集：在servlet-container标签中，default-encoding设置所有应用的字符集（默认为utf-8），use-listener-encoding指是否使用listener定义的编码。servlet-container的详细配置属性点击这里。
  3. 移除Jboss默认欢迎页面：配置文件中注释的部分，就是jboss默认欢迎页面的配置。直接注释就是将其移除，也可以将默认地址映射到某个应用上。
  4. 开启http访问日志：在host标签下增加access-log这一标签，即可将http请求的信息记在日志中，便于调试。directory是日志存放的目录，默认文件名为access_log.log。pattern是要日志中记录的信息，预定义了common和combined两种模式，combined的信息丰富一些。自定义的输出模式详见此处。
  5. 输出http请求和响应的信息：在filters标签下增加名为request-dumper的filter，在host标签下增加命名一致的filter-ref，就能在jboss日志中输出每一个http请求的request和response信息，便于调试。

注：对于上面的操作1，早期版本中，在extensions和management标签之间增加下面的配置代码，可以实现同样的效果。但自从wildfly 8 之后，jboss放弃tomcat容器转而使用undertow，所以下面的配置不再起作用了。

1
2
3
4
<system-properties>
    <property name="org.apache.catalina.connector.URI_ENCODING" value="GBK"/>
    <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true"/>
</system-properties>

部署应用

下面将介绍三种部署模式，但官方推荐在生产环境中，使用第三种手动模式，前两种可以应用于开发环境。
应用部署相关的默认配置如下：

1
2
3
<subsystem xmlns="urn:jboss:domain:deployment-scanner:2.0">
            <deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000" runtime-failure-causes-rollback="${jboss.deployment.scanner.rollback.on.failure:false}"/>
</subsystem>

scan-interval是每隔多少毫秒扫描deployments文件夹下的变化。如果设定的值小于1，则只在启动时扫描。

全自动模式

在默认配置下，将war包上传至${JBOSS_HOME}/standalone/deployments，服务器会在启动时和每5000毫秒间隔，检查deployments下的文件变化，部署应用。

半自动模式

增加属性 auto-deploy-zipped="false"
上传应用myApp.war至deployments文件夹后，在deployments文件夹下新建一个文件，命名为myApp.war.dodeploy，服务器检测到这个文件后，则会开始执行部署。更多配置详情点击这里。

手动模式

增加属性scan-enabled="false"
此模式是官方推荐的生产环境部署应用方式，无需将应用上传至deployments文件夹下。首先保证myApp.war在服务器上，假设其路径为/usr/me/myApp.war。
启动服务器，并使用./jboss-cli.sh --connect命令进入命令行管理界面。执行命令deploy /usr/me/myApp.war部署应用。取消部署时，在命令行管理界面执行 undeploy myApp.war。
应用的数据会在${JBOSS_HOME}/standalone/data/content下，并且standalone.xml最下方会出现deployments标签，显示已经部署的应用。

题外话

既然是一个入门级的教程，就介绍下jboss一系列的产品。因为改名，导致jboss系列越来越乱，下面做一个简单梳理。
Undertow： Jboss自主研发的Servlet容器。
Jboss AS（Application Server）： Jboss社区版的早期版本，由于和Jboss eap名称相近，在Jboss AS7之后就改名为Wildfly。内部封装的容器是基于Tomcat的升级版。
WildFly： 版本号从WildFly 8.0开始，由Jboss AS改名而来。内部封装的容器是Undertow。
Jboss EAP（Enterprise Application Platform）：Jboss的企业版。会将社区版中验证过的，成熟的技术引入该版本，支持周期长。6的版本以Jboss AS7为基础；7的版本以Wildfly为基础。

参考资料

  1. 非jdbc驱动配置services