digitalhainan-tongweb 信创适配 ​

本文档用于指导在目标项目中完成 digitalhainan-tongweb 模块集成。

执行顺序：

1. 先完成「12.1.2 快速集成」的全部步骤（必须）
2. 根据业务需求，查阅「功能集成决策索引」选择对应路径，逐项实现
3. 遇到配置问题时参考「12.1.3 配置属性参考」
4. 出现异常时查阅「12.1.6 常见问题」

代码约定： 本模块为纯配置模块，无 Java 源码。所有配置示例使用 YAML 格式。

12.1.1 模块简介 ​

digitalhainan-tongweb-spring-boot-starter 是数字海南框架提供的信创 Web 容器替代方案，用于将 Spring Boot 项目默认的 Tomcat 容器替换为东方通 TongWeb V8.0 嵌入式版，满足国产化/信创合规要求。

• 零代码改动，通过 Maven Profile 一键将 Tomcat 替换为 TongWeb
• 支持本地文件认证（file）和远程 License Server 认证（remote）两种授权方式
• 支持单向/双向 SSL（mTLS），可限制国密套件满足等保/密评合规
• 基于 Spring Boot Actuator 提供运行时监控能力，配套 Grafana 模板
• 提供 Spring Boot WebSocket 规范的 TongWeb 适配

Maven 坐标：

<dependency>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>digitalhainan-tongweb-spring-boot-starter</artifactId>
</dependency>

前置依赖（项目 pom.xml 中必须已有）：

当前版本： 2.0.0-SNAPSHOT

技术规格：

12.1.2 快速集成 ​

目标： 完成以下 7 个步骤后，项目即运行在 TongWeb 容器上。

12.1.2.1 确认父 POM ​

操作： 业务项目需继承 digitalhainan-pom，其中定义了 xc-tongweb Profile 和 TongWeb 版本管理：

<parent>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>digitalhainan-pom</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</parent>

12.1.2.2 激活 xc-tongweb Profile ​

操作： 通过以下方式之一激活 xc-tongweb Profile，自动完成 Tomcat 排除 + TongWeb 引入。

方式一：IDE 中手动勾选（推荐日常开发）

以 IntelliJ IDEA 为例：

1. 打开右侧 Maven 面板
2. 展开 Profiles
3. 勾选 xc-tongweb

勾选后 IDE 会重新导入 Maven 依赖，Tomcat 会被排除、TongWeb 会被引入，此时可直接运行启动类进行开发调试。

方式二：命令行指定

mvn clean package -P xc-tongweb

Profile 工作原理（仅供参考，无需在业务项目中重复配置）：

xc-tongweb Profile 定义在 digitalhainan-pom/pom.xml 中，激活后自动执行：

1. 排除 Tomcat：从 spring-boot-starter-web 中排除 spring-boot-starter-tomcat
2. 引入 TongWeb：自动引入 digitalhainan-tongweb-spring-boot-starter

12.1.2.3 配置 License 授权 ​

操作： TongWeb 嵌入式版启动时需依赖授权文件校验，请联系东方通相关人员获取 license.dat 授权文件。

将 license.dat 文件放置到 src/main/resources/ 目录下，在 application.yml 中配置：

server:
  tongweb:
    license:
      # 指定认证方式为本地认证
      type: file
      # 指定 license.dat 文件路径（classpath 方式）
      path: classpath:license.dat

也支持使用本地磁盘绝对路径（适用于生产环境外部挂载）：path: /opt/license/license.dat

如需远程认证，参考「12.1.3 配置属性参考 - 3.1 License 配置」中的 remote 模式。

12.1.2.4 本地启动验证 ​

操作： 启动项目，检查以下条件：

IDE 直接运行：找到项目中带有 @SpringBootApplication 注解的启动类，右键 → Run 即可。

Maven 命令启动：

mvn spring-boot:run -P xc-tongweb

TongWeb 专属 Banner：

     _____               __        __   _
    |_   _|__  _ __   __ \ \      / /__| |__
      | |/ _ \| '_ \ / _` \ \ /\ / / _ \ '_ \
      | | (_) | | | | (_| |\ V  V /  __/ |_) |
      |_|\___/|_| |_|\__, | \_/\_/ \___|_.__/
                     |___/
Copyright  2026 Beijing TongTech All rights reserved.

如果启动失败，参考「12.1.6 常见问题 Q1」排查 License 问题。

12.1.2.5 验证依赖切换 ​

操作： 确认 Tomcat 已被排除、TongWeb 已引入：

# 确认无 Tomcat 依赖（预期无输出）
mvn dependency:tree -P xc-tongweb | findstr tomcat

# 确认 TongWeb 依赖已引入
mvn dependency:tree -P xc-tongweb | findstr tongweb

12.1.2.6 打包部署 ​

# 构建（激活 TongWeb Profile）
mvn clean package -P xc-tongweb

# 启动
java -jar target/your-app.jar

