7.2 Web 应用部署问题

7.2 Web 应用部署问题

第七章：Tomcat 常见问题与故障排除

7.2 Web 应用部署问题

Web 应用部署是 Tomcat 使用过程中至关重要的一步，也是容易出现问题的环节。一个看似简单的部署过程，背后涉及到文件结构、配置解析、类加载、资源访问等多个方面。本节将深入探讨 Tomcat 中常见的 Web 应用部署问题，并提供详细的故障排除方法和实践指导。

7.2.1 部署描述符 (web.xml) 问题

web.xml 文件，作为 Web 应用的部署描述符，是 Tomcat 理解和运行 Web 应用的关键。它的正确性直接影响着应用的启动和功能。

7.2.1.1 web.xml 缺失或格式错误

问题描述:

最基础的错误就是 web.xml 文件缺失或格式不正确。Tomcat 规范要求在标准 Web 应用的 WEB-INF 目录下必须存在 web.xml 文件（虽然Servlet 3.0 之后可以不依赖 web.xml，但为了兼容性和最佳实践，通常仍会保留）。如果 web.xml 文件不存在，或者 XML 格式不符合规范（例如标签未闭合、属性值缺失等），Tomcat 在部署时会报错，导致应用无法启动。

可能原因:

• 文件缺失: 开发人员忘记在 WEB-INF 目录下创建 web.xml 文件。

• 路径错误: web.xml 文件放置在错误的目录，例如 WEB-INF 的子目录或者同级目录。

• 格式错误: 手动编写 web.xml 时，XML 语法错误，例如标签未正确闭合，属性值引号缺失，或者使用了非法的 XML 字符。

• 构建工具配置错误: 使用 Maven 或 Gradle 等构建工具时，web.xml 文件未被正确包含到 WAR 包中。

故障排除和解决方法:

1. 检查文件是否存在: 确认 WAR 包中 WEB-INF 目录下是否存在 web.xml 文件。如果手动部署，检查应用目录的 WEB-INF 目录下是否存在 web.xml 文件。

2. 检查 XML 格式: 使用 XML 验证工具（例如在线 XML 验证器或 IDE 的 XML 校验功能）检查 web.xml 文件是否符合 XML 规范。常见的错误包括：

   • 标签未闭合：例如 <servlet> 没有对应的 </servlet> 结束标签。

   • 属性值缺失引号：例如 <servlet-name>MyServlet 应该写成 <servlet-name>"MyServlet"</servlet-name>.

   • 使用了 XML 保留字符但未进行转义：例如在文本内容中使用了 <、>、& 等字符，需要使用 <、>、& 等转义字符。

3. 查看 Tomcat 日志: Tomcat 启动时会解析 web.xml 文件，如果解析出错，会在日志文件中记录详细的错误信息（通常在 catalina.out 或 localhost.<日期>.log 文件中）。仔细查看日志文件，定位具体的错误行号和错误类型。

4. 使用示例 web.xml: 如果不熟悉 web.xml 的编写，可以参考 Tomcat 官方文档或网上提供的示例 web.xml 文件，根据自己的应用需求进行修改。

代码实践:

以下是一个简单的 web.xml 示例，包含了 Servlet、Servlet 映射和欢迎页面配置：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                             http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">
    <display-name>MyWebApp</display-name>
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>
    <servlet>
        <servlet-name>MyServlet</servlet-name>
        <servlet-class>com.example.MyServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>MyServlet</servlet-name>
        <url-pattern>/myservlet</url-pattern>
    </servlet-mapping>
</web-app>
​

内容详解:

• <web-app> 根元素: xmlns、xmlns:xsi、xsi:schemaLocation 和 version 属性定义了 XML Schema，确保 web.xml 文件符合 Servlet 规范。

• <display-name>: Web 应用的显示名称，通常在管理界面中显示。

• <welcome-file-list>: 定义欢迎文件列表，当用户访问根路径时，Tomcat 会按照列表顺序查找并返回第一个存在的文件。

• <servlet>: 定义 Servlet，包括 <servlet-name> (Servlet 名称) 和 <servlet-class> (Servlet 类全限定名)。

