# 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 里的“实现要点/主要调用”就是索引。