# 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 平台:
~~~text
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 会强制读取:
~~~text
C:\ProgramData\MiDM\midm.properties
~~~
目录或文件不存在时,PropertySourcesPlaceholderConfigurer 会抛
FileNotFoundException,应用直接启动失败。本地开发建议内容:
~~~properties
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 命令
~~~powershell
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 里的“实现要点/主要调用”就是索引。