为何无法在IIS虚拟目录中使用httpPlatformHandler部署TomEE应用？

环境信息 #

• Windows Server 2016
• IIS 10，已安装httpPlatformHandler v1.2模块
• TomEE 9.1.1 microprofile路径：C:\tomee\apache-tomee-9.1.1-microprofile
• JDK 11.0.18路径：C:\tomee\jdk-11.0.18+10
• 主ASP.Net应用访问地址：https://myserver.mydomain.tld/main/
• MyApp.war已部署，原访问地址（未改端口）：http://localhost:8080/myapp/
• 已创建名为myapp的虚拟目录，物理路径：C:\tomee\iis_virtual_directory

需求与问题 #

需要通过https://myserver.mydomain.tld/myapp/访问MyApp，但目前出现502.3 Bad Gateway错误，TomEE无法启动。

当前配置 #

虚拟目录下的web.config #

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
        </handlers>
        <httpPlatform processPath="C:\tomee\apache-tomee-9.1.1-microprofile\\bin\startup.bat" arguments="start" stdoutLogEnabled="true" stdoutLogFile="C:\tomee\iis_virtual_directory\log.txt">
            <environmentVariables>
                <environmentVariable name="JRE_HOME" value="C:\tomee\jdk-11.0.18+10" />
                <environmentVariable name="CATALINA_HOME" value="C:\tomee\apache-tomee-9.1.1-microprofile" />
                <environmentVariable name="CATALINA_OPTS" value="-Dport.http=%HTTP_PLATFORM_PORT%" />
            </environmentVariables>
        </httpPlatform>
    </system.webServer>
</configuration>

TomEE server.xml修改 #

<Server port="-1" shutdown="SHUTDOWN">
<Connector port="${port.http}" protocol="HTTP/1.1">

异常情况 #

• 将web.config配置放到c:\inetpub\wwwroot主web.config时，MyApp可正常访问，但主ASP.Net应用无法访问
• 修改主web.config中handler的path为myapp/*后，两个应用均可访问，但创建的myapp虚拟目录失去作用

问题原因及解决方案 #

1. 虚拟目录未转换为应用程序 #

IIS中单纯的虚拟目录不会独立加载自身的web.config配置，需将其转换为应用程序才能正确生效：

• 打开IIS管理器，找到myapp虚拟目录，右键选择转换为应用程序，可选择独立的应用程序池（避免与主ASP.Net应用冲突）。

2. web.config路径错误 #

processPath中多了一个冗余反斜杠，修改为正确路径：

<httpPlatform processPath="C:\tomee\apache-tomee-9.1.1-microprofile\bin\startup.bat" ...>

3. TomEE上下文路径不匹配 #

当通过/myapp虚拟目录访问时，TomEE应用的上下文路径需与虚拟目录一致：

• 将MyApp.war重命名为myapp.war，TomEE会自动部署到/myapp上下文；
• 或在TomEE的conf/server.xml中添加上下文配置：

<Context docBase="myapp" path="/myapp" reloadable="true"/>

4. httpPlatformHandler进程监控问题 #

startup.bat start会启动后台进程，导致httpPlatformHandler无法正确绑定端口和监控进程状态，改用catalina.bat run：

<httpPlatform processPath="C:\tomee\apache-tomee-9.1.1-microprofile\bin\catalina.bat" arguments="run" stdoutLogEnabled="true" stdoutLogFile="C:\tomee\iis_virtual_directory\log.txt">
    <environmentVariables>
        <environmentVariable name="JRE_HOME" value="C:\tomee\jdk-11.0.18+10" />
        <environmentVariable name="CATALINA_HOME" value="C:\tomee\apache-tomee-9.1.1-microprofile" />
        <environmentVariable name="CATALINA_OPTS" value="-Dport.http=%HTTP_PLATFORM_PORT% -Dcatalina.base=%CATALINA_HOME%" />
    </environmentVariables>
</httpPlatform>

5. 权限不足 #

确保IIS应用程序池身份对以下路径有读写权限：

• C:\tomee\apache-tomee-9.1.1-microprofile
• C:\tomee\iis_virtual_directory
• C:\tomee\jdk-11.0.18+10

可临时将应用程序池身份设为LocalSystem测试，或给对应身份分配权限。

验证步骤 #

1. 重启IIS和TomEE；
2. 访问https://myserver.mydomain.tld/myapp/检查是否正常；
3. 查看C:\tomee\iis_virtual_directory\log.txt日志排查启动错误；
4. 确认主ASP.Net应用https://myserver.mydomain.tld/main/可正常访问。

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