• <servlet-mapping>: 将 Servlet 映射到 URL 模式，<url-pattern> 定义了 URL 匹配规则，当请求 URL 匹配该模式时，请求会被转发到对应的 Servlet 处理。

7.2.1.2 Servlet/Filter/Listener 配置错误

问题描述:

web.xml 中 Servlet、Filter 和 Listener 的配置错误是常见的部署问题。配置错误可能导致 Servlet 无法加载、Filter 拦截器链失效、Listener 事件监听器无法响应等问题。

可能原因:

• 类名错误: <servlet-class>、<filter-class> 或 <listener-class> 中指定的类名拼写错误或类路径不正确，导致 Tomcat 无法找到对应的类。

• 初始化参数错误: <init-param> 配置的初始化参数名称或值错误，或者 Servlet/Filter/Listener 代码中没有正确读取和处理这些参数。

• 映射错误: <servlet-mapping> 或 <filter-mapping> 中的 URL 模式配置错误，导致请求无法正确路由到 Servlet 或 Filter。

• Filter 顺序错误: <filter-mapping> 的顺序会影响 Filter 的执行顺序，如果顺序配置不当，可能会导致 Filter 链逻辑错误。

• Listener 配置重复或冲突: 重复配置同一个 Listener 或者配置了相互冲突的 Listener。

故障排除和解决方法:

1. 检查类名: 仔细检查 <servlet-class>、<filter-class> 和 <listener-class> 中指定的类全限定名是否正确，包括包名和类名拼写是否一致。确保这些类已经编译并放置在 Web 应用的 WEB-INF/classes 目录下或 JAR 包中。

2. 检查初始化参数: 确认 <init-param> 的 <param-name> 和 <param-value> 配置是否正确，Servlet/Filter/Listener 代码中是否正确获取和使用了这些参数。可以通过日志输出参数值进行验证。

3. 检查 URL 映射: 仔细检查 <servlet-mapping> 和 <filter-mapping> 中的 <url-pattern> 配置，确保 URL 模式符合预期，没有语法错误，并且没有与其他映射冲突。可以使用通配符 (*) 进行更灵活的 URL 匹配。

4. 检查 Filter 顺序: 如果使用了多个 Filter，检查 <filter-mapping> 的配置顺序，确保 Filter 的执行顺序符合业务逻辑需求。Filter 的执行顺序按照 <filter-mapping> 在 web.xml 中出现的顺序决定。

5. 检查 Listener 配置: 避免重复配置同一个 Listener，如果使用了多个 Listener，确保它们之间没有冲突，并且事件处理逻辑正确。

代码实践:

Servlet 配置示例:

<servlet>
    <servlet-name>ConfigServlet</servlet-name>
    <servlet-class>com.example.ConfigServlet</servlet-class>
    <init-param>
        <param-name>configPath</param-name>
        <param-value>/WEB-INF/config.properties</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>ConfigServlet</servlet-name>
    <url-pattern>/config</url-pattern>
</servlet-mapping>
​

Filter 配置示例:

<filter>
    <filter-name>EncodingFilter</filter-name>
    <filter-class>com.example.EncodingFilter</filter-class>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>EncodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
</filter-mapping>
​

Listener 配置示例:

<listener>
    <listener-class>com.example.ContextListener</listener-class>
</listener>
​

内容详解:

• <init-param> (初始化参数): 允许在 web.xml 中为 Servlet、Filter 和 Listener 配置初始化参数，这些参数在 Servlet、Filter 或 Listener 初始化时会被读取。

• <load-on-startup> (Servlet 启动加载): 对于 Servlet，<load-on-startup> 元素指定 Servlet 在 Web 应用启动时加载的顺序。数值越小，优先级越高，越先加载。负数或不配置表示 Servlet 在第一次请求时加载。

• <dispatcher> (Filter 调度器): 对于 Filter，<dispatcher> 元素指定 Filter 拦截的请求类型，常见的类型包括 REQUEST (直接请求), FORWARD (请求转发), INCLUDE (请求包含), ERROR (错误处理)。

