9.6 KiB
TongWeb接入全流程通用指南
1. 适用场景
本文档用于指导 Spring Boot 2.x 项目接入东方通 TongWeb 内嵌容器，适用于以下场景：
- 现有项目默认使用 Spring Boot 内嵌 Tomcat。
- 需要切换为 TongWeb 自启动运行。
- 需要将 TongWeb license 文件随应用一起打包。
- 需要沉淀一套可以迁移到其他项目的标准接入步骤。
本文以本仓库的接入经验为基础，输出的是一套可复用流程，而不是只面向当前项目的零散记录。
2. 前置准备
接入前需要准备以下信息：
2.1 TongWeb Starter 依赖
当前使用的依赖坐标：
<dependency>
<groupId>com.tongweb.springboot</groupId>
<artifactId>tongweb-spring-boot-starter-2.x</artifactId>
<version>7.0.E.7</version>
</dependency>
2.2 Maven 仓库
如果项目默认只配了 Maven Central 或阿里云公共仓库，TongWeb 依赖通常无法直接解析，需要补充 TongWeb 仓库：
<repositories>
<repository>
<id>tongweb-releases</id>
<name>TongWeb Maven Releases</name>
<url>https://mvn.elitescloud.com/nexus/repository/maven-releases/</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
2.3 License 文件
需要一份可用的 TongWeb license 文件，例如：
Tongweb_license.dat
建议确认以下信息：
- 许可证版本是否与目标 TongWeb 版本一致。
- 许可证是否仍在有效期内。
- 许可证是否允许当前部署规模使用。
3. 接入总流程
TongWeb 接入建议按下面顺序执行：
- 确认项目里是谁引入了默认 Tomcat。
- 排除默认 Tomcat 依赖。
- 引入 TongWeb Starter。
- 把 license 文件放入
resources。 - 在
application.yml中增加 TongWeb 配置。 - 执行构建、依赖树、产物检查和启动验证。
- 根据日志处理依赖解析、license 不匹配、配置冲突等问题。
4. 依赖改造
4.1 找出默认 Tomcat 来源
很多项目不是在启动模块直接声明 spring-boot-starter-web，而是通过公共框架模块间接引入。因此第一步必须先查清默认 Tomcat 的入口来源。
例如：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
如果它出现在公共框架模块里，实际排除 Tomcat 时通常要在应用启动模块对该依赖做 exclusion。
4.2 排除默认 Tomcat
推荐在最终启动模块中对上游框架模块做排除，避免默认内嵌 Tomcat 和 TongWeb 同时进入运行时：
<dependency>
<groupId>com.xxx</groupId>
<artifactId>project-framework</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
</exclusions>
</dependency>
4.3 引入 TongWeb Starter
在最终启动模块增加 TongWeb Starter：
<dependency>
<groupId>com.tongweb.springboot</groupId>
<artifactId>tongweb-spring-boot-starter-2.x</artifactId>
<version>7.0.E.7</version>
</dependency>
4.4 资源打包
如果项目资源打包规则比较严格，建议显式保留 resources 配置，避免 .dat 文件没有进入产物：
<build>
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>false</filtering>
<includes>
<include>**/*</include>
</includes>
</resource>
</resources>
</build>
5. License 文件接入
5.1 放置路径
将 TongWeb license 文件放到：
src/main/resources/Tongweb_license.dat
建议直接随项目源码管理，便于构建产物统一携带。
5.2 命名原则
配置中的文件名必须与实际资源名完全一致。例如资源名是：
Tongweb_license.dat
那么配置里也必须写：
classpath:Tongweb_license.dat
不要一个地方写 license.dat，另一个地方写 Tongweb_license.dat，否则运行时会直接出现 license 读取失败。
6. 配置接入
建议把 TongWeb 配置统一放到 application.yml 中，便于其他项目直接复用，而不是散落到多个环境文件。
推荐配置如下：
server:
tongweb:
license:
path: classpath:Tongweb_license.dat
如果项目本身已经有 server 节点，直接挂到其下即可，不需要额外拆配置文件。
7. 构建与验证
接入完成后，至少执行下面几类验证。
7.1 依赖解析验证
mvn -pl ruoyi-admin -am package -DskipTests
预期：
- TongWeb 依赖能够正常下载。
- 项目可以正常构建。
7.2 产物检查
jar tf ruoyi-admin/target/ruoyi-admin.jar | rg 'Tongweb_license.dat|tongweb'
预期：
Tongweb_license.dat已进入BOOT-INF/classes/- TongWeb 相关 jar 已进入
BOOT-INF/lib/
7.3 依赖树检查
mvn -pl ruoyi-admin dependency:tree '-Dincludes=com.tongweb.springboot:*,com.tongweb:*,org.apache.tomcat.embed:*'
预期：
- 能看到 TongWeb Starter 及相关依赖。
- 默认
spring-boot-starter-tomcat不应再作为主依赖链出现。
注意：
- 某些项目中仍可能看到
tomcat-embed-el，它可能来自spring-boot-starter-validation等其他依赖。 - 是否需要继续清理，最终以实际启动结果为准。
7.4 启动验证
建议从应用模块目录直接执行：
mvn -f ruoyi-admin/pom.xml spring-boot:run -Dspring-boot.run.profiles=dev
这样可以避免从聚合工程根目录调用时，Maven 把插件错误落到父 pom 上。
验证重点：
- 应用是否成功启动。
- TongWeb License SDK 日志是否出现。
- 端口是否成功监听。
- 是否出现 TongWeb 与 Tomcat 的容器冲突报错。
7.5 启动后进程清理
如果是本地验证，结束测试后需要手动关闭 Java 进程，避免残留服务继续占用端口。
例如：
lsof -nP -iTCP:63310 -sTCP:LISTEN
kill <PID>
8. 推荐自动化测试
如果项目有测试体系，建议至少补两类测试。
8.1 资源存在性测试
验证 license 文件能否从 classpath 读取：
assertNotNull(
TongWebLicenseResourceTest.class.getClassLoader().getResource("Tongweb_license.dat"));
8.2 配置存在性测试
验证 application.yml 中是否存在：
server.tongweb.license.path
这样可以避免后续重构时把 TongWeb 配置误删。
9. 常见问题
9.1 TongWeb 依赖下载失败
典型现象：
- Maven 提示找不到
tongweb-spring-boot-starter-2.x
原因：
- 项目只配置了公共仓库，没有配置 TongWeb 专用仓库。
处理方式：
- 补充 TongWeb Maven 仓库。
9.2 spring-boot:run 找不到插件
典型现象：
No plugin found for prefix 'spring-boot'
处理方式：
- 改为从子模块目录执行，或者用
-f ruoyi-admin/pom.xml指向具体模块。
9.3 spring-boot:run 落到父工程
典型现象：
Unable to find a suitable main class
原因：
- Spring Boot 插件被执行在聚合父
pom上。
处理方式：
- 使用：
mvn -f ruoyi-admin/pom.xml spring-boot:run
9.4 License 不匹配或已过期
典型现象：
- 版本号不匹配告警
- 有效期已过期
这类问题说明 TongWeb 配置链路通常已经生效，真正的问题是授权文件本身不适配当前环境。
处理方式：
- 更换与目标 TongWeb 版本一致、且仍在有效期内的 license 文件。
9.5 项目里仍保留 server.tomcat.*
如果项目原先已有：
server:
tomcat:
...
建议先不要大规模重构。
处理策略：
- 若 TongWeb 启动时仅忽略这些配置，则先保留。
- 只有当日志明确指出这些配置导致启动失败时，再做最小必要调整。
10. 可复制模板
10.1 pom.xml 最小改造模板
<dependency>
<groupId>com.xxx</groupId>
<artifactId>project-framework</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>com.tongweb.springboot</groupId>
<artifactId>tongweb-spring-boot-starter-2.x</artifactId>
<version>7.0.E.7</version>
</dependency>
10.2 application.yml 模板
server:
tongweb:
license:
path: classpath:Tongweb_license.dat
10.3 目录模板
src/main/resources/Tongweb_license.dat
11. 最终检查清单
在其他项目复用时，可以按下面清单逐项确认：
- 是否已确认默认 Tomcat 的引入来源
- 是否已排除
spring-boot-starter-tomcat - 是否已引入 TongWeb Starter
- 是否已配置 TongWeb Maven 仓库
- 是否已将
Tongweb_license.dat放入src/main/resources - 是否已在
application.yml中加入server.tongweb.license.path - 是否已通过构建验证
- 是否已确认产物中包含 TongWeb 相关 jar 与 license 文件
- 是否已完成启动验证
- 是否已确认 license 版本、有效期和授权范围可用
12. 结论
TongWeb 接入本质上只包含四件事：
- 替换默认内嵌容器依赖
- 接入 TongWeb 仓库与 Starter
- 让 license 文件进入 classpath
- 用启动日志验证 TongWeb 是否真正接管运行
只要按这个顺序执行，TongWeb 接入通常可以用最短路径完成，且这套流程可以直接迁移到其他 Spring Boot 项目中。