Files
mdm/docs/CODE_WALKTHROUGH.md
T
rick 10aa1829f5 fix: repair decompiled sources and add exhaustive documentation
- restore generic signatures, scoped variables and missing code from original bytecode
- remove decompiler artifacts and document classes, methods, fields and packages
- restore resources, add Batik/BouncyCastle dependencies and build/runtime docs
2026-11-16 17:28:23 +08:00

22 KiB
Raw Blame History

MiDM 源码学习指南(CODE WALKTHROUGH)

目标:把反编译出来的 Java 代码变成一套可以按图索骥学习的工程。 本文件讲架构与调用链;每个类/方法/字段的细节看源码里的 Javadoc (本次已补全 286 个类型、3,989 个方法、1,733 个字段的注释)。


0. 推荐阅读顺序

  1. 先读本文件第 1~4 节,建立“端 → 云 → Mongo → 管理后台”的整体地图。
  2. 读 com.midm.model:先看 GeneralProfile、Device、DeviceProfile、Site、User。
  3. 读 com.midm.service.BaseService 与一个具体 Service(推荐 DeviceService)。
  4. 读 com.midm.websocket.message.QueryHandler:这是设备协议的总入口。
  5. 读 com.midm.webservice.device.DeviceApi / DeviceProfileApi:管理端 REST 入口。
  6. 最后读文件/报表/云存储/安全等横向能力。

1. 系统全景

MiDM 是一套面向工业手持终端、车载平板、POS/医疗设备的 MDM/EMM 平台:

