Apache Tomcat 部署 Vaadin 应用：兼容性问题排查与解决方案

1. 问题现象与初步排查

在尝试将 vaadin web 应用程序部署到 apache tomcat 服务器时，开发者可能会遇到应用程序无法访问，浏览器显示 404 not found 错误的情况。尽管 tomcat 服务器本身运行正常，且其他非 vaadin 应用可能可以正常访问，但 vaadin 应用的特定路径（例如 /your-app-name/）却无法解析。

典型的服务器访问日志可能会记录如下错误：

127.0.0.1 - - [15/Nov/2022:11:02:51 -0500] GET /icsprojects-version-1.0/ HTTP/1.1 404 783
127.0.0.1 - - [15/Nov/2022:11:18:00 -0500] GET /icsprojects-version-1.0/ HTTP/1.1 404 783

这些日志条目明确指出，当尝试访问部署的 Vaadin 应用程序路径时，服务器返回了 404 状态码，表示资源未找到。

在遇到此类问题时，开发者通常会进行以下初步排查：

• 确认 WAR 包完整性：检查 Vaadin 项目是否已正确打包为 .war 文件，并且该文件包含了所有必要的类和资源。
• 部署方式检查：确保 WAR 文件已通过 Tomcat Manager 界面成功部署，或直接放置在 Tomcat 的 webapps 目录下并等待其自动解压和部署。
• 构建工具检查：无论使用 Gradle 还是 Maven，都已仔细审查 pom.xml 或 build.gradle 文件，确保 Vaadin 依赖和构建配置正确无误。
• 尝试部署不同应用：尝试部署自定义 Vaadin 应用和社区提供的 Vaadin 示例应用，结果均出现相同问题。

尽管进行了这些排查，问题依旧存在，这表明可能存在更深层次的兼容性问题。

2. 核心原因：Java EE 与 Jakarta EE 的兼容性鸿沟

导致 Vaadin 应用在某些 Tomcat 版本上部署失败的根本原因，在于 Java EE (Java Platform, Enterprise Edition) 和 Jakarta EE (Jakarta Enterprise Edition) 之间的包名和规范变更。

• *Java EE (javax.)*：传统的 Java EE 规范，包括 Servlet、JSP、EJB 等 API，其核心包名以 `javax.开头。例如，Servlet API 的包是javax.servlet`。
• *Jakarta EE (jakarta.)*：随着 Java EE 捐赠给 Eclipse 基金会并更名为 Jakarta EE，为了避免与 Oracle 现有的 `javax.包冲突，所有相关的 API 包名都从javax.更改为jakarta.。例如，Servlet API 的包现在是jakarta.servlet`。

Apache Tomcat 的版本兼容性：

• Tomcat 9 及更早版本：这些版本实现了 Java EE 8 及更早的规范，因此它们期望应用程序使用 javax.* 包。
• Tomcat 10 及更高版本：这些版本实现了 Jakarta EE 9 及更高版本规范，因此它们期望应用程序使用 jakarta.* 包。

Vaadin 框架的兼容性：

• Vaadin 14 及更早版本：这些版本是基于 Java EE (使用 javax.* 包) 构建的。
• Vaadin 23 及更高版本：这些版本已迁移到 Jakarta EE (使用 jakarta.* 包)，并需要兼容 Jakarta EE 的 Servlet 容器。

问题症结： 当您尝试将一个基于 Java EE (使用 javax.* 包) 的 Vaadin 应用（如 Vaadin 14）部署到 Tomcat 10 或更高版本时，Tomcat 无法找到应用程序所需的 javax.* 包和 API。这导致应用程序无法正确初始化，从而在访问时返回 404 错误，因为 Web 容器未能识别并加载该应用。

3. 解决方案与部署策略

针对上述兼容性问题，有以下几种解决方案：

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

22

查看详情

3.1 方案一：降级 Apache Tomcat 版本

最直接和简单的解决方案是使用与您的 Vaadin 版本兼容的 Tomcat 版本。

• 如果您的 Vaadin 应用是基于 Java EE (Vaadin 14 或更早版本)，请使用 Apache Tomcat 9 或更早版本。
• 下载并安装相应版本的 Tomcat，然后按照标准的 WAR 包部署流程进行操作。