7.2.1.3 上下文参数和初始化参数配置问题

问题描述:

上下文参数 (<context-param>) 和初始化参数 (<init-param>) 是在 web.xml 中配置应用级别和组件级别参数的重要方式。配置错误可能导致应用无法读取到正确的配置信息，影响功能运行。

可能原因:

• 参数名错误: <context-param> 或 <init-param> 中的 <param-name> 拼写错误，导致应用代码无法通过正确的参数名获取到配置值。

• 参数值错误: <param-value> 配置的值不符合预期格式或类型，例如需要整数类型却配置了字符串，或者路径配置错误。

• 参数作用域混淆: 混淆了上下文参数和初始化参数的作用域。上下文参数是整个 Web 应用共享的，而初始化参数是 Servlet、Filter 或 Listener 组件私有的。

• 参数覆盖问题: 在不同的配置文件中（例如 context.xml 和 web.xml）配置了相同的上下文参数，导致参数值被覆盖，最终生效的不是预期的值。

故障排除和解决方法:

1. 检查参数名: 仔细检查 <param-name> 的拼写，确保与应用代码中获取参数时使用的名称完全一致（大小写敏感）。

2. 检查参数值: 确认 <param-value> 的值是否符合预期格式和类型。例如，如果是文件路径，检查路径是否正确，文件是否存在。如果是数值类型，检查值是否在有效范围内。

3. 理解参数作用域: 明确上下文参数和初始化参数的区别和作用域。上下文参数使用 ServletContext.getInitParameter(String name) 获取，初始化参数使用 ServletConfig.getInitParameter(String name) 获取。

4. 避免参数覆盖: 如果需要在多个配置文件中配置参数，明确参数的优先级规则。通常 context.xml 中的配置会覆盖 web.xml 中的同名上下文参数。建议在一个地方集中管理配置，避免混淆和覆盖。

5. 日志输出参数值: 在应用启动时，将读取到的上下文参数和初始化参数值输出到日志文件中，以便检查配置是否正确加载。

代码实践:

上下文参数配置示例:

<context-param>
    <param-name>appName</param-name>
    <param-value>MyWebApp</param-value>
</context-param>
<context-param>
    <param-name>databaseUrl</param-name>
    <param-value>jdbc:mysql://localhost:3306/mydb</param-value>
</context-param>
​

Servlet 中获取上下文参数示例 (Servlet 代码):

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.PrintWriter;
public class ContextParamServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        String appName = getServletContext().getInitParameter("appName");
        String databaseUrl = getServletContext().getInitParameter("databaseUrl");
        resp.setContentType("text/html;charset=UTF-8");
        PrintWriter out = resp.getWriter();
        out.println("<html><body>");
        out.println("<h1>Context Parameters</h1>");
        out.println("<p>App Name: " + appName + "</p>");
        out.println("<p>Database URL: " + databaseUrl + "</p>");
        out.println("</body></html>");
    }
}
​

内容详解:

• <context-param> (上下文参数): 在 <web-app> 元素下配置，定义整个 Web 应用共享的初始化参数。

• <init-param> (初始化参数): 在 <servlet>、<filter> 或 <listener> 元素下配置，定义组件私有的初始化参数。

• ServletContext.getInitParameter(String name): 在 Servlet、Filter 或 Listener 中，通过 ServletContext 对象获取上下文参数。ServletContext 对象可以通过 getServletContext() 方法获取。

• ServletConfig.getInitParameter(String name): 在 Servlet 或 Filter 中，通过 ServletConfig 对象获取初始化参数。ServletConfig 对象在 Servlet 或 Filter 的 init() 方法中作为参数传入。

7.2.1.4 安全约束配置错误

问题描述:

web.xml 中的安全约束配置 (<security-constraint>) 用于定义 Web 应用的安全策略，例如哪些 URL 需要认证、允许哪些角色访问等。配置错误可能导致安全策略失效，或者过度限制访问，影响用户体验。

可能原因:

• URL 模式错误: <url-pattern> 配置的安全约束 URL 模式不正确，导致安全约束没有应用到预期的 URL。