Android 设备 (DPC/MDM Agent)
   │  WebSocket /query(文本 JSON、二进制 Deflate)
   │  REST /dpc/*、/file/*(下载、二维码、APK/OTA)
   ▼
Spring Boot 2.7 (WAR)
   ├─ QueryHandler ── WebSocketSessionManager ── DeviceService / ProfileService / BatteryService
   ├─ Controller / WebService ── UserService / SiteService / FileService / ReportService
   ├─ MongoTemplate / Repository ── MongoDB (db_midm)
   └─ CloudStorageService ── AWS S3 / Azure Blob / GCP Storage

管理后台(Thymeleaf + 静态前端)通过 REST/JSON 与 WebSocket 同时接入; 设备端主要走 WebSocket 长连接,少量文件下载走 HTTP。

技术栈:Java 11 目标字节码、Spring Boot 2.7.15、Spring Security 5.7、 Spring Data MongoDB 3.4、Thymeleaf、POI、Flying Saucer、ZXing、OkHttp、 AWS SDK v1/v2、Azure SDK、Google Cloud Storage、Batik。


2. 目录地图

包 作用 先看谁
com.midm 启动入口 MainApplication
com.midm.app Mongo/Security/WebSocket/Locale/启动初始化 DbConfig、SecurityConfig、DbInitialize、StartupKeeper
com.midm.app.converter 请求参数 → 对象转换 DateConverter、JsonObjectConverter
com.midm.constant 常量、集合名、协议码 MidmConst、PropertyConst
com.midm.controller 页面路由(Thymeleaf) HomeController、DeviceController
com.midm.controller.lib 图片/文件下载 FilesController、StoreController
com.midm.dpc Android Enterprise 零接触 DpcController、DpcModel
com.midm.model 领域模型 / Mongo 文档 GeneralProfile、Device、DeviceProfile
com.midm.repository Spring Data Repository DeviceLicenseRepository
com.midm.security 认证主体 UserPrincipal
com.midm.service 业务服务 BaseService、DeviceService、ProfileService
com.midm.webservice 管理端/设备端 REST API DeviceApi、DeviceProfileApi、UserApi
com.midm.websocket WebSocket 网关与协议处理 QueryHandler
com.mitac.cell 通用基础库 DbObject、McJsonUtils、McFile、McTextEncryptor

3. 启动与配置链路

3.1 启动入口

MainApplication:

  • @SpringBootApplication(scanBasePackages = "com.midm");
  • 继承 SpringBootServletInitializer,既支持 java -jar 也支持外置 Tomcat;
  • @EnableScheduling 打开定时任务;
  • restart() 在非守护线程中关闭并重建 Spring 上下文,用于运行期热重启。

3.2 外部配置

PropertiesConfig 会强制读取:

C:\ProgramData\MiDM\midm.properties

目录或文件不存在时,PropertySourcesPlaceholderConfigurer 会抛 FileNotFoundException,应用直接启动失败。本地开发建议内容:

mongo.uri=
mongo.host=127.0.0.1
mongo.port=27017
mongo.dbname=db_midm
mongo.replica_set=

application.properties 负责日志级别、Session Cookie、Tomcat access log、 Thymeleaf 缓存、静态资源缓存等 Spring Boot 配置;Mongo 连接参数集中在 DbConfig 的 @Value 字段。

3.3 Mongo 连接池

DbConfig.getConnectiontString() 根据 mongo.uri / mongo.host 动态拼装 ConnectionString:

  • 多节点时拆分逗号分隔的 host,补齐默认端口;
  • 强制 w=majority、retryWrites=true、uuidRepresentation=javaLegacy;
  • 按配置补齐 maxPoolSize、connectTimeoutMS、maxIdleTimeMS、 waitqueuetimeoutms、ssl、replicaSet;
  • fixDb() 在启动时做索引自愈(删除低效单字段索引,确保复合索引生效)。

注意:单机 MongoDB 要把 mongo.replica_set 置空;副本集才填 rs0 并执行 rs.initiate()。

3.4 初始化与启动钩子

  • DbInitialize:首次启动时建集合/索引、修复历史数据、补默认设置。
  • StartupKeeper:监听 ContextRefreshedEvent,加载系统设置、恢复同步、 校验 License、加载语言与帮助消息、初始化设备状态、清理孤儿数据、安排通知任务。

4. 领域模型与 MongoDB

4.1 公共基类 GeneralProfile

大部分业务对象继承 com.midm.model.GeneralProfile:

字段 作用
uuid 业务主键(@Id),全系统统一用 UUID
created / updated 创建/更新时间
profile DbObject 扩展属性包,承载厂商/硬件/软件等可变字段
enabled 通用启用状态

DbObject 继承 org.bson.Document,提供 getString/getBoolean/getList/getDbObject 等便捷方法,避免到处强转。

4.2 常用注解

注解 含义
@Document 映射为 MongoDB 集合
@Id 文档主键
@Indexed 建索引,常用于查询条件
@Field("x") 指定 Mongo 字段名
@Transient 不持久化,仅运行时
@DBRef 引用其他文档(慎用,查询成本高)
@Expose(serialize=false) Gson 序列化时排除(如密码)

4.3 核心集合(按业务)

领域 主要类 说明
设备 Device、DeviceApps、DeviceGroup、DeviceNote 设备档案、已装应用、分组树、备注
策略 DeviceProfile、ProfileApps、ProfileScope 配置档案、应用/文件/OTA 项、作用域
组织 Site、User、SiteInfo、UserGroup 多租户站点、账号、站点成员、用户组
授权 DeviceLicense、SiteLicense、LicenseModel、HostLicense 设备/站点/主机 License
文件 BaseFile、AppFile、OtaFile、StoreAppFile APK/OTA/普通文件/商店文件
遥测 Battery、BatteryLog、DataUsage、DeviceReport 电池健康、流量、设备报表
审计 MidmLog、DeviceLog 操作/设备日志
系统 SystemSetting、Locale、HelpMessage、NewsMessage 设置、语言、帮助、通知
商店 StoreApp、StoreWebApp、AppReleaseNote 应用商店/WebApp/发布说明

阅读实体时先看字段注释和注解,再看对应 Service 如何构造 Criteria。


5. Web 层与安全

5.1 两类入口

  • com.midm.controller:返回 Thymeleaf 视图名,服务管理后台页面;
  • com.midm.webservice:@RestController/JSON,服务前端 AJAX 与设备/第三方 API。

统一响应封装是 MidmResponse(code/message/data),异常由 ExceptionController 收敛。

5.2 认证与授权

  • SecurityConfig 定义过滤器链、登录页、静态资源放行、CSRF/Headers;
  • BasicAuthInterceptor 处理 Basic/Token 头;
  • UserPrincipal 把 User 包装成 Spring Security 主体;
  • UserRole 定义角色常量(SUPERVISOR、DEVICE_MANAGER、PROFILE_MANAGER 等);
  • UserService.authorizedUser(authentication, accessToken) 是各 API 的统一鉴权入口;
  • user.canHandle(siteUuid, roles) 做站点级权限判断。

5.3 典型 REST 调用链

DeviceApi.findDevices() → UserService.authorizedUser() → 站点校验 → DeviceService.findDevices() → BaseService.findByPage() → MongoTemplate。


6. WebSocket 设备通道(重点)

6.1 端点与握手

WebSocketConfig 把 /query 注册到 QueryHandler,允许跨域。 握手完成后 afterConnectionEstablished:

  1. WebSocketSessionManager.toMidmSocketSession(session, true) 从 Header/Query 解析设备序列号或用户 Token,包装成 MidmWebSocketSession;
  2. 按配置设置文本/二进制最大缓冲;
  3. 设备连接走 onConnected,管理端用户连接走 register。

6.2 报文模型

MidmPacket 是统一报文:

  • query:请求(MidmQuery,含 code/request/params);
  • feedback:响应(MidmResponse,含 code/message/data);
  • uuid / queryUuid / recieverUuid:路由与幂等;
  • 支持 toTextMessage() / toBinaryMessage(),二进制路径用 McCompress 压缩。

MIDM_REQUEST 定义协议码,例如:

code 枚举 含义
99 PING 心跳
100 CONNECT 建连
104 ENROLL 设备注册
105 DEVICE_INFO 设备信息/遥测上报
131/132 UPDATE_PROFILE / UPDATE_ALL_PROFILES 策略下发/全量同步
136 REMOVE_PROFILE 移除策略
200 COMMAND 远程指令
210 QUERY 查询设备信息
400 RTC 远程协助/WebRTC 信令

6.3 消息分发

QueryHandler.handleMessage:

  1. 刷新 pong 时间戳;
  2. 若租户开启流量采集,按阈值触发 updateDataUsage;
  3. 按帧类型分派:
    • PongMessage → onPong;
    • TextMessage → handleTextMessage("ping" 或 JSON MidmPacket);
    • BinaryMessage → McDecompress 解压后按 feedback/ping 处理。

onFeedback 是业务总路由:ENROLL 注册、DEVICE_INFO 更新设备、 UPDATE_PROFILE/命令回执、RTC 信令等。

6.4 会话管理

WebSocketSessionManager 维护:

  • deviceSessions:设备 UUID → MidmWebSocketSession;
  • userSessions:用户 UUID → UserSocketSessions;
  • 心跳 ping/pong、在线状态广播、断线清理;
  • ReconnectMonitor:滑动窗口统计重连频率,异常时 block,防止弱网重连风暴。

6.5 设备注册(ENROLL)链路

QueryHandler.onFeedback 的 ENROLL 分支:

  1. 校验序列号;找不到站点/白名单不允许则回 451/463/461 并关闭;
  2. DeviceService.register():初始化设备、绑定分组、所有者、站点;
  3. License 激活/试用;
  4. 审计日志 LogService.saveDeviceLog;
  5. 注册全局 Session,下发 111 + 精简设备配置;
  6. License 过期则回 115 并关闭。

7. 设备生命周期与策略

7.1 设备

DeviceService 是设备中枢:

  • 注册/保存/批量导入:register、save、saveDevices;
  • 查询:findBySerialNo、findDeviceByUuid、findDevices(分页/过滤);
  • 分组:findGroupFamily、findChildGroups、findAllDevicesInGroup;
  • 删除/退役:delete、retire、deleteBySite;
  • License:setTrialLicense、activateLicense、renewLicense;
  • OTA 回调:systemImageUpdated、regionImageUpdated。

7.2 策略(Profile)

ProfileService 负责配置档案:

  • CRUD:save、find、delete、findProfiles;
  • 作用域:updateScope、unscope、isDeviceScoped、isGroupScoped;
  • 下发:notifyToSync 给设备发 WebSocket 通知;
  • 应用状态:isProfileApplied、profileStatesByDevice;
  • 冲突解决:ProfileAdvisor 计算应用/设置/OTA 冲突,决定最终下发项。

7.3 License

  • DeviceLicense:设备级,含 licenseModel、expiry、activationCount;
  • SiteLicense:站点级采购/续费;
  • LicenseModel:型号/周期/最大激活数;
  • HostLicenseService:主机级 License 校验(单机/多租户模式)。

8. 文件与云存储

8.1 文件模型

  • BaseFile:文件名、大小、校验和、站点、分类;
  • AppFile:APK 包名、版本号、minSdk、签名证书;
  • OtaFile:固件 build date、SKU、区域、系统/区域镜像标记。

8.2 路径规则

FileService 统一生成路径:getFilePath、getDeviceFilePath、 getSiteFilePath、getMustFolderFilePath。上传/下载/删除都走这里, 避免路径拼接散落各处。

8.3 多云策略

CloudStorageService 根据 cloud.storage 设置选择:

  • AwsS3
  • AzureBlob
  • GoogleCloudStorage

统一接口:upload、download/getUrl、exists、delete、list、 updateMetaInfo、refreshClient。大文件用预签名 URL 让设备直连云存储, 服务端只负责签发和元数据。

8.4 APK 签名

StoreAppService.sign() 调用资源里的 apksigner/apksigner.jar, 用 keystore 对 APK 重签名,并记录证书 MD5/版本信息。


9. 报表、邮件与模板

9.1 报表

ReportService 基于 POI 的 ExcelWriter 生成三类报表:

  • generateDeviceReport:设备清单/状态/流量/电池;
  • generateProfileReport:策略应用情况;
  • generateSiteReport:站点/License/设备分布。

模板在 src/main/resources/report/*.xlsx,生成后保存为 SiteFile, 可下载或邮件发送。

9.2 PDF

com.mitac.cell.doc.HtmlToPdf 用 Flying Saucer + iText 把 HTML 转 PDF。

9.3 邮件与模板

  • EmailService:发送密码重置、License、报表等邮件;
  • TemplateService:从 Mongo/资源加载模板;
  • McMailSender:封装 JavaMail,支持抄送/密送/附件;
  • EmailTemplateResolver:Thymeleaf 模板解析。

10. 异步、定时与并发

  • AsyncConfig:配置 ThreadPoolTaskExecutor;
  • @Async:报表生成、邮件发送、日志等不阻塞请求;
  • @Scheduled / ScheduledTaskService:设备离线检查、报表过期、通知;
  • ReconnectMonitor:滑动窗口 + 定时 unblock;
  • synchronized / ConcurrentHashMap:会话表、缓存等共享状态。

读并发代码时先找“共享字段”,再看锁粒度和任务调度器。


11. 安全细节

  • 设备密钥:DeviceKeyService 生成/保存 RSA 公私钥;
  • 请求验签:ExternalApiService.doRequestRsaIsValid 用 RSA-OAEP 解密设备密文;
  • 密码:BCrypt(PasswordEncoder);
  • API Token:UserToken / accessToken,一次性令牌用后删除;
  • 文件下载:FilesController 校验用户站点归属,防越权下载;
  • 安全头/CSRF/Session Cookie:SecurityConfig + application.properties。

12. 构建、运行与排错

12.1 本机环境

  • JDK 18(编译目标 11);
  • Maven 3.9.9;
  • MongoDB 7.0.14(单机);
  • C:\ProgramData\MiDM\midm.properties 必须存在。

12.2 命令

mvn clean package -DskipTests
java -jar target\midm-1.1.1.12.war

12.3 常见错误

现象 原因 处理
FileNotFoundException: c:\ProgramData\MiDM\midm.properties 运行配置缺失 创建目录和文件
replicaSet=rs0 连接失败 单机 Mongo 却配了副本集 mongo.replica_set= 置空
端口占用 8080 被占用 --server.port=18081
登录页 404 访问了错误路径 用 /,不是 /login
生成报表/邮件失败 模板/邮箱配置缺失 看 SettingsService 与运行日志

13. 建议的学习路线

天 目标 代码
Day 1 跑起来 + 模型 MainApplication → GeneralProfile → Device → Site → User
Day 2 通用 CRUD/分页 BaseService → DeviceService 的 find/save/delete
Day 3 设备协议 WebSocketConfig → QueryHandler → WebSocketSessionManager
Day 4 策略与 License ProfileService → ProfileAdvisor → DeviceLicense
Day 5 文件/报表/云存储 FileService → CloudStorageService → ReportService
Day 6 安全/定时任务 SecurityConfig → UserPrincipal → ScheduledTaskService

练习建议:

  1. 新增一个只读 API:GET /api/device/count,走 DeviceService.count;
  2. 给 Device 增加一个 @Indexed 字段,观察 DbInitialize 索引;
  3. 在 MIDM_REQUEST 增加一个协议码,在 onFeedback 加分支;
  4. 给 ProfileService 增加一个“按名称模糊查询”的方法并写 Javadoc。

14. 代码索引(功能 → 类)

功能 入口 核心实现
启动 MainApplication DbConfig、DbInitialize、StartupKeeper
登录/鉴权 UserApi UserService、SecurityConfig、UserPrincipal
设备列表/详情 DeviceApi DeviceService、BaseService
设备注册 QueryHandler.ENROLL DeviceService.register、WebSocketSessionManager
策略管理 DeviceProfileApi ProfileService、ProfileAdvisor
策略下发 ProfileService.notifyToSync WebSocketSessionManager
设备分组 DeviceApi DeviceService.findGroupFamily/findChildGroups
License LicenseApi、HostLicenseApi LicenseService、HostLicenseService
APK/OTA StoreAppsApi、OtasApi StoreAppService、FileService、OtaFile
文件下载 FilesController、DeviceFilesApi FileService、CloudStorageService
报表 ReportApi ReportService、ExcelWriter
电池 BatteryApi BatteryService
审计日志 LogsApi LogService
WebSocket /query QueryHandler、WebSocketSessionManager、ReconnectMonitor
零接触 DpcController DpcModel、StoreAppService
云存储 CloudStorageService AwsS3、AzureBlob、GoogleCloudStorage

15. 读代码时最值得问的三个问题

  1. 数据从哪里来? 看 @Document 字段、BaseService 的查询条件、Mongo 索引。
  2. 状态在哪里改? 看 Service 的 save/update 与 @Async/定时任务。
  3. 失败会怎样? 看 MidmResponse 错误码、throw、catch 与 WebSocket sendFeedback。

把这三问套到每个方法上,Javadoc 里的“实现要点/主要调用”就是索引。