注意：-P xc-tongweb 仅在打包时生效。IDE 中直接 Run 启动类时，需通过 Step 2 的方式手动激活 Profile。

12.1.2.7 回退方案（如需） ​

TongWeb 集成采用零侵入设计，回退到 Tomcat 无需修改任何代码：

# 回退到 Tomcat（不激活 TongWeb Profile）
mvn clean package

# 启动（使用默认 Tomcat 容器）
java -jar target/your-app.jar

回退后行为与集成前完全一致，100% 向后兼容。

12.1.3 配置属性参考 ​

12.1.3.1 License 配置 server.tongweb.license.* ​

license.dat 放置位置说明：

License 文件字段说明：

更新 License：

• 本地认证：替换 license.dat 文件，重启应用即可生效
• 远程认证：在 License Server 管理控制台更新授权，各应用无需重启（License Server 会通知客户端刷新）

12.1.3.2 HTTP 配置 server.tongweb.* ​

12.1.3.3 HTTPS/SSL 配置 server.tongweb.* ​

12.1.3.4 容器行为配置 server.tongweb.* ​

12.1.3.5 远程 License 补充配置 server.tongweb.license-remote.* ​

12.1.3.6 完整 YAML 示例 ​

server:
  tongweb:
    # License 配置（本地认证）
    license:
      type: file
      path: classpath:license.dat

    # HTTP 配置
    server-name: myapp
    use-http: true
    http-port: 9080

    # HTTPS 配置（生产环境建议启用）
    use-https: true
    https-port: 8443
    keystore-path: classpath:keystore.p12
    keystore-password: your-password
    keystore-type: PKCS12

    # 容器行为
    use-manifest-jar-file: true
    session-timeout: 30
    uri-encoding: UTF-8

远程认证模式完整示例：

server:
  tongweb:
    license:
      type: remote
      license-ips: 127.0.0.1:8888
      license-public-key: your-public-key
      ssl-enabled: true
      ssl:
        key-store: classpath:client.p12
        key-store-password: 123456
        key-store-type: PKCS12
        trust-store: classpath:server.jks
        trust-store-password: 123456
        trust-store-type: JKS

12.1.4 核心功能使用 ​

功能集成决策索引 ​

AI 执行指引： 先完成「12.1.2 快速集成」，然后根据业务需求在下表中找到对应路径，跳转到对应小节实现。

12.1.4.1 远程 License 认证 ​

适用场景： 多实例集中管理 License 授权，避免每个实例单独放置 license.dat 文件。 前置条件： 已从 License Server 管理控制台获取加密公钥。

Step 1: 修改配置

server:
  tongweb:
    license:
      type: remote
      license-ips: 127.0.0.1:8888
      license-public-key: your-public-key

Step 2:（可选）启用 SSL 加密通信

server:
  tongweb:
    license:
      ssl-enabled: true
      ssl:
        key-store: classpath:client.p12
        key-store-password: 123456
        key-store-type: PKCS12
        trust-store: classpath:server.jks
        trust-store-password: 123456
        trust-store-type: JKS

验证： 启动日志中出现 授权证书已经成功通过校验。

12.1.4.2 HTTPS/SSL 配置 ​

适用场景： 生产环境需要加密传输，或需要满足等保/密评合规要求。 前置条件： 已准备 SSL 证书文件（PKCS12 或 JKS 格式）。

Step 1: 启用 HTTPS（单向 SSL）

server:
  tongweb:
    use-https: true
    https-port: 8443
    keystore-path: classpath:keystore.p12
    keystore-password: your-password
    keystore-type: PKCS12

Step 2:（可选）启用双向 SSL（mTLS）

server:
  tongweb:
    truststore-path: /opt/certs/trust.jks
    truststore-password: changeit
    truststore-type: JKS
    client-auth: need

Step 3:（可选）限制国密加密套件

server:
  tongweb:
    ciphers: TLS_AES_256_GCM_SHA384

验证： 通过 https://localhost:8443 访问应用，浏览器显示安全连接。

12.1.4.3 运行时监控 ​

适用场景： 需要实时监控 TongWeb 容器运行状态（连接池、请求处理、Session 等）。 前置条件： 项目已引入 Spring Boot Actuator。

Step 1: 引入监控依赖

在业务项目 pom.xml 中添加：

<dependency>
    <groupId>com.tongweb.springboot</groupId>
    <artifactId>tongweb-spring-boot-monitor-starter-2.x</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Step 2: 获取监控指标

启用后可通过 Actuator 端点获取以下指标：

• 连接器状态 — 活跃连接数、请求数等
• Servlet 引擎指标 — 请求处理时间、错误率等
• Session 统计 — 活跃 Session 数等

Step 3:（可选）导入 Grafana 监控模板

TongWeb 提供配套 Grafana 监控模板（位于安装包根目录）：

• 嵌入式_配置指标-xxxx.json：K8s 环境 Grafana 监控模板
• 嵌入式_配置指标单机版.json：单机版 Grafana 监控模板