3.2 方案二：升级 Vaadin 版本（如适用）

如果项目允许且有资源进行迁移，可以考虑将 Vaadin 应用升级到支持 Jakarta EE 的版本（Vaadin 23 及更高版本）。

• 升级 Vaadin 版本通常涉及更新项目依赖、调整代码以适应新版本 API 的变化，并确保所有第三方库也与新的 Vaadin 和 Jakarta EE 环境兼容。
• 升级后，您的 Vaadin 应用将能够与 Tomcat 10+ 及其实现的 Jakarta EE 规范无缝协作。

3.3 方案三：使用嵌入式 Web 服务器（推荐 Spring Boot）

对于学校项目或需要快速部署的场景，使用 Spring Boot 及其内置的嵌入式 Web 服务器（如 Tomcat、Jetty 或 Undertow）是一种非常简便且强大的解决方案。

优点：

• 简化部署：无需单独安装和配置外部 Tomcat 服务器，应用程序可以打包成一个可执行的 JAR 文件，直接运行。
• 消除兼容性问题：Spring Boot 会自动管理其嵌入式服务器的版本和依赖，通常能够很好地处理 Vaadin 应用的兼容性。
• 易于开发和测试：开发过程中可以直接通过 IDE 运行应用，无需部署到外部服务器。

Spring Boot 示例配置： 在您的 Vaadin 项目中，如果使用 Maven，可以在 pom.xml 中添加 Spring Boot Web Starter 依赖。

<dependencies>
    <!-- Vaadin dependencies -->
    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-spring-boot-starter</artifactId>
    </dependency>

    <!-- Spring Boot Web Starter (includes embedded Tomcat) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Other Spring Boot dependencies if needed -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

然后，创建一个 Spring Boot 主应用程序类：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class YourVaadinApplication {

    public static void main(String[] args) {
        SpringApplication.run(YourVaadinApplication.class, args);
    }
}

通过这种方式，您可以将 Vaadin 应用打包为可执行 JAR，并通过 java -jar your-app.jar 命令直接运行，而无需担心外部 Tomcat 的版本兼容性问题。

4. 部署注意事项与最佳实践

• 详细日志分析：在部署过程中，务必仔细检查 Tomcat 的日志文件（如 catalina.out、localhost.<date>.log 或 manager.<date>.log）。这些日志通常会提供关于部署失败原因的详细堆栈跟踪信息，例如类加载错误、找不到特定包等，这对于诊断问题至关重要。
• 上下文路径：确保您在访问 Vaadin 应用时使用的 URL 与其在 Tomcat 中部署的上下文路径（Context Path）相匹配。例如，如果 WAR 文件名为 my-app.war，通常可以通过 http://localhost:8080/my-app/ 访问。
• 内存与资源：确保 Tomcat 有足够的内存来运行 Vaadin 应用程序，尤其是在开发环境中。Vaadin 应用可能比简单的静态页面消耗更多资源。
• 安全性：对于生产环境，应配置 Tomcat 的安全性，包括用户认证、SSL/TLS 加密等。如果使用 ngrok 进行隧道传输，也要考虑其安全性配置。
• 持续集成/持续部署 (CI/CD)：对于更复杂的项目，考虑采用 CI/CD 流程自动化构建、测试和部署 Vaadin 应用，以减少手动错误并提高效率。

总结

Vaadin 应用在 Apache Tomcat 上的 404 部署错误，核心在于 Java EE 和 Jakarta EE 规范之间的不兼容性，尤其是 javax.* 和 jakarta.* 包的冲突。理解这一背景是解决问题的关键。通过选择合适的 Tomcat 版本（Tomcat 9 及更早版本），或升级 Vaadin 到支持 Jakarta EE 的版本，或采用 Spring Boot 嵌入式服务器，开发者可以有效地解决这些兼容性挑战。对于大多数现代项目，尤其是那些追求部署简便性的项目，Spring Boot 的嵌入式服务器方法通常是更优选的解决方案。

以上就是Apache Tomcat 部署 Vaadin 应用：兼容性问题排查与解决方案的详细内容，更多请关注php中文网其它相关文章！