快速落地 JT/T 808 服务端：jt-framework
一、项目名称
jt-framework
一句话简介：基于 Spring Boot 的 JT/T 808（并扩展 JT/T 1078、附件服务器、Dashboard）服务端框架，提供 starter + 示例工程，适合直接集成到你的车联网平台后端。
适用场景：
- 车联网平台对接终端：JT/T 808 登录/定位/心跳/下发指令
- 音视频与实时流：JT/T 1078 相关链路（beta）
需要可观测/运维入口：组件统计、请求处理器列表、Dashboard（beta）
二、开源协议
以仓库 LICENSE 为准
三、功能概述（核心卖点）
1）Spring Boot Starter（boot2/boot3 双线）
- 是什么：把 JT/T 808/1078 能力做成 starter，直接依赖即可启动服务端，不需要从零搭 Netty pipeline。
- 怎么做：
- Spring Boot 2.x：
jt-808-server-spring-boot-starter-boot2（JDK 8+） - Spring Boot 3.x：
jt-808-server-spring-boot-starter（JDK 17+）
- Spring Boot 2.x：
- 注意事项（可选）：boot2/boot3 的 JDK 与 Spring Boot 版本有硬约束，选型先看 README 的兼容矩阵。
2）注解驱动的消息处理
- 是什么：用注解/Handler 的方式组织业务处理逻辑，减少“switch case + 手写路由”的维护成本。
- 怎么做：示例工程集中在
samples/**、demos/**，可以直接照着写自己的 Handler。 - 注意事项（可选）：建议把“协议解析/校验/分包重组”留在框架层，把“业务入库/告警/策略”放在你的业务模块。
3）分包/下发/加解密等协议常见难点覆盖
- 是什么：覆盖 JT/T 808 常见能力：消息分包、消息下发、报文加解密、多版本适配。
- 怎么做：配置项通过
application.yml/yaml管理，示例里能看到分包缓存、线程池、最大帧长等参数。 - 对外部依赖要显式说明：
- 分包存储支持
caffeine / redis / none（示例里有 caffeine、redis 的配置块） - 若启用 redis，你需要自备 Redis 服务并开放连接权限
- 分包存储支持
4）附件服务器（苏标附件等）
- 是什么：独立的附件服务器能力（与 808 指令服务器可分开启停），用于上传/接收附件数据链路。
- 怎么做：示例
samples/jt-808-attachment-server-sample中可看到：jt808.attachment-server.enabled: truejt808.attachment-server.port: 6809
- 注意事项（可选）：附件临时目录/落盘目录需要可写权限（示例默认
/tmp/jt808-attachment-server-demo/）。
5）JT/T 1078（beta）
- 是什么：提供 1078 服务端 starter + 示例（WebMVC/WebFlux），用于音视频链路相关场景。
- 怎么做：示例
samples/jt-1078-server-sample-webmvc-boot3/...webflux-boot3：- HTTP：
server.port: 1078 - TCP：
jt1078.server.port: 61078
- HTTP：
- 注意事项（可选）：示例里包含数据 dump 到文件的配置（默认
/tmp/jtt/**），部署到容器或生产机时要显式挂载目录。
6）Dashboard（beta）
- 是什么：Dashboard server/client + UI（Vue3）模块，提供更直观的运行态入口。
- 怎么做：模块在
dashboard/**，UI 在dashboard/jt-dashboard-server-ui-vue3。 - 注意事项（可选）：Dashboard 模块当前只支持
spring-boot-3.x/jdk17+（见 README 模块矩阵）。
四、技术选型
- 后端：
Java · Spring Boot 2/3 · Netty（协议服务端常见实现路径） - 构建：
Gradle · Kotlin DSL（*.gradle.kts） - 协议/编解码：
jt-framework · xtream-codec 适配器（3.0.0-rc.1 起内置） - 缓存（可选）：
Caffeine · Redis - Dashboard：
Spring Boot 3.x · Vue3（jt-dashboard-server-ui-vue3）
五、如何使用
准备数据/环境（先看这个）：
- JDK：
- Spring Boot 3.x 示例：JDK 17+
- Spring Boot 2.x 示例：JDK 8+（但仓库整体构建链路以 JDK17 为主，建议本地直接用 JDK17 跑 boot3 示例）
- 端口（示例默认/推荐）：
- JT/T 808 TCP：
6808（在jt-808-server-sample-customized里显式配置） - JT/T 808 管理 HTTP：
8808（多个 sample 默认server.port: 8808） - 附件服务器：
6809（jt-808-attachment-server-sample） - JT/T 1078 TCP：
61078；HTTP：1078（application-local.yaml）
- JT/T 808 TCP：
- 权限/网络：需要开放 TCP 端口给终端连入；容器环境记得映射端口
方式 1：手动构建（maven ）
<dependency>
<groupId>io.github.hylexus.jt</groupId>
<artifactId>jt-808-server-spring-boot-starter-boot2</artifactId>
<version>3.0.0-rc.1</version>
</dependency>
- Windows 可用：
\.\gradlew.bat ...
六、二次开发注意事项
- 环境依赖版本（从 README/构建配置推断）：
- Spring Boot 2.x starter：JDK 8+（上限到 2.7.18）
- Spring Boot 3.x starter：JDK 17+（3.0.0+）
- 构建工具：Gradle Wrapper（
gradlew/gradlew.bat）
- 本地开发启动方式：
- 先跑 sample：
./gradlew :samples:jt-808-server-sample-bare-boot3:bootRun - 再按需迁移配置到你的业务工程（核心就是依赖 starter + application.yml）
- 先跑 sample：
- 常见问题 3 条以内：
- 端口冲突：HTTP（
server.port）和 TCP（jt808.server.port/jt1078.server.port）是两套端口，别只改一个。 - 容器内目录不可写：1078/附件服务器示例默认写
/tmp/**，生产环境需要挂载并给权限。 - 分包缓存策略：caffeine/redis 的选择会影响一致性与资源占用，压测后再定。
- 端口冲突：HTTP（
八、目录结构与主要文件
jt-framework/
├── jt-core # 公共基础能力（供 808/1078/dashboard 复用）
├── jt-808-server-support # JT/T 808 核心实现（协议处理链路、编解码等）
├── jt-808-server-spring-boot-starter # Spring Boot 3.x starter（JDK17+）
├── jt-808-server-spring-boot-starter-boot2 # Spring Boot 2.x starter（JDK8+）
├── jt-1078-server-support # JT/T 1078 核心实现（beta）
├── jt-1078-server-spring-boot-starter # 1078 Spring Boot 3.x starter（beta）
├── dashboard/ # Dashboard 模块（server/client/ui，beta）
├── samples/ # 可直接运行的示例（808/1078/附件服务器/codec 适配等）
├── demos/ # Demo 工程（更多组合示例）
├── docs/ # 文档站点（VuePress）
├── build.gradle.kts # 根构建脚本（依赖管理、发布、checkstyle 等）
└── settings.gradle.kts # 多模块声明（包含 samples/demos/dashboard）
