1. 项目概述从Tomcat到TongWeb的国产化迁移最近在做一个信创适配的项目客户要求将原有的SpringBootVue前后端分离应用从我们熟悉的Tomcat环境迁移到国产的东方通TongWeb应用服务器上。说实话一开始心里是有点打鼓的毕竟TongWeb虽然名气不小但网上的实战资料尤其是结合Vue这种纯前端项目的部署教程确实比较零散踩坑的分享也不多。经过几轮测试环境的折腾和生产环境的验证总算把整个流程跑通了而且运行得挺稳定。今天就把从环境准备、项目改造、部署配置到问题排查的一整套经验梳理出来希望能给正在做类似国产化迁移的兄弟一个清晰的参考避开我走过的那些弯路。这个部署方案的核心是将Vue项目通过打包工具如Webpack或Vite生成纯粹的静态资源HTML、CSS、JS文件然后将其作为静态内容部署到TongWeb中。这听起来和部署到Nginx或Tomcat没什么不同但关键在于TongWeb作为一款遵循Java EE规范的应用服务器其静态资源处理、路径映射、以及作为后端SpringBoot应用容器的角色与Tomcat存在一些细微但关键的差异。我们的目标就是让Vue打包后的dist目录在TongWeb里能被正确访问并且能无缝对接后端的API接口。2. TongWeb环境准备与基础配置2.1 TongWeb的获取与安装首先你得有TongWeb。通常需要从东方通官方渠道获取安装包这可能是一个压缩包如.zip或安装程序。这里假设我们以常见的独立服务器部署为例。安装步骤简述解压或安装将安装包解压到你指定的目录例如/opt/tongweb。这个目录将成为$TONGWEB_HOME。目录结构初窥进入安装目录你会看到类似bin启停脚本、conf配置文件、logs日志、webapps应用部署目录等文件夹。对前端部署来说最需要关注的是webapps和conf。启动与验证进入bin目录执行启动脚本Linux下通常是./startserver.shWindows下是startserver.bat。启动成功后默认访问http://localhost:9060应该能看到TongWeb的管理控制台登录页面。默认的管理员账号密码通常在安装文档中注明。注意生产环境务必修改默认密码并仔细配置安全策略。TongWeb的管理端口默认为9060和应用端口默认为8060可以在conf/server.xml中配置避免与现有服务冲突。2.2 关键配置调整server.xml与上下文路径要让TongWeb更好地服务我们的静态Vue应用需要对conf/server.xml文件进行一些调整。这个文件类似于Tomcat的server.xml定义了连接器、引擎、主机等核心组件。一个需要重点关注的点是Context配置在Tomcat中我们经常在server.xml里或独立的context.xml中配置Context来定义应用。在TongWeb中虽然也支持但更推荐将静态资源直接放入webapps目录下的独立文件夹或者通过配置虚拟目录来实现。对于Vue的dist包最简单直接的方式就是将其整体复制到webapps目录下并重命名为你的应用名例如webapps/my-vue-app。这样应用就可以通过http://host:port/my-vue-app来访问。如果你想配置一个根路径上下文即直接通过http://host:port访问可以将dist目录下的所有文件复制到webapps/ROOT目录下清空原有ROOT内容。或者在server.xml的Host标签内添加一个指向dist目录的ContextContext path docBase/absolute/path/to/your/vue-dist reloadablefalse /这里path表示根路径docBase指向你的dist目录的绝对路径。reloadablefalse对于静态资源可以提高性能。连接器配置检查Connector标签确保HTTP端口默认为8060是你期望的。你也可以在这里配置连接超时、最大线程数等参数以优化性能。3. Vue项目的适配性改造Vue项目本身是静态的但它的配置需要适应部署环境。最关键的两点是公共路径publicPath和路由模式。3.1 配置公共路径 (publicPath)公共路径决定了你的静态资源JS、CSS、图片等在部署后的基础URL。如果你计划将应用部署在非根路径下例如/my-vue-app则必须在Vue项目的构建配置中设置它。对于 Vue CLI 创建的项目在项目根目录下的vue.config.js文件中进行配置module.exports { // 假设部署到 TongWeb 的 /my-vue-app 目录下 publicPath: process.env.NODE_ENV production ? /my-vue-app/ : /, // ... 其他配置 }对于 Vite 创建的项目在vite.config.js文件中配置export default defineConfig({ // 假设部署到 TongWeb 的 /my-vue-app 目录下 base: /my-vue-app/, // ... 其他配置 })这个配置至关重要。如果设置错误浏览器在加载页面时会去错误的路径寻找JS和CSS文件导致页面白屏或样式错乱。3.2 路由模式选择与适配Vue Router有两种模式hash模式和history模式。Hash模式默认URL中带有一个#例如http://example.com/#/home。它的优点是部署简单不需要服务器端做任何特殊配置因为#之后的部分不会被发送到服务器。在TongWeb上直接使用没有任何问题。History模式URL更简洁如http://example.com/home。但这需要服务器端的配合当用户直接访问一个深链接如/home或刷新页面时服务器需要能够识别这些路由并返回同一个index.html文件然后由前端路由接管。如果你想使用History模式并在TongWeb上部署需要额外配置由于我们的Vue应用是纯静态文件TongWeb需要将所有未知路径的请求都重定向到index.html。这通常无法直接在TongWeb的server.xml中像Nginx的try_files那样简单配置。最稳妥的方案是坚持使用Hash模式这是最省事、兼容性最好的方案特别在初期迁移阶段推荐使用。使用History模式并配置错误页面在TongWeb中可以为应用配置一个404错误页面将其指向index.html。但这并非标准做法且可能影响真正的404资源请求。具体可在应用目录下如webapps/my-vue-app/WEB-INF/若无则创建创建web.xml进行配置但相对复杂且不完美。前端妥协方案如果非要用History模式一个常见的做法是在打包前将路由模式改为Hash模式。或者接受一个限制要求用户永远只能从根路径进入应用。实操心得在信创环境迁移初期为了求稳强烈建议先使用Hash模式。这能避免大量因路径问题导致的白屏故障等整体环境稳定后再考虑History模式的优化方案。3.3 构建与打包配置完成后运行构建命令生成dist目录。# Vue CLI npm run build # 或 yarn build # Vite npm run build # 或 yarn build构建完成后检查dist目录下的index.html确认其中引用的JS、CSS资源路径是否正确包含了配置的公共路径如/my-vue-app/js/app.xxxx.js。4. 部署SpringBoot后端与前后端对接在前后端分离项目中Vue前端需要调用SpringBoot后端提供的API。在TongWeb环境中我们需要将SpringBoot应用也部署进去。4.1 SpringBoot应用适配TongWebSpringBoot默认使用内嵌的Tomcat。要部署到TongWeb需要将打包方式从可执行的Jar包改为War包并排除内嵌的Tomcat。1. 修改pom.xmlMaven项目packagingwar/packaging !-- 将jar改为war -- dependencies !-- 排除内嵌的Tomcat -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId scopeprovided/scope !-- 关键改为provided -- /dependency !-- 其他依赖保持不变 -- /dependenciesscopeprovided/scope意味着这个依赖在打包时会被包含但在运行时由TongWeb服务器提供。2. 修改主应用类继承SpringBootServletInitializer并重写configure方法这是War包部署到Servlet容器的标准方式。SpringBootApplication public class YourApplication extends SpringBootServletInitializer { Override protected SpringApplicationBuilder configure(SpringApplicationBuilder application) { return application.sources(YourApplication.class); } public static void main(String[] args) { SpringApplication.run(YourApplication.class, args); } }3. 重新打包执行mvn clean package会在target目录下生成一个your-app.war文件。4.2 部署War包到TongWeb将生成的your-app.war文件复制到TongWeb的webapps目录下。启动或重启TongWeb它会自动解压war包并部署应用。假设你的war包名为api.war那么后端API的根路径通常是http://host:port/api。4.3 前端API请求地址配置现在前端需要知道后端API的地址。在开发环境我们可能用vue.config.js的devServer.proxy代理。在生产环境需要根据实际部署情况配置。最佳实践是使用环境变量在Vue项目中创建不同的环境配置文件如.env.production。# .env.production VUE_APP_API_BASE_URL /api注意这里使用了相对路径/api意味着前端会向与自己同域名、同端口的/api路径发起请求。这要求前端和后端部署在同一个TongWeb实例下且端口相同。在前端请求库如axios的配置中使用这个环境变量import axios from axios; const service axios.create({ baseURL: process.env.VUE_APP_API_BASE_URL, timeout: 10000 });部署结构示例TongWeb (http://localhost:8060)webapps/ROOT/(或webapps/my-vue-app/) - Vue的dist文件webapps/api/- SpringBoot的api.war解压后目录前端页面访问http://localhost:8060前端请求APIhttp://localhost:8060/api/user/login(由baseURL: /api拼接而成)这种同源部署方式避免了跨域CORS问题是最简单的部署架构。5. 完整部署流程与操作实录让我们串联起所有步骤进行一次完整的部署操作。步骤一准备TongWeb环境安装并启动TongWeb确保http://localhost:9060管理台和http://localhost:8060应用端口可访问。可选根据需求修改conf/server.xml中的端口号。步骤二改造并构建Vue前端进入Vue项目确认vue.config.js中的publicPath设置为目标上下文路径如/或/my-app。确认路由模式初期建议使用hash模式。运行npm run build生成dist目录。步骤三改造并构建SpringBoot后端修改pom.xml将打包方式改为war并将spring-boot-starter-tomcat作用域设为provided。修改主类继承SpringBootServletInitializer。运行mvn clean package生成api.war。步骤四部署到TongWeb清空tongweb/webapps/ROOT目录如果希望部署在根路径。将Vue项目dist目录下的所有文件复制到tongweb/webapps/ROOT下。将api.war文件复制到tongweb/webapps/目录下。启动或重启TongWeb服务器。进入bin目录执行./startserver.shLinux或startserver.batWindows。步骤五验证访问http://localhost:8060应能看到Vue应用界面。在Vue应用中触发一个API调用如登录打开浏览器开发者工具的“网络”选项卡查看请求是否正确发送到http://localhost:8060/api/xxx并且响应成功。检查TongWeb的logs目录下的日志文件查看有无错误信息。6. 常见问题、性能调优与深度排查部署过程很少一帆风顺下面记录了一些典型问题及解决方法。6.1 静态资源404白屏问题这是最常见的问题浏览器控制台会报错找不到app.xxxx.js或chunk.xxxx.js。排查思路检查publicPath这是首要怀疑对象。确认Vue项目中配置的publicPath与部署的上下文路径完全一致。如果应用部署在ROOT根路径publicPath应为/。如果部署在webapps/myapppublicPath应为/myapp/注意结尾的斜杠。检查文件是否就位直接通过浏览器访问一个静态资源URL如http://localhost:8060/myapp/js/app.xxxx.js看是否能下载。如果不能去webapps/myapp/js/目录下确认文件是否存在。检查TongWeb静态资源服务TongWeb默认是支持静态资源服务的。可以检查conf/web.xml中关于DefaultServlet的配置是否被错误修改。6.2 路由刷新404History模式特有当使用History模式时直接访问子路由或刷新页面会得到404。解决方案如前所述最稳妥的是换用Hash模式。如果必须用History模式一个变通方案是在Vue应用的入口index.html同级创建一个简单的WEB-INF/web.xml需要放在webapps/ROOT/WEB-INF/下来配置错误页面但这并非标准Web静态项目的做法且可能影响其他静态资源。更专业的做法是考虑在前端和后端之间引入一个Nginx作为反向代理由Nginx来处理History模式的重定向但这增加了架构复杂度。6.3 后端API访问404或跨域问题现象前端页面能打开但所有API请求失败。排查确认API部署成功直接访问http://localhost:8060/api/或你的应用路径看是否有响应可能是一个Whitelabel Error Page这正说明SpringBoot应用已启动。检查请求地址在前端浏览器控制台的“网络”标签中查看请求的完整URL是否正确拼接。确保baseURL配置正确。跨域问题如果前端和后端部署在不同端口或域名下浏览器会因同源策略而阻止请求。此时需要在SpringBoot后端配置CORS。Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) // 或指定前端地址如 http://localhost:8060 .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowCredentials(true) .maxAge(3600); } }最佳实践是保持同源部署即前端和后端在同一个TongWeb实例的同一个端口下通过上下文路径区分这样可以彻底避免CORS。6.4 TongWeb容器运行变卡或内存溢出有网络热词提到“tongweb容器运行一天就开始变卡”这通常与资源管理有关。排查与调优建议检查JVM参数TongWeb本身运行在JVM上。编辑bin/startserver.sh或startserver.bat中的JAVA_OPTS调整内存参数。例如JAVA_OPTS-server -Xms2048m -Xmx4096m -XX:MetaspaceSize256m -XX:MaxMetaspaceSize512m-Xms和-Xmx设置堆内存初始和最大值根据服务器物理内存和应用大小调整。检查应用内存泄漏使用JDK自带的jvisualvm或jconsole工具连接到TongWeb的JVM进程监控堆内存和老年代的使用情况看是否有持续增长而不被回收的现象。问题可能出在你部署的SpringBoot应用代码中如静态集合不当引用、未关闭的连接等。检查线程池在TongWeb管理控制台或查看conf/server.xml中Executor和Connector的配置看最大线程数maxThreads是否设置过小导致请求堆积。检查日志级别过细的日志如DEBUG级别会大量消耗磁盘I/O和CPU。确保生产环境日志级别为INFO或WARN。检查部署的应用某些应用可能存在内存泄漏或资源未释放的问题。可以尝试逐个卸载应用观察系统资源是否恢复以定位问题应用。6.5 “Unable to start embedded TongWeb”错误这个错误通常出现在SpringBoot应用尝试以内嵌方式启动TongWeb时但在我们的场景中我们是将SpringBoot作为War包部署到独立的TongWeb服务器因此不应该出现这个错误。如果出现请检查是否错误地将spring-boot-starter-tomcat依赖的scope设置为了compile默认而非provided导致打包时包含了内嵌容器与外部TongWeb冲突。主类是否正确地继承了SpringBootServletInitializer。6.6 性能调优小贴士静态资源缓存为了加快页面加载速度可以为Vue的静态资源JS、CSS、图片配置HTTP缓存。这需要在TongWeb中配置静态资源的MIME类型和过期时间。可以通过修改conf/web.xml中相关mime-mapping和配置DefaultServlet的缓存参数实现但操作较为复杂。一个更简单有效的方式是在TongWeb前放置一个Nginx由Nginx来处理静态资源缓存和压缩。GZIP压缩启用GZIP压缩可以显著减少传输体积。TongWeb支持在conf/server.xml的Connector中配置压缩Connector port8060 protocolHTTP/1.1 compressionon compressionMinSize1024 compressableMimeTypetext/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json /会话超时在conf/web.xml中可以调整全局的会话超时时间session-configsession-timeout避免不必要的会话占用内存。部署国产化中间件是一个需要耐心和细致的过程从熟悉的开源环境切换到国产商业产品必然会遇到一些适配性问题。关键是要理解其作为Java EE应用服务器的本质其操作逻辑与Tomcat大同小异核心在于配置文件的调整和部署方式的匹配。希望这份从实战中总结的指南能帮助你更顺畅地完成Vue项目在TongWeb上的部署之旅。如果在实际操作中遇到新的问题多查看TongWeb的logs目录下的日志文件那里通常藏着最直接的线索。