验证： 访问 /actuator 端点确认 TongWeb 监控指标已注册。

12.1.4.4 WebSocket 支持 ​

适用场景： 需要在 TongWeb 容器上使用 Spring Boot WebSocket（@ServerEndpoint 注解）。 前置条件： 完成第二章快速集成。

Step 1: 引入 WebSocket 依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-websocket</artifactId>
</dependency>
<dependency>
    <groupId>com.tongweb.springboot</groupId>
    <artifactId>tongweb-spring-boot-websocket-2.x</artifactId>
</dependency>

Step 2: 使用 @ServerEndpoint 注解

引入依赖后，Spring Boot 的 @ServerEndpoint 注解可正常使用，无需额外配置。

验证： 创建 WebSocket 端点并通过客户端连接测试。

12.1.4.5 License Server 搭建（远程认证场景） ​

适用场景： 多实例集中管理 License 授权。

操作步骤：

1. 从东方通获取 License Server 安装包
2. 在授权管理机上部署并启动 License Server
3. 通过 License Server 管理控制台上传 license.dat 授权文件
4. 获取加密公钥（license-public-key）
5. 在各业务应用的 application.yml 中配置远程认证信息（参见 4.1 节）

12.1.5 版本变更记录 ​

v2.0.0（当前版本） ​

• [新增] 初始化 TongWeb Spring Boot Starter 项目配置
• [新增] 封装 TongWeb 嵌入式容器依赖（tongweb-spring-boot-starter-2.x）
• [新增] 可选监控模块（tongweb-spring-boot-monitor-starter-2.x）
• [新增] 可选 WebSocket 模块（tongweb-spring-boot-websocket-2.x）
• [新增] 通过 digitalhainan-pom xc-tongweb Profile 实现一键容器切换

12.1.6 常见问题 ​

Q1: License 校验失败 ​

排查步骤：

1. 确认 license.dat 文件存在且路径配置正确
2. 如使用 classpath: 路径，确认文件已打包进 jar（检查 target/ 目录下的 jar 包内容）
3. 确认 server.tongweb.license.type 和 server.tongweb.license.path 配置无误
4. 如使用远程认证，确认 License Server 地址可达、公钥正确

常见错误：

server:
  tongweb:
    license:
      # 错误：路径未加 classpath: 前缀，但文件在 resources 目录
      path: license.dat
      # 正确写法
      # path: classpath:license.dat

Q2: 依赖冲突（Tomcat vs TongWeb） ​

排查步骤：

1. 使用依赖树检查冲突：

mvn dependency:tree -P xc-tongweb > dep-tree.txt

2. 确认 Tomcat 依赖已被完全排除：

findstr tomcat dep-tree.txt

预期无输出，如有残留请检查 Profile 是否正确激活。

Q3: HTTPS 配置问题 ​

排查步骤：

1. 确认证书文件路径正确且文件存在
2. 确认密码与证书生成时设置的密码一致
3. 确认 keystore-type 与证书文件格式匹配（PKCS12 对应 .p12/.pfx，JKS 对应 .jks）

server:
  tongweb:
    use-https: true
    https-port: 8443
    keystore-path: classpath:keystore.p12
    keystore-password: your-password
    keystore-type: PKCS12

Q4: WebSocket 不生效 ​

原因分析： 未引入 tongweb-spring-boot-websocket-2.x 依赖。

解决方案： 在 pom.xml 中添加 WebSocket Starter 依赖（参见「12.1.4 核心功能使用 - 4.4 WebSocket 支持」）。

Q5: 端口不一致导致请求失败 ​

原因分析： TongWeb 默认 HTTP 端口为 9080，Tomcat 默认为 8080。切换容器后需调整前端代理或测试脚本中的端口配置。

解决方案： 修改 server.tongweb.http-port 为 8080，或调整调用方端口。

12.1.7 版本兼容性矩阵 ​

注意事项：

开发阶段：

• xc-tongweb Profile 仅在 Maven 打包时生效。IDE 中直接 Run 启动类时，需手动在 Maven 面板勾选该 Profile，否则仍使用 Tomcat
• TongWeb 默认 HTTP 端口为 9080，Tomcat 默认为 8080。切换容器后注意调整前端代理或测试脚本中的端口配置
• 确保项目中不存在多个 Servlet 容器实现（如同时引入 Tomcat 和 TongWeb）。使用 mvn dependency:tree 检查

上线后：

• 生产环境建议使用磁盘绝对路径（如 /opt/license/license.dat）而非 classpath 方式，便于独立更新 License 无需重新部署 jar 包
• TongWeb 运行日志输出到 logs/tongweb/ 目录，需关注磁盘空间，建议配置日志轮转策略
• 生产环境建议启用 HTTPS（use-https: true），证书文件路径和密码应通过环境变量或配置中心管理，避免硬编码
• 建议启用 monitor-starter 并对接 Grafana，实时监控 TongWeb 连接池、请求处理等关键指标