• 角色名错误: <role-name> 中指定的角色名与应用中的角色定义不一致，导致角色验证失败。

• 认证方式配置错误: <auth-method> 配置的认证方式（例如 BASIC, FORM, DIGEST, CLIENT-CERT）与实际使用的认证方式不匹配。

• 用户数据约束错误: <user-data-constraint> 配置的用户数据约束（例如 CONFIDENTIAL, INTEGRAL）与服务器配置不符，导致安全连接要求无法满足。

• 逻辑冲突: 配置了相互冲突的安全约束，例如对同一个 URL 模式同时定义了允许访问和拒绝访问的约束。

故障排除和解决方法:

1. 检查 URL 模式: 仔细检查 <url-pattern> 的配置，确保 URL 模式能够正确匹配需要保护的资源。可以使用更精确的 URL 模式，避免过度保护或遗漏保护。

2. 检查角色名: 确认 <role-name> 中指定的角色名与应用中的角色定义一致。角色名通常在 Tomcat 的 tomcat-users.xml 文件或外部用户认证系统中定义。

3. 检查认证方式: 根据应用的安全需求选择合适的认证方式，并在 <auth-method> 中正确配置。常用的认证方式包括：

   • BASIC: 基本认证，通过 HTTP Basic Authentication 机制进行用户名密码认证。

   • FORM: 表单认证，通过 HTML 表单收集用户名密码，并跳转到登录页面进行认证。

   • DIGEST: 摘要认证，类似于基本认证，但密码不以明文传输，安全性更高。

   • CLIENT-CERT: 客户端证书认证，通过客户端 SSL 证书进行身份验证。

4. 检查用户数据约束: 如果配置了 <user-data-constraint>，确保服务器支持配置的数据约束。例如，CONFIDENTIAL 要求使用 HTTPS 连接。

5. 避免逻辑冲突: 仔细审查所有的安全约束配置，确保没有逻辑冲突。可以使用更细粒度的 URL 模式和角色定义，避免安全策略过于宽泛或过于严格。

6. 测试安全策略: 部署应用后，进行全面的安全测试，验证安全策略是否生效，是否能够正确限制未授权用户的访问。

代码实践:

安全约束配置示例 (需要认证才能访问 /admin 目录下的资源，并需要 admin 角色):

<security-constraint>
    <web-resource-collection>
        <web-resource-name>Admin Resources</web-resource-name>
        <url-pattern>/admin/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>
<login-config>
    <auth-method>FORM</auth-method>
    <form-login-config>
        <form-login-page>/login.jsp</form-login-page>
        <form-error-page>/login-error.jsp</form-error-page>
    </form-login-config>
</login-config>
<security-role>
    <role-name>admin</role-name>
</security-role>
​

内容详解:

• <security-constraint> (安全约束): 定义一组安全约束规则，包括需要保护的资源、访问权限要求和用户数据约束。

• <web-resource-collection> (Web 资源集合): 定义需要保护的 Web 资源，通过 <url-pattern> 指定 URL 模式。

• <auth-constraint> (认证约束): 定义访问受保护资源所需的角色。<role-name> 指定允许访问的角色名。

• <user-data-constraint> (用户数据约束): 定义用户数据传输的安全要求。<transport-guarantee> 指定传输保证级别，CONFIDENTIAL 表示需要保密传输（HTTPS）。

• <login-config> (登录配置): 配置 Web 应用的登录方式。<auth-method> 指定认证方式，<form-login-config> 用于配置表单认证的登录页面和错误页面。

• <security-role> (安全角色): 定义 Web 应用中使用的角色。<role-name> 指定角色名。

mermaid 图表:

内容详解:

此图表展示了 web.xml 文件的主要结构，<web-app> 作为根元素，包含了各种子元素，例如显示名称、欢迎文件列表、Servlet 定义和映射、Filter 定义和映射、Listener 定义、上下文参数、安全约束、登录配置和安全角色等。通过这个图表，可以更直观地理解 web.xml 的组织结构和包含的主要配置项。