企业官网建设流程全解析

如果你正在接手或维护一套 datax-web（社区里通常写成 datax-web，也有叫 datax web 的），并且最近被要求把它从 Spring Boot 2.x 升到 Spring Boot 3、JDK 8 升到 JDK 17，那你大概率已经感受到了那种“说大不大、说小不小”的升级焦虑。我这次升级的是团队内部基于 datax-web 二次开发的调度和同步平台，老代码一路从 Spring Boot 2.1 走到 2.3，JDK 8 用了很多年，直到新部署的机器镜像默认只给 JDK 17、部分配套组件也要求新版兼容，才终于下定决心做一次整体迁移。

datax-web 的本质是给阿里 DataX 套了一层 Web 管控面，解决的是任务可视化配置、手动/定时触发、执行日志查看、权限管理这些事；底层真正跑数据同步的还是 DataX 的 Python 脚本。所以升级过程中最难啃的不是 DataX，而是外面这层 Spring Boot 应用。这篇文章按照我实际改造的顺序来写：老项目盘点、版本路线确定、javax/jakarta 迁移、依赖矩阵、代码实操、构建排错、回归验证，最后是一份可以直接抄的常见问题清单。适合正在做老 Spring Boot 项目升级的人参考，也适合对 Spring Boot 3 和 Spring Security 6 迁移还没概念的同学当案例看。

1. 升级前的技术摸底：先别急着改 pom.xml

1.1 先搞清楚你手里的是哪个 datax-web 分支

datax-web 这个项目社区里有好几个流传版本，比较常见的是 WeiYe-Jing/datax-web 这个仓库，以及后来各种公司 fork 出来继续魔改的增强分支。这些版本的模块划分大体一致：一个 web 控制台负责用户和任务管理，一个 executor 执行器负责拉取任务并调用 datax.py，前端一般是 Vue + Element UI 构建的静态页面。但具体到你手里的代码，内部包名、自定义功能、部署方式可能千差万别。

我这次拿到的是一套基于 2.x 老分支的二次开发版本，登录模块自己改了 JWT 逻辑，任务调度基于 Quartz，部署方式是打 jar 包然后用 supervisor 托管，完全没有用官方推荐的 Docker 方式。如果你手里的也是这种“祖传代码”，我建议升级前先花半天把模块边界理清楚，至少要知道：自定义代码集中在哪个模块、前端产物是打进 Spring Boot 的 static 目录还是单独用 Nginx 托管、有没有外部系统通过 API 在调用 datax-web 的接口。这些因素会直接影响你的升级范围。

1.2 升级前必须列清楚的检查清单

老项目升级最怕的是“打开 IDE 到处报错”，根本原因是依赖太多、版本太乱。我建议先做一次全量盘点，把下面这张表填完再动手：

• 目标运行环境：JDK 版本、操作系统位数、是否有特殊安全基线（比如必须用非 root 运行）。
• 数据库连接池与驱动：用的是什么连接池，MySQL 驱动是 com.mysql:mysql-connector-java 还是新坐标。
• 安全认证方式：Spring Security、Shiro、JWT 过滤器，还是数据库表硬编码账号。
• 任务调度框架：Quartz、xxl-job，还是自己写的 Timer 线程池。
• API 文档组件：是否用了 springfox Swagger，Boot 3 下 springfox 基本不可用。
• 前端产物：登录页、任务配置页是否依赖老接口返回结构。
• 反射和序列化：代码里有没有 Fastjson、Gson 对泛型 TypeReference 的使用。
• 外部中间件：Redis、ES、MQ，哪些是强依赖，哪些启动时连不上也不用挂。

这些内容看着琐碎，但决定你之后是“半天搞定”还是“调一周”。我自己就是没提前登记 WebSocket 的使用场景，结果升级到 Spring Boot 3 之后被 javax.websocket 的依赖冲突卡了两个小时。

2. JDK 17 和 Spring Boot 3：版本路线一次性定清楚

2.1 为什么是 JDK 17 而不是继续留在 JDK 8

Spring Boot 3 的底层是 Spring Framework 6，而 Spring Framework 6 从设计上就把 Java 17 作为基线版本，这意味着你想用 Boot 3，就必须先把 JDK 升到 17 或更高。JDK 17 又是 LTS 长期支持版本，新环境默认装的就是它，老应用直接跑在 JDK 17 上，老框架的反射、字节码代理很容易触发模块化封装问题，所以与其在 JDK 17 上继续跑老 Boot 2.3 去补各种 add-opens，不如直接连框架一起升级。

