信创改造实战SpringBoot项目迁移到宝兰德BES 9.5.5的完整避坑指南1. 项目概述与迁移前思考先说背景。之前接手了一个典型的SpringBoot 2.7.13微服务项目原来部署方式是mvn package打成可执行jar包扔到服务器上nohup java -jar就完事。但客户侧明确要求走信创路线中间件必须国产化替换目标平台锁定为宝兰德BES Application Server 9.5.5。这意味着原先的内嵌Tomcat方案不能用了必须把SpringBoot应用以war包形式部署到BES上由BES接管HTTP服务和类加载环境。这里有个核心认知必须先纠正SpringBoot项目迁移到BES不是简单地把jar改成war扔进去就能跑。BES本质上是完整Java EE应用服务器它有自己的一套类加载体系、JNDI命名空间、安全管理器和部署规范。内嵌Tomcat方式下很多“约定大于配置”的默认行为在外部Servlet容器环境下会失效。比如SpringBoot自动装配里的ServletWebServerFactoryAutoConfiguration在没有内嵌容器依赖时根本不会生效再比如spring.main.web-application-type的推断逻辑也会因为类路径变化而改变。这篇博文适合谁看一是正在做信创迁移、需要把存量SpringBoot服务部署到BES或其他国产中间件如东方通TongWeb、金蝶天燕等的开发人员二是刚接触BES、想了解这个中间件部署机制的技术同学。我会把依赖改造、打包配置、控制台部署、以及我实际踩过的问题完整列出来基本可以按图索骥。先交代一下本次迁移涉及的核心组件清单后面所有配置都是基于这个版本组合验证过的操作系统CentOS 7.6x86_64JDK1.8.0_202BES 9.5.5内置OpenJDK或使用外部JDK均可但推荐统一用外部JDK应用框架SpringBoot 2.7.13 MyBatis-Plus 3.5.x目标中间件宝兰德BES Application Server 9.5.5构建工具Maven 3.6.3原部署方式内嵌Tomcat 9.0.x jar包方式2. BES 9.5.5环境准备与安装要点2.1 获取安装包与基础环境BES 9.5.5的安装包可以从宝兰德官方渠道获取注意区分版本——企业版安装包通常包含管理控制台、节点代理和完整的Java EE容器开发版可能阉割了部分集群能力但单机部署完全够用。我这边拿到的是Linux 64位安装包文件名类似bes-linux-x64-9.5.5.tar.gz。解压后的目录结构大概如下# 解压安装包 tar -zxvf bes-linux-x64-9.5.5.tar.gz -C /opt/bes/ cd /opt/bes/ ls -lh # 核心目录说明 # bin/ 启动脚本、管理命令 # domains/ 域目录创建域之后生成 # lib/ 中间件核心依赖 # modules/ 模块化组件 # property/ 配置文件模板注意BES安装路径不要包含中文和特殊字符建议统一放在/opt/或/usr/local/下否则后续启动脚本会报路径解析异常。2.2 创建域与启动管理控制台BES的部署模型和WebLogic很像核心概念就是“域Domain”。一个域包含管理服务器AdminServer和若干被管节点Managed Server所有应用部署操作都通过管理控制台完成。单机部署时可以只创建一个域管理服务器和业务服务器共用同一个实例减少资源开销。创建域的两种方式方式一命令行方式cd /opt/bes/bin ./asadmin create-domain --adminport 4848 --port 8080 mydomain这里adminport是管理控制台端口port是HTTP服务端口。asadmin是BES自带的域管理命令类似GlassFish的asadmin用起来很顺手。方式二交互式方式直接执行./asadmin create-domain不加参数它会引导你输入域名、端口、管理员账号密码。我建议用交互式方便设置管理员密码。创建成功后启动域./asadmin start-domain mydomain启动日志会输出到domains/mydomain/logs/server.log看到类似Server startup in [xxxx] milliseconds就说明启动成功了。此时访问http://服务器IP:4848可以进入管理控制台。2.3 JDK版本选择与配坑BES 9.5.5兼容JDK 8和JDK 11但我的项目是SpringBoot 2.7.13基础要求JDK 8所以统一用JDK 8运行BES。这里有个比较隐蔽的坑BES默认会使用自己内置的JRE如果你没配置外部JDK而这个内置JRE的版本不一定和应用的编译版本匹配极容易导致UnsupportedClassVersionError。建议强制指定外部JDK路径。修改domains/mydomain/config/domain.xml或启动脚本中的JAVA_HOME变量# 编辑启动脚本或设置环境变量 export JAVA_HOME/usr/local/jdk1.8.0_202 export PATH$JAVA_HOME/bin:$PATH # 重启域 ./asadmin restart-domain mydomain另外BES的JVM参数默认堆内存比较保守通常只有256M对微服务来说肯定不够。在控制台的“服务器配置 - JVM设置”里把-Xms1024m -Xmx2048m -XX:MaxMetaspaceSize512m配置进去确保应用运行期内存充足。提示BES对JDK的检测逻辑是从启动脚本所在环境变量中读取不是读/etc/profile。所以每次启动前务必保证JAVA_HOME已经export到当前shell否则它会fallback到内置JRE这个问题非常隐蔽排查起来也很耗时间。3. SpringBoot项目依赖改造核心章节3.1 打包方式从jar切换为war迁移第一步是修改pom.xml的打包方式和依赖。原来的spring-boot-starter-web自带了内嵌Tomcat在外部容器部署时会产生冲突必须排除掉。下面是我经过验证的完整依赖配置packagingwar/packaging properties java.version1.8/java.version spring-boot.version2.7.13/spring-boot.version /properties dependencies !-- Web依赖排除内嵌Tomcat -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId /exclusion /exclusions /dependency !-- BES API用于自定义ServletInitializer时引用 -- dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version4.0.1/version scopeprovided/scope /dependency !-- 其他业务依赖MyBatis-Plus、Redis、Nacos等按需保留 -- /dependencies关键点有两个spring-boot-starter-tomcat必须显式排除。如果不排除而直接打包成warBES部署时会检测到内嵌Tomcat相关的类触发类加载冲突表现通常是启动报NoClassDefFoundError: org/apache/catalina/...或者应用启动到一半直接卡死。javax.servlet-api的scope必须是provided。因为这个依赖在BES运行时由容器提供打不打包进去都行但如果不加这个依赖代码里引用ServletContext等API时编译会报错。为什么用javax而不是jakarta因为我们用的SpringBoot 2.x底层是javax规范BES 9.5.5同时支持javax和jakarta但2.x用javax没问题。3.2 SpringBootApplication启动类改造SpringBoot jar方式部署的启动类通常长这样SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }这种写法在war方式部署时有一个致命问题main方法只负责本地开发启动在外部Servlet容器中启动时容器根本不会执行main方法。容器启动的是ServletContainerInitializer体系所以需要另外提供一个SpringBootServletInitializer的子类重写configure方法SpringBootApplication public class DemoApplication extends SpringBootServletInitializer { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } Override protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) { // 参数必须传当前启动类 return builder.sources(DemoApplication.class); } }注意sources(DemoApplication.class)不能传错。有人习惯传this.getClass()如果被代理类包装过可能造成Spring扫描不到配置类应用会启动但是无法加载任何Controller。3.3 application.properties关键调整接下来说说配置文件。jar方式下很多外部化配置可以直接通过--spring.profiles.activexxx方式和nohup命令传参但war方式部署到BES后应用是由BES的部署模块加载的System.getProperty不一定能拿到JVM启动参数所以有几种做法第一种推荐在application.properties中直接固定Profile和上下文路径。# 指定当前环境为生产 spring.profiles.activeprod # 上下文路径即访问根路径 server.servlet.context-path/demo # 外部容器模式下端口配置不生效由容器负责监听 server.port8080这里强调一下server.port在war包部署到外部容器后是无效的因为端口由BES实例决定不是应用自己决定。配置了也不报错只是SpringBoot会忽略它。第二种进阶如果多个应用部署到同一个BES不同应用想要不同Profile可以用spring.application.json环境变量或者JNDI自定义配置。这块后续在“多应用隔离”部分再展开单应用部署先不折腾。3.4 数据源与JNDI绑定另一个大坑在jar方式下数据源通常用spring.datasource.url、spring.datasource.username直接写在配置里或者在Nacos配置中心统一管理。但企业级应用部署到BES后通常走JNDI数据源方式——这是Java EE容器的标准玩法。原因很简单运维可以通过控制台动态调整数据库连接池不用重新打包重新部署数据库密码可以存放于BES的配置领域避免明文写在应用配置里。BES控制台配置JNDI数据源进入控制台 - 资源 - JDBC - 连接池 - 新建。数据源类型选择MySQL我用的是MySQL 8.x驱动类名com.mysql.cj.jdbc.Driver。配置JDBC URL、用户名、密码。设置JNDI名称比如jdbc/mydb。点击“测试连接”确认连通性。应用侧改造可以二选一方案ASpring Boot标准方式# 使用JNDI数据源 spring.datasource.jndi-namejdbc/mydb这是最简洁的写法SpringBoot的DataSourceAutoConfiguration会自动通过JndiDataSourceLookup去容器中查找数据源。方案B自定义DataSource配置类Configuration public class DataSourceConfig { Bean Primary public DataSource dataSource() throws NamingException { JndiDataSourceLookup lookup new JndiDataSourceLookup(); return lookup.getDataSource(jdbc/mydb); } }如果你用了MyBatis-Plus记得确保DataSource优先被注入到SqlSessionFactory中。方案A就走SpringBoot默认的自动装配路径基本不用改代码方案B适合那些需要自定义连接池参数如最大连接数、超时时间的场景。我在实操中发现一个细节BES的JNDI查找名称必须和控制台上定义的名称完全一致开头是java:comp/env/jdbc/mydb还是直接jdbc/mydb取决于BES版本和配置方式。9.5.5版本在控制台创建连接池时填入的JNDI名称直接写jdbc/mydb应用侧写jdbc/mydb就能找到但如果通过domain.xml手写资源可能需要加java:comp/env/前缀。最稳妥的办法先用控制台创建不要直接改XML。4. 完整构建与BES部署实操4.1 Maven构建war包依赖都改好后执行打包mvn clean package -Dmaven.test.skiptrue -Pprod构建成功后war包位于target/目录名称形如demo-1.0.0.war。注意SpringBoot的SpringBootServletInitializer机制下war包在本地./target目录中会包含WEB-INF/lib-provided目录存放provided依赖的jar这些jar在部署到BES时不会使用但保留在包内没问题BES会自动忽略。4.2 控制台部署war包部署过程很简单登录BES管理控制台http://IP:4848。左侧菜单选择“应用” - “Web应用” - “部署”。上传war包应用名称填demo建议和war包名一致这样上下文路径好控制。上下文根路径填/demo对应访问地址是http://IP:8080/demo。部署完成后点击“启动”。如果一切正常BES会解压war包创建应用实例通过SpringBootServletInitializer完成Spring容器的初始化。查看日志确认效果tail -f /opt/bes/domains/mydomain/logs/server.log看到以下日志说明启动成功Root WebApplicationContext: initialization completed in 8122 ms BES Web Application Startup Time: 8000 ms然后你就可以访问http://IP:8080/demo/验证接口了。4.3 单机多实例部署模式如果服务器资源充足想在一台机器上跑多个BES实例做应用隔离或本地灰度可以创建多个域或者在同一域下创建多个独立实例。命令方式./asadmin create-node --nodeport 28181 mynode ./asadmin create-instance --node mynode --port 8081 instance1 ./asadmin create-instance --node mynode --port 8082 instance2创建后分别启动./asadmin start-instance instance1 ./asadmin start-instance instance2实际项目中多实例的典型场景是“nacos注册中心同一个服务注册两个实例实现本地双节点负载”。BES自身也有集群和负载均衡能力但如果你的服务中间接入了Nacos/FeignBES的集群LB反而可以不用让Nacos层面的负载来分摊流量。4.4 访问日志与并发参数调优BES部署后默认并发和线程池参数比较保守。如果你的SpringBoot应用压测发现吞吐上不去先看BES的HTTP线程池配置控制台 - 服务器配置 - HTTP服务 - 线程池把最大线程数从默认值调高比如调到400然后配置连接超时和请求超时。这些参数对应domain.xml里类似这样thread-pool max-thread-pool-size400 min-thread-pool-size20 idle-thread-timeout-seconds1200/访问日志默认是关闭的排障时需要开启。在JVM选项里加系统属性-Dcom.bes.webserver.log.access.enabledtrue -Dcom.bes.webserver.log.access.dir/opt/bes/logs开启后每次HTTP请求会记录IP、时间、URL、状态码和耗时。排查某接口慢或客户端异常断开时这份日志非常管用。5. 实战中的常见问题与排查实录5.1 类加载冲突Jackson版本被容器覆盖问题现象应用启动报错提示jackson-databind的某个类方法找不到或者反序列化时直接抛出InvalidDefinitionException。定位后发现BES自身lib目录带了一份较旧的Jackson版本由于BES的类加载策略是“父类优先”应用lib中的新版本Jackson被旧版本覆盖。解决方案修改应用的WEB-INF/classes下的META-INF/MANIFEST.MF通过Class-Path显式指定优先加载应用jar。这个在BES里对应“应用部署配置 - 类加载策略”可以设置为“子类优先”即child-first。或者在domain.xml中给特定应用添加如下配置application namedemo class-loader-policychild-first/如果不想动配置还有一个土办法把目标jar如jackson-databind新版本复制到/opt/bes/domains/mydomain/lib/目录覆盖BES自带的旧版本。但这种方法会影响域内所有应用改动面较大如果不是确认全局兼容不建议直接覆盖。5.2 启动出现“No active profile set”或配置未加载问题现象应用日志打出No active profile set, falling back to 1 default profile数据库连接失败判断是官方配置没生效。原因分析war部署在BES时SpringBoot的application.properties路径不受--spring.config.location控制同时nacos地址等参数需要通过环境变量或JNDI传入。排查时先确认spring.profiles.active是否正确注入再看nacos.config.server-addr是否可通过本地环境变量读到。推荐做法# application.properties保持默认配置 spring.profiles.active${SPRING_PROFILES_ACTIVE:prod} spring.cloud.nacos.config.server-addr${NACOS_ADDR:127.0.0.1:8848}这样BES的JVM系统属性或操作系统环境变量里配置SPRING_PROFILES_ACTIVE和NACOS_ADDR就能自动覆盖。如果环境变量也拿不到就把NACOS_ADDR硬编码后重新打包等后续有条件再接配置中心。5.3 上传文件临时目录不存在问题现象通过接口上传文件比如Excel导入第一次报错Failed to create temp directory或者java.io.IOException: No space left on device但磁盘空间明明够用。原因分析SpringBoot默认上传下载的临时目录取自javax.servlet.context.tempdirBES为每个应用分配的临时目录在domains/mydomain/applications/demo/tmp如果该目录不存在或权限不对就会报这个错。解决办法mkdir -p /opt/bes/domains/mydomain/applications/demo/tmp chown -R bes:bes /opt/bes/domains/mydomain/applications/然后在应用配置里强制指定临时目录spring.servlet.multipart.temp-dir/opt/bes/domains/mydomain/applications/demo/tmp5.4 日志文件找不到了jar方式下logback-spring.xml里的日志路径通常写成相对路径./logs在war方式下相对路径的“当前目录”是BES的bin目录或特定工作目录结果日志文件被创建到奇怪的地方甚至因为权限不足直接抛异常无法输出日志。经验做法把logback-spring.xml中的日志路径改成绝对路径或者通过LOG_HOME系统属性指定property nameLOG_HOME value${LOG_HOME:-/opt/bes/domains/mydomain/logs/demo}/ appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender file${LOG_HOME}/app.log/file !-- 其余配置省略 -- /appender然后启动BES前设置系统属性或环境变量export LOG_HOME/opt/bes/domains/mydomain/logs/demo5.5 集群部署时Session共享问题如果有多个BES实例组成集群默认情况下Session不会跨节点共享。SpringBoot应用如果用到HttpSession登录验证码、权限暂存等需要把Session共享方案迁移到容器级别。BES自带集群Session复制功能但配置比较繁琐我们项目里选择在应用层解决接入Redis统一存储Session。依赖如下dependency groupIdorg.springframework.session/groupId artifactIdspring-session-data-redis/artifactId /dependency配置spring.session.store-typeredis spring.redis.host127.0.0.1 spring.redis.port6379这样不需要动BES集群配置Session问题就直接绕开了。6. 依赖配置与避坑清单速查下面把本次改造的核心内容浓缩为一张速查表方便你迁移时对照检查检查项jar包内嵌Tomcat方式war包部署BES方式备注打包方式packagingjar/packagingpackagingwar/packaging必须改web-starterspring-boot-starter-webspring-boot-starter-web排除tomcat排除内嵌Tomcatservlet-api依赖无需添加javax.servlet-apiscopeprovided不添加则编译报错启动类普通main方法继承SpringBootServletInitializer必须重写configureserver.port生效不生效端口由BES管理配置了也不会启动监听server.servlet.context-path生效建议在BES控制台配置上下文根配置可能被覆盖数据源spring.datasource.url直接配置JNDI数据源spring.datasource.jndi-name也可以从Nacos读取日志路径相对路径./logs必须使用绝对路径否则日志散落各处JVM参数java -jar -XmxBES JVM设置中配置与控制台保持一致上传临时目录Servlet容器自动管理需显式指定否则可能创建失败Profile切换命令行--spring.profiles.active环境变量或JVM系统属性需保证可注入这份表其实不限于BES也适用于其他国产Java EE中间件比如东方通TongWeb、金蝶天燕Apusic、中创InforSuite等它们的部署方式和常用坑都高度相似换成对应控制台操作就行。7. 我踩过的最深的坑最后分享一个让我排查了两天的典型问题给你打个预防针。我们是先从jar方式在本地mvn spring-boot:run调试功能全通了再改成war方式部署到BES。部署后应用界面能开但所有接口返回的JSON中中文字段都变成了???或乱码。一开始怀疑是数据库连接字符集问题检查characterEncodingutf8也加了没用又怀疑是HttpMessageConverter配置问题排查了一大圈。最后用curl直接观察BES的响应头发现Content-Type里带的是charsetISO-8859-1而不是预期的UTF-8。原来是BES的HTTP响应编码默认走ISO-8859-1SpringBoot在外部容器下拿不到请求默认编码所以返回体的编码被覆盖了。解决办法在BES控制台的“服务器配置 - HTTP监听器 - 编码”里把默认编码改成UTF-8或者在应用的Filter里强制设置response.setCharacterEncoding(UTF-8)。后来为了避免每个接口都手动处理我加了一个OncePerRequestFilter统一处理Component public class CharacterEncodingFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { request.setCharacterEncoding(UTF-8); response.setCharacterEncoding(UTF-8); response.setContentType(application/json;charsetUTF-8); filterChain.doFilter(request, response); } }部署后再测中文全部正常。这个坑的教训是中间件迁移过程中“看似正常”比“直接报错”更可怕。报错时日志会给出线索而编码这种隐性问题很容易被误判为业务代码问题。建议你在做信创改造验证时专门抽出测试用例覆盖中文字符、特殊符号、上传下载文件流、Session传递这几个高敏感场景每一个都要盯紧。迁移完成后记得把BES日志接入你的ELK或日志平台后续线上排查完全依赖它。祝你的信创改造之路一切顺利少踩一些我踩过的坑。提示以上配置基于宝兰德BES 9.5.5版本如果你使用的是其他版本部分控制台路径和参数名可能会有差异以官方文档为准。如果迁移过程中遇到其他问题欢迎一起交流学习。