域名服务

引用文件

本文引用的文件

简介

本文件面向“域名服务”的技术文档，聚焦于域名解析与管理机制、域名与设备的关联关系、缓存与失效策略、安全防护、高可用架构、监控运维以及完整 API 文档与客户端集成示例。域名服务通过“域名配置 + 规则匹配 + 设备维度 + 缓存聚合”的方式，为设备侧提供按平台、按规则下发的域名与应用下载地址集合，并结合网关灰度负载均衡、安全过滤与监控体系，形成端到端的稳定与安全能力。

项目结构

域名服务主要分布在以下模块与文件：

控制层：管理后台域名 CRUD、分页、导出
业务层：域名与UOTA应用聚合、规则匹配、缓存策略
数据访问层：MyBatis Mapper、DO 定义
关联模块：规则引擎（绑定设备计数）、设备缓存、基础设施文件存储、网关安全与灰度负载均衡、监控指标

Mermaid Diagram Code:

graph TB
subgraph "域名服务模块"
DC["DomainController<br/>管理后台接口"]
DS["DomainService/Impl<br/>业务逻辑"]
DM["DomainMapper<br/>数据访问"]
DO["DomainDO<br/>实体"]
DUAS["DomainUotaAppService<br/>UOTA应用服务"]
DUADO["DomainUotaAppDO<br/>UOTA实体"]
end
subgraph "关联模块"
RBA["RuleBusinessApi<br/>规则绑定/计数"]
DCache["DeviceCacheUtils<br/>设备缓存"]
IFU["InfraFileUtil<br/>文件存储工具"]
FDTO["FileRespDTO<br/>文件响应DTO"]
end
subgraph "网关与安全"
GW["GatewayServerApplication<br/>网关入口"]
GFilter["GrayReactiveLoadBalancerClientFilter<br/>灰度LB"]
SEC["AppApiSecurityProperties/Configuration<br/>安全配置"]
end
subgraph "监控"
METRICS["YudaoMetricsAutoConfiguration<br/>指标标签"]
end
DC --> DS
DS --> DM
DS --> DUAS
DS --> RBA
DS --> DCache
DS --> IFU
DUAS --> DUADO
DM --> DO
IFU --> FDTO
GW --> GFilter
GW --> SEC
GW --> METRICS

图表来源

章节来源

核心组件

控制层 DomainController：提供域名的创建、更新、删除、查询、分页、导出 Excel 等管理后台接口，并联动规则引擎返回设备绑定数量。
业务层 DomainService/Impl：负责域名与UOTA应用聚合、规则匹配、缓存策略、租户上下文切换、设备维度匹配。
数据访问层 DomainMapper/DO：提供分页查询、实体映射与持久化。
关联模块：规则引擎 RuleBusinessApi 提供设备绑定计数；DeviceCacheUtils 提供设备缓存查询；InfraFileUtil 提供文件下载地址拼装；DomainUotaAppService/DO 提供启用状态的UOTA应用列表。

章节来源

架构总览

域名服务整体由“管理后台接口 + 业务聚合 + 规则匹配 + 缓存 + 文件存储 + 网关安全”构成，支持按平台聚合域名与UOTA应用，并根据设备维度进行规则匹配，最终返回给客户端。

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理后台"
participant Ctrl as "DomainController"
participant Svc as "DomainServiceImpl"
participant Rule as "RuleBusinessApi"
participant Dev as "DeviceCacheUtils"
participant Infra as "InfraFileUtil"
participant LB as "GrayReactiveLoadBalancerClientFilter"
Admin->>Ctrl : "分页/查询/导出"
Ctrl->>Svc : "getDomainPage()/getDomain()"
Svc->>Rule : "设备绑定计数"
Rule-->>Svc : "返回计数"
Ctrl-->>Admin : "返回结果"
Admin->>Ctrl : "获取UOTA域名V2"
Ctrl->>Svc : "getUotaDomainVOV2()"
Svc->>Dev : "按mac/cpu获取设备"
Dev-->>Svc : "设备信息"
Svc->>Svc : "规则匹配(域名/应用)"
Svc->>Infra : "加载文件URL/元信息"
Infra-->>Svc : "文件响应DTO"
Svc-->>Ctrl : "聚合后的UotaDomainVO"
Ctrl-->>Admin : "返回结果"
Note over Ctrl,LB : "后续经网关灰度LB转发至目标服务"

图表来源

详细组件分析

控制层：DomainController

