JBoss 7.4.10.GA与远程IBM MQ集成及资源适配器部署故障排查

问题根源 #

报错WFLYCTL0412: Required services that are not installed:" => ["jboss.ra."wmq.jmsra""]说明IBM MQ的资源适配器（RA）未被JBoss正确加载，核心原因是域模式下的RA部署方式错误或模块配置缺失。

解决方案步骤 #

1. 明确部署模式：域模式 vs 独立模式 #

你使用domain.xml配置，说明是JBoss域模式，此时不要使用standalone/deployments目录，域模式的部署目录为domain/deployments，模块目录为domain/modules。

2. 选择一种RA部署方式（二选一） #

方式一：通过域部署目录加载RA

• 将wmq.jmsra.rar复制到JBoss域控制器的domain/deployments目录。
• 编辑domain.xml，在<deployments>节点下添加RA部署声明：

<deployments>
    <!-- 其他部署 -->
    <deployment name="wmq.jmsra.rar" runtime-name="wmq.jmsra.rar"/>
</deployments>

• 在你的服务器组配置（如<server-group name="main-server-group">）中添加部署引用：

<server-group name="main-server-group" profile="full">
    <!-- 其他配置 -->
    <deployments>
        <deployment-ref name="wmq.jmsra.rar"/>
    </deployments>
</server-group>

• 保持resource-adapters子系统中的<archive>值为wmq.jmsra.rar。

方式二：通过模块系统加载RA（推荐，便于版本管理）

• 创建模块目录：在domain/modules下新建com/ibm/mq/main路径。
• 将wmq.jmsra.rar放入该目录，并创建module.xml文件：

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.5" name="com.ibm.mq">
    <resources>
        <resource-root path="wmq.jmsra.rar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.jms.api"/>
        <module name="javax.transaction.api"/>
        <module name="org.jboss.logging"/>
    </dependencies>
</module>

• 修改resource-adapters子系统中的<archive>值为模块引用：

<archive>module:com.ibm.mq</archive>

3. 修正RA配置中的必填参数 #

你的配置中channel、hostName等关键参数为空，这会导致RA初始化失败，必须填写IBM MQ的实际配置：

<config-property name="channel">SYSTEM.DEF.SVRCONN</config-property> <!-- 替换为你的MQ通道名 -->
<config-property name="hostName">mq-server-ip</config-property> <!-- 替换为MQ服务器IP -->
<config-property name="PortNumber">1414</config-property> <!-- 替换为MQ监听端口 -->
<config-property name="queueManager">QMGR_NAME</config-property> <!-- 替换为队列管理器名称 -->

注：ServerName参数可以移除，hostName+PortNumber已足够指定MQ服务器地址。

4. 验证与排查 #

• 重启JBoss域控制器和服务器实例。
• 查看域控制器的日志文件（domain/log/host-controller.log），检查是否有RA加载的错误信息（如依赖缺失、文件损坏）。
• 确认IBM MQ的RA版本与JBoss EAP 7.4兼容（推荐使用MQ 9.2及以上版本的RA）。

内容的提问来源于stack exchange，提问作者Nitin Dang