如果你在 Windows 或者 Linux 上装 JDK 17，步骤并不复杂：下载对应的 .tar.gz 或安装包，配置 JAVA_HOME 和 PATH，然后在启动脚本里显式写死 /path/to/jdk17/bin/java。这里特别提醒一点，服务器上如果同时存在 JDK 8 和 JDK 17，千万不要依赖全局 PATH，否则日志里会出现“Unsupported major.minor version 61.0”这种没头没脑的提示。部署脚本里写死绝对路径是最稳妥的。

2.2 javax 到 jakarta 的包名大迁移

这是 Spring Boot 3 升级最明显、也最费手的一个变化。Java EE 移交到 Eclipse 基金会之后，命名空间从 javax 变成了 jakarta，Spring Boot 3 内置的 Servlet 容器已经是 Tomcat 10.1 / Jetty 11 / Undertow 2.2，对应的是 Jakarta EE 9+ API。所以老代码里的 javax.servlet.* 在编译期直接就找不到类了。

我实际遇到的主要是这几个包的替换：

替换方法我用的是全局搜索兼顾人工确认。IDE 自带 Refactor 功能（比如 IDEA 的 Java EE Migration 流程）能帮你改一部分，但代码里如果是字符串拼接、XML 配置、SPI 文件里写了 javax 全类名，就得自己排查了。最靠谱的命令是grep -R "javax\." src/把所有命中一条条过一遍，宁可多花半小时，也不要漏掉某个隐藏在常量里的字符串。

2.3 依赖版本矩阵：照着这张表挑版本

升级依赖不是把所有版本号往大了调就行，关键是要确定各个库对 Spring Boot 3 / JDK 17 的适配情况。我这次整理出一套验证过能配合使用的版本组合，你直接照抄问题不大，但要根据自己项目实际微调：

如果你项目里用了 Redis，还要注意 spring-boot-starter-data-redis 在 Boot 3 下依赖的是 Lettuce 6.1+，老项目的连接池配置项有一些变化，启动后要重点看日志里 Redis 连接是否正常输出。

3. 核心代码改造实操：安全、持久层、WebSocket、启动参数

3.1 Spring Security 6：WebSecurityConfigurerAdapter 已经彻底没了

Spring Security 6 改动最大的地方是 WebSecurityConfigurerAdapter 这个基类被删掉了，以前写一坨继承类的配置方式全部要改成 SecurityFilterChain Bean。如果你项目里用的是 Shiro，影响没这么大，但只要涉及 Spring Security 就要重写。我这次改造的登录模块刚好是 JWT + Security 的组合，踩的坑基本都集中在这块。

新标准写法是定义 SecurityFilterChain Bean，我直接贴一段可以用的配置：

@Configuration @EnableWebSecurity public class SecurityConfig { @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http.csrf(csrf -> csrf.disable()) .authorizeHttpRequests(auth -> auth .requestMatchers("/login", "/static/**", "/api/auth/**").permitAll() .anyRequest().authenticated() ) .formLogin(form -> form.loginPage("/login").permitAll()) .logout(logout -> logout.logoutSuccessUrl("/login")) .sessionManagement(session -> session .sessionCreationPolicy(SessionCreationPolicy.STATELESS) ); return http.build(); } @Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }

注意几个关键差异：旧版的.antMatchers("/**")变成了.requestMatchers("/**")；旧版的.authorizeRequests()变成了.authorizeHttpRequests()；旧版的.and()链式调用全部移除。URL 匹配规则也有细节变化，旧的/user/*只匹配一级路径，新写法推荐用/user/**，我实际测试中前者在 Security 6 下的匹配行为有坑。另外过滤器顺序非常重要，如果你自定义了 JWT 认证过滤器，记得用http.addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)明确指定位置，否则会出现“该登录的没登录，不该拦的全拦了”的诡异现象。

3.2 MyBatis-Plus 和 MyBatis 在 Boot 3 下的兼容处理

如果你的老项目用了 MyBatis-Plus 3.4.x，直接升级到 Spring Boot 3 后启动时会报 “Failed to introspect Class” 或 “ClassNotFound” 之类的错误，本质原因是老版本的 starter 还在走 Spring Boot 2 的自动装配机制。官方从 3.5.3 开始适配 Boot 3，我这边用的是 3.5.5，实测比较稳。另外一个坑是坐标：MyBatis-Plus 官方后来提供了专门给 Spring Boot 3 用的 starter，名字叫 mybatis-plus-spring-boot3-starter，引入的时候别还是引入原来的 mybatis-plus-boot-starter。

还有几个容易忽略的点：分页插件、乐观锁插件这些内部 Bean 在 Boot 3 下初始化时机有变化，多个数据源时尤其容易因为初始化顺序问题导致 Mapper 扫描不到。如果项目里自己定义过 SqlSessionFactory 或 MybatisSqlSessionFactoryBean，建议把所有 Mapper 路径和类型别名重新核对一遍。我这次就遇到过 Mapper XML 文件里写了旧包名的 parameterType，编译不报错，启动也不报错，但运行时任务列表接口直接 500，最后排查半天才发现是 XML 里的全限定类名还带 javax。

3.3 WebSocket 和 Servlet 容器相关的替换

datax-web 这类管控平台经常用 WebSocket 向前端推送执行日志，升级过程中这一块也很容易出问题。首先要做的还是把代码里的javax.websocket.*全部替换成jakarta.websocket.*，包括@ServerEndpoint注解和WebSocketContainer这些。其次要确认依赖坐标，Spring Boot 3 工程里建议直接用spring-boot-starter-websocket，它会自动带出兼容 Jakarta API 的 Tomcat 包。

如果你用的是独立 Tomcat 部署 war 包而不是可执行 jar，升级后还要特别注意 servlet-api 冲突。我遇到过“本地启动一切正常，放到 Tomcat 上就报 WebSocket endpoint 无法注册”的情况，最后是删掉了打包产物里混入的旧 javax.websocket-api 才解决。顺序上建议先跑可执行 jar，稳定了再考虑 war 部署，能少踩一半坑。

3.4 JVM 启动参数：--add-opens 是绕不开的

JDK 17 对内部的强封装比 JDK 8 严格很多，Spring 的 CGLIB 代理、MyBatis-Plus 对实体字段的反射、Fastjson 处理泛型反序列化，都可能在运行期出现InaccessibleObjectException。我这边最终在启动脚本里加了一组 add-opens 参数，覆盖了常见的反射场景，贴出来供参考：

JAVA_OPTS=" -server -Xms1024m -Xmx2048m -XX:MaxMetaspaceSize=512m --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.text=ALL-UNNAMED --add-opens=java.base/java.time=ALL-UNNAMED --add-opens=java.sql/java.sql=ALL-UNNAMED " java $JAVA_OPTS -jar datax-web-*.jar

如果你是 Windows 环境，启动脚本里把写法换成set "JAVA_OPTS=..."，其他内容一样。这些参数加上去对正常逻辑没有副作用，属于“宁可多开也不要启动到一半挂掉”的保险做法。如果你用的是高版本 Spring Boot 或者某些库升级后已经适配了模块化系统，可以逐步删掉不用的项，但没必要一开始就精简。

3.5 自动装配机制和配置文件迁移

老项目如果自己写过 Spring Boot 自动配置类，升级时要注意 Spring Boot 3 已经不再读取META-INF/spring.factories里配置的自动装配类，必须新建META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件，把自动配置类的全限定名写进去。这个改动非常隐蔽，因为如果只是普通 @Configuration 注解类，启动时仍然生效；只有自动装配类的加载方式变了。

配置项方面，Spring Boot 3 对 @ConfigurationProperties 的绑定校验更严格，类型不匹配会直接启动失败而不是忽略。我用下来最大的感受是：老项目里那些约定俗成的配置前缀，如果之前没写规范，升级后往往会浮出水面。比如spring.redis.*改成spring.data.redis.*这个变化不知道坑了多少老项目，你回头看看自己的 application.yml，是不是还在用spring.redis.host？

4. 构建、启动与 DataX 任务回归

4.1 先让编译干净跑通

升级代码改完之后，第一件要做的事不是启动服务，而是把整个工程在 JDK 17 下编译通过。我用的是 Maven，命令很简单：

mvn clean package -Dmaven.test.skip=true

如果模块很多，建议先mvn clean compile快速暴露出所有 javac 编译错误，重点是 javax 相关 import。如果编译时报 “程序包 javax.servlet 不存在”，说明代码里还有老包名没改完。全部改完之后再打完整包，避免每次都在打包阶段被中断。

datax-web 的前端一般也是构建后甚至打进后端 static 目录的。如果你是前端、后端一起构建，记得重新构建前端 dist 产物，并确认产物目录和你后端静态资源路径一致。我见过只升后端不重新打前端包，结果访问登录页 404 的情况，不是后端的问题，是前端文件没了。

4.2 启动时的数据库和中间件核对

编译通过只是第一步，真正启动时候才会暴露一堆运行期问题。数据库这块，老项目常用的是com.mysql:mysql-connector-java坐标，这个坐标在 Boot 3 下虽然还能拉到包，但新版本 MySQL 官方已经改为com.mysql:mysql-connector-j，建议直接更换，并且版本至少 8.0.33 以上，配合 MySQL 8.0.36 比较稳。

数据源连接串也要检查一下。MySQL 8 默认认证插件是 caching_sha2_password，如果连接串里没有启用 allowPublicKeyRetrieval，在非 SSL 连接下经常会报公钥检索失败；连接串里加上allowPublicKeyRetrieval=true基本能解决。我这边最后稳定的配置大概是这个样子：

spring: datasource: url: jdbc:mysql://127.0.0.1:3306/datax_web?useUnicode=true&characterEncoding=utf8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai driver-class-name: com.mysql.cj.jdbc.Driver username: root password: xxxxxx data: redis: host: 127.0.0.1 port: 6379 database: 0

启动时重点观察日志里的 Mapper 映射记录和数据源初始化情况，不要看到“Started ... in x seconds”就觉得万事大吉，Spring Boot 的启动成功不代表所有 Bean 都初始化正确，很多懒加载的 Bean 要等第一次调用才报错。

4.3 跑通一条 DataX 同步任务才算升级完成

服务能起来只是第一阶段，真正的验收标准是在新版本下完整跑通一条 DataX 同步任务。我建议用最小场景来测：构建一个 MySQL 到 MySQL 的同步任务，手动运行，然后观察执行器是否正常拉取任务、是否成功调用 datax.py、日志是否能正常回写到 Web 控制台。

这个环节最容易出问题的不是 datax-web 本身，而是执行器节点上的环境配置。datax-web 的执行器需要知道 DataX 的安装路径，通常要配置 datax 的 home 目录和 python 环境变量。你升级的是控制面，底层 DataX 脚本版本不用动，但环境变量要重新确认一遍。另外一个常见的关联问题是调度系统：如果你公司用 DolphinScheduler 统一调度，它本身是可以调 DataX 任务的，通常用自带的 DataX 节点直接跑 datax.py，也可以通过脚本去调 datax-web 的 API。升级 datax-web 和 DolphinScheduler 之间没有硬冲突，但要小心两边 JDK 环境变量别被覆盖成同一个版本，尤其当两台服务部署在同一台机器时。

5. 常见问题速查表与升级后的几个细节

5.1 编译期和启动期问题速查

下面这个表是我升级过程中真实遇到的报错和对应解法，基本可以覆盖老 Boot 项目升 Boot 3 的大部分问题：

5.2 升级完还要做的三件事

第一，把整个团队的开发环境统一到新版本。仅改你本机的 IDEA Project SDK 和 Maven 编译器还不够，要把 CI 流水线里的 JDK 版本、Maven 配置、Docker 基础镜像全部改成 JDK 17，否则开发环境正常、测试环境编译失败的情况会反复出现。用 IDEA 创建 Spring Boot 3 项目的时候，默认模板也会用 JDK 17+，说明这已经是新常态。

第二，给数据库表做一次兼容性检查。datax-web 的官方表结构基本可以沿用，但你二次开发可能加过字段或表，升级之后要跑一遍 SQL 校验，尤其是 datetime 和 text 类型字段在不同 MySQL 版本下的行为差异。如果数据库里已经有大量任务配置，强烈建议升级前做一次全量备份。

第三，把监控补上。切换 JDK 17 和 Boot 3 之后，JVM 的内存模型和默认 GC 行为有变化，建议通过 spring-boot-starter-actuator 把 JVM 指标接进 Prometheus，重点看 Metaspace、老年代和线程数，不然流量上来之后才发现内存涨得比老版本快，排查成本很高。

5.3 几个值得记下来的经验

升级顺序上，我强烈建议分两步走：先单独在 JDK 17 下编译老 Boot 2.3 代码，把因为 JDK 版本引起的报错先收集一轮；然后再切换到 Boot 3 依赖，去处理框架层的问题。两个大变量叠加在一起的话，出了一行报错你很难判断到底是 JDK 引起的还是 Spring Boot 3 引起的。

javax 到 jakarta 的替换别只盯着自己写的 Java 文件，也要排查依赖传递。用mvn dependency:tree查一下有没有老 jar 把 javax.servlet-api 或 javax.websocket-api 带了进来，有的话直接在 pom 里 exclude 掉。这种隐藏依赖最烦人，因为它不在你的代码里，编译期不报错，运行期才出问题。

安全配置升级的时候，不要照抄别人的博客配置，尤其是 URL 规则。把你项目里现在的所有接口路径列一张表，一条一条对应到 Security 6 的 requestMatchers 上，漏一个接口就可能导致整个管理页面登录失效或者静态资源全部 403。

最后说点个人感受。这种升级真正难的地方从来不是 Spring Boot 3 的新 API 有多难学，而是老项目里那些在 JDK 8 + Boot 2.x 时代一直没爆发的“小毛病”，会在新版本下集中冒出来。我这次白天改代码、晚上盯编译，花了差不多一周，收获最大的不是版本号终于变了，而是把项目里的自定义代码彻底梳理了一遍。如果你也在折腾同样的事，别慌，按照“盘点依赖、统一 JDK、替换包名、调整安全框架、回归数据同步任务”的顺序来，问题总能一个个啃完。特别提醒一句，升级前记得把 datax-web 里所有任务配置和调度计划导出一份备份，别问我为什么知道要备份。