职责：提供管理后台域名的增删改查、分页、导出 Excel；在分页时联动规则引擎返回每个域名绑定的设备数量。
关键点：权限注解、分页参数、Excel 导出、设备计数聚合。

章节来源

DomainController.java

业务层：DomainService/Impl

职责：
- 域名 CRUD 与分页；
- UOTA域名聚合：按平台聚合域名与启用的UOTA应用，支持本地缓存；
- 设备维度聚合：优先使用客户端令牌中的设备信息，否则从设备缓存查询；再通过规则引擎匹配域名与UOTA应用ID集合，最终裁剪返回。
缓存策略：使用本地缓存注解，按平台 key 缓存聚合结果，同步模式避免缓存击穿。

Mermaid Diagram Code:

flowchart TD
Start(["进入 getUotaDomainVOV2"]) --> HasClient["是否存在客户端令牌设备信息"]
HasClient --> |是| UseClient["复制客户端设备信息"]
HasClient --> |否| GetDev["从设备缓存按mac/cpu获取设备"]
GetDev --> DevOK{"设备信息是否有效"}
DevOK --> |否| Empty["返回空结果"]
DevOK --> |是| UseDev["复制设备信息"]
UseClient --> Match["规则匹配：域名/应用ID集合"]
UseDev --> Match
Match --> Fetch["从本地缓存获取聚合结果"]
Fetch --> Found{"缓存命中？"}
Found --> |否| Build["构建聚合结果域名+启用UOTA应用"]
Found --> |是| ReturnCache["返回缓存"]
Build --> ReturnRes["返回裁剪后的结果"]
ReturnCache --> End(["结束"])
ReturnRes --> End
Empty --> End

图表来源

章节来源

数据访问层：DomainMapper/DO

职责：提供分页查询、条件过滤（类型/域名/启用/备注），映射 DO 实体。
关键点：动态数据源标注（任务UOTA库）、分页包装。

章节来源

关联模块

规则引擎：RuleBusinessApi 提供设备绑定计数与批量计数，用于管理后台展示与业务决策。
设备缓存：DeviceCacheUtils 提供按 mac/cpu 查询设备信息，作为规则匹配输入。
文件存储：InfraFileUtil 通过文件ID获取 URL、大小、版本等元信息，拼装 UOTA 应用下载地址。

章节来源

依赖关系分析

控制层依赖业务层；业务层依赖 Mapper/DO、规则引擎、设备缓存、文件工具。
网关层依赖灰度负载均衡过滤器，实现基于服务实例的选择与安全过滤。
监控层通过指标自动配置注入通用标签，便于统一观测。

Mermaid Diagram Code:

classDiagram
class DomainController {
+createDomain()
+updateDomain()
+deleteDomain()
+getDomain()
+getDomainPage()
+exportDomainExcel()
}
class DomainService {
<<interface>>
+createDomain()
+updateDomain()
+deleteDomain()
+getDomain()
+getDomainPage()
+getUotaDomainVO()
+getUotaDomainVOV2()
}
class DomainServiceImpl {
+createDomain()
+updateDomain()
+deleteDomain()
+getDomain()
+getDomainPage()
+getUotaDomainVO()
+getUotaDomainVOV2()
}
class DomainMapper {
+selectPage()
}
class DomainDO
class RuleBusinessApi
class DeviceCacheUtils
class InfraFileUtil
DomainController --> DomainService : "依赖"
DomainService <|.. DomainServiceImpl : "实现"
DomainServiceImpl --> DomainMapper : "使用"
DomainServiceImpl --> RuleBusinessApi : "调用"
DomainServiceImpl --> DeviceCacheUtils : "使用"
DomainServiceImpl --> InfraFileUtil : "使用"
DomainMapper --> DomainDO : "映射"

图表来源

性能与缓存

本地缓存：聚合结果按平台 key 缓存，同步模式避免并发击穿；新增/更新/删除域名后主动清缓存，确保一致性。
分页与批量计数：管理后台分页查询时，一次性批量拉取设备绑定计数，减少多次远程调用。
文件元信息：通过文件ID直接拼装 URL 与版本信息，避免重复查询。

章节来源

安全机制

访问控制：管理后台接口使用权限注解进行资源级授权。
设备接入安全：针对机顶盒请求，提供签名与加解密配置，支持指定域名白名单、签名路径、加密路径与SDK密钥版本。
网关安全：通过安全过滤器与响应加密切面，按配置决定是否验签与加密返回。
HTTPS 与证书：网关依赖 Spring Cloud Gateway 与注册中心/配置中心，结合生产环境配置实现 HTTPS 与证书管理（详见部署配置）。

章节来源

高可用与容错

灰度负载均衡：网关通过自定义灰度负载均衡过滤器，支持按服务实例选择与生命周期回调，提升流量治理能力。
动态路由：基于 Nacos 配置中心的动态路由刷新能力，实现路由变更无需重启。
健康检查与自动恢复：结合注册中心的服务发现与健康检查，配合灰度LB的生命周期事件，实现故障转移与可观测性。

章节来源

监控与运维

指标标签：通过自动配置为 Micrometer 注入通用应用标签，便于统一采集与展示。
网关监控：网关内置 Druid 监控页面与访问日志过滤器，辅助定位问题。
运维建议：结合生产环境配置与监控面板，持续观察网关健康、路由命中率与业务指标。

章节来源

API 接口文档

管理后台接口

创建域名
- 方法：POST
- 路径：/task/domain/create
- 权限：task:domain:create
- 请求体：DomainSaveReqVO
- 返回：Long（主键）
更新域名
- 方法：PUT
- 路径：/task/domain/update
- 权限：task:domain:update
- 请求体：DomainSaveReqVO
- 返回：Boolean
删除域名
- 方法：DELETE
- 路径：/task/domain/delete
- 权限：task:domain:delete
- 参数：id（Long）
- 返回：Boolean
获取域名
- 方法：GET
- 路径：/task/domain/get
- 权限：task:domain:query
- 参数：id（Long）
- 返回：DomainRespVO（含设备绑定计数）
域名分页
- 方法：GET
- 路径：/task/domain/page
- 权限：task:domain:query
- 查询：DomainPageReqVO
- 返回：PageResult<DomainRespVO>（每条记录含设备绑定计数）
导出域名 Excel
- 方法：GET
- 路径：/task/domain/export-excel
- 权限：task:domain:export
- 查询：DomainPageReqVO（不分页）
- 返回：Excel 文件

章节来源

DomainController.java

APP 接口（域名聚合）

获取UOTA域名（V2，带mac/cpu）
- 方法：POST 或 GET（视具体实现）
- 路径：/app-api/...（参考固件对接文档）
- 请求：DomainListReqVO（包含 platform、mac、cpu 等）
- 返回：UotaDomainVO（包含 domains 与 uotaApps 列表）

章节来源

客户端集成示例

固件侧集成要点：
- 先获取服务器时间戳，再构造请求数据，按协议签名与加密（如需）。
- 通过域名服务接口获取域名与UOTA应用列表，按平台筛选后选择可用域名与应用。
- 参考 C 语言 TCP 客户端示例与 HTTP 协议文档。

章节来源

故障排查

域名不存在：删除/更新前进行存在性校验，抛出相应异常。
设备信息缺失：当无客户端令牌且设备缓存查询失败时，返回空结果，需检查设备缓存与规则匹配输入。
缓存未命中：确认缓存 key（platform）与缓存注解配置；新增/更新/删除后是否清除了缓存。
安全配置生效：核对 no-need-domain、sign-urls、encryption-urls 与 SDK 配置是否正确。
网关转发：若灰度LB未生效，检查请求 scheme 是否为 grayLb，以及服务实例健康状态。

章节来源

结论

域名服务以“规则驱动 + 设备维度 + 本地缓存 + 文件聚合”的方式，为设备侧提供稳定、可扩展的域名与UOTA应用下发能力。结合网关灰度负载均衡、安全过滤与监控体系，形成从配置到下发再到可观测的闭环。建议在生产环境中完善证书与安全配置，持续优化缓存与规则匹配策略，并通过监控与告警体系保障高可用。

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

控制层：DomainController​

业务层：DomainService/Impl​

数据访问层：DomainMapper/DO​

关联模块​

依赖关系分析​

性能与缓存​

安全机制​

高可用与容错​

监控与运维​

API 接口文档​

管理后台接口​

APP 接口（域名聚合）​

客户端集成示例​

故障排查​

结论​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

控制层：DomainController

业务层：DomainService/Impl

数据访问层：DomainMapper/DO

关联模块

依赖关系分析

性能与缓存

安全机制

高可用与容错

监控与运维

API 接口文档

管理后台接口

APP 接口（域名聚合）

客户端集成示例

故障排查

结论