跳到主要内容

域名分发管理

核心概念：域名分发 | 域名分发APP

域名分发管理模块是机顶盒与服务器通信的“生命线”，负责向设备下发可用域名组和最新版 UOTA 程序。

设备出厂时预装了一个兜底 APP（专门用于域名分发数据交换），即使主业务程序出现故障，该 APP 也能通过本模块获取最新的配置和修复程序，确保设备永远“在线”。

关联模块

1. 域名信息管理 (域名分发)​

核心概念：域名分发 | 域名分发APP | 域名信息管理

域名信息管理用于管理系统中的各类域名配置，为 UOTA 程序分配新的可用域名组。

核心价值 (域名信息)​

防止域名不可用导致失联。

UOTA 是整个系统的核心 APP，承担着配置下发（如任务推送配置）和数据上报的关键职责。

域名轮询与兜底机制：

  1. 预置域名：设备出厂时会在 UOTA 中预置一组域名。
  2. 动态下发：当预置域名不可用或需要更新时，设备会启动兜底程序（通过内置的 IP 或硬编码域名）请求本模块，获取最新的可用域名组。
  3. 自动轮询：UOTA 程序会遍历下发的域名组，逐个尝试连接。
  4. 故障转移：一旦当前使用的域名访问失败，UOTA 会自动从域名池中寻找下一个可用域名，直到再次发现可用域名访问失败，才继续从配置下发的域名池中寻找，确保设备永远“在线”。

点击访问：域名信息管理

列表查询 (域名信息)​

核心概念：域名分发 | 域名分发APP | 域名列表查询

在域名信息管理页面，您可以查询和管理域名配置。

查询列表

查询条件：

  • 域名类型：选择域名类型。
  • 域名：输入域名地址。
  • 是否开启：选择启用状态。
  • 备注：输入备注。

列表字段：

  • ID：唯一标识。
  • 域名类型：域名的分类（如API、资源等）。
  • 域名：具体的域名地址。
  • 是否开启：启用/禁用状态。
  • 备注：备注说明。
  • 创建者/更新者：操作人信息。
  • 创建/更新时间：时间记录。

新增/编辑 (域名信息)​

核心概念：域名分发 | 域名分发APP | 域名配置编辑

在域名信息管理页面，您可以新增或编辑域名配置。

新增与修改

表单字段：

  • 域名类型：必填，选择域名的类型。
  • 域名：必填，输入完整的域名地址。
  • 是否开启：选择是否立即启用。
  • 备注：选填。

2. UOTA-APP管理 (域名分发)​

核心概念：域名分发 | 域名分发APP | UOTA-APP管理

UOTA-APP管理用于管理域名分发关联的 UOTA 应用包信息。

核心价值 (UOTA-APP)​

终端设备的“终极救援”方案。 当盒子上的 UOTA-APP 发生意外（如被恶意卸载、自升级失败崩溃）导致与服务器断联时，设备上的兜底程序可以通过本模块下载最新的 UOTA 安装包进行重装或修复，恢复设备正常功能。

平台差异说明​

不同芯片方案的主板（如 Allwinner 全志、Rockchip 瑞芯微、Amlogic 晶晨）底层代码存在差异，因此需要针对不同平台下发对应的 UOTA 版本。

  • 所属平台：来源于数据字典 device_platform。

点击访问：UOTA-APP

列表查询 (UOTA-APP)​

核心概念：域名分发 | 域名分发APP | UOTA包列表查询

在UOTA-APP管理页面，您可以查询和管理UOTA应用包。

列表查询

查询条件：

  • 包名：应用包名。
  • 版本号：应用版本号。
  • 版本名称：应用版本名称。
  • 所属平台：设备平台（Allwinner/Rockchip/Amlogic 等）。
  • 是否开启：启用状态。
  • 创建时间：时间范围。

列表字段：

  • ID：唯一标识。
  • 文件表ID：关联的文件ID。
  • 文件url：文件下载地址。
  • 文件大小：文件字节大小。
  • 包名：应用包名。
  • 版本号：内部版本号。
  • 版本名称：显示版本名称。
  • 所属平台：适用的设备平台（Allwinner/Rockchip/Amlogic 等）。
  • 是否开启：启用状态。
  • 备注：备注说明。
  • 创建时间：记录创建时间。

新增/编辑 (UOTA-APP)​

核心概念：域名分发 | 域名分发APP | UOTA包配置编辑

在UOTA-APP管理页面，您可以新增或编辑UOTA应用包信息。

新增与修改

表单字段：

  • 文件上传：上传应用安装包。
  • 包名：必填。
  • 版本号：必填。
  • 版本名称：必填。
  • 所属平台：必填，选择设备平台（来源于数据字典 device_platform）。
  • 是否开启：选择是否启用。
  • 备注：选填。

3. 秘钥管理 (域名分发)​

核心概念：域名分发 | 域名分发APP | 秘钥管理

秘钥管理用于管理服务器与盒子 APP 通信过程中的加密与签名秘钥。

核心价值 (秘钥管理)​

保障通信安全，防止数据被篡改或伪造。秘钥类型来源于数据字典 task_secret_key_type。

秘钥类型与用途说明​

  1. 域名分发加解密 (DOMAIN_DISPATCH_ENCRYPT)

    • 用途：用于“兜底 APP”与服务器交互时的敏感数据加密。
    • 技术细节：参考 签名和加解密 文档。

  2. 域名分发签名 (DOMAIN_DISPATCH_SIGN)

    • 用途：盒子请求服务器时进行签名，服务器进行验签，确保请求来源合法。
    • 技术细节：参考 签名和加解密 文档。

  3. 固件请求加解密 (FIRMWARE_REQUEST_ENCRYPT)

点击访问：秘钥管理

列表查询 (秘钥管理)​

核心概念：域名分发 | 域名分发APP | 秘钥列表查询

在秘钥管理页面，您可以查询和管理通信秘钥。

列表查询

查询条件：

  • 秘钥类型：选择类型。
  • 创建时间：时间范围。

列表字段：

  • 主键：唯一标识。
  • 秘钥类型：秘钥的分类。
  • 秘钥唯一标识：Key ID。
  • 秘钥值：Key Value。
  • 时间差(毫秒)：允许的时间误差。
  • 备注：备注说明。
  • 创建时间：记录创建时间。

新增/编辑 (秘钥管理)​

核心概念：域名分发 | 域名分发APP | 秘钥配置编辑

在秘钥管理页面，您可以新增或编辑通信秘钥。

新增与修改

表单字段：

  • 秘钥类型：必填。
  • 秘钥唯一标识：必填。
  • 秘钥值：必填。
  • 时间差：必填，单位毫秒。
  • 备注：选填。
异步导出

当导出数据量较大时，系统会采用异步导出方式。您可以在 导出任务管理 中查看导出进度并下载文件。

4. 规则引擎集成 (高级分发)​

核心概念：域名分发 | 域名分发APP | 规则引擎集成

域名分发模块已全面接入 规则引擎，实现了从“静态分发”到“智能分发”的跨越。

4.1 为什么要结合规则引擎？​

在没有规则引擎之前，域名通常只能全局生效，或者硬编码一些简单的逻辑。结合规则引擎后，您可以实现：

  1. 灰度发布：“只对 5% 的随机设备下发新域名”。
  2. 地域优化：“巴西设备下发南美洲节点域名，中国设备下发亚洲节点域名”。
  3. 设备兼容：“只对内存大于 2GB 的设备下发高清资源域名”。
  4. A/B 测试：针对不同用户群下发不同配置，验证效果。

4.2 如何配置规则 (域名分发)​

核心概念：域名分发 | 域名分发APP | 规则配置

在域名分发列表页，选中某一行域名记录，下方会显示 规则配置组件 (RuleBusinessTabs)。

  1. 定义规则：

    • 您可以直接引用规则中心已有的规则（如“高端机型通用规则”）。
    • 也可以点击“新增”，现场创建一个专用规则（如“域名灰度测试规则”）。

  2. 绑定业务：

    • 域名分发 (DOMAIN_DISPATCH)：将规则与域名绑定。当设备命中该规则时，系统会下发该域名。
    • UOTA分发 (DOMAIN_DISPATCH_UOTA)：将规则与UOTA包绑定。当设备命中该规则时，系统会下发该升级包。

  3. 实时生效：

    • 域名分发业务不需要审批。
    • 一旦绑定完成，配置即刻生效。设备下次请求时（调用 DomainDistributeController 接口），系统会自动运行规则引擎匹配逻辑，返回命中的结果。
提示

规则引擎支持数十种设备属性（CPU、内存、系统版本、IP、MAC等）的组合判断，配合 EL表达式，可以实现极其复杂的业务逻辑。详情请参考 规则引擎使用手册。

5. 请求处理流程 (域名分发)​

核心概念：域名分发 | 域名分发APP | 请求处理流程

5.1 简易流程图 (用户视角)​

Mermaid Diagram Code:

sequenceDiagram
    participant Device as "终端设备 (机顶盒)"
    participant Server as "云端服务器"

    Device->>Server: "1. 发起请求 (携带MAC/机型等信息)"
    Server->>Server: "2. 识别设备身份"
    Server->>Server: "3. 匹配适用规则 (地区/灰度/机型)"
    Server-->>Device: "4. 返回可用域名列表 & UOTA升级包"
    Device->>Device: "5. 更新本地配置"

5.2 详细处理流程 (技术视角)​

Mermaid Diagram Code:

sequenceDiagram
    participant STB as "机顶盒/设备"
    participant Biz as "域名分发模块"
    participant Rule as "规则引擎 (RuleRunUtil)"
    participant Redis as "Redis缓存"
    participant LiteFlow as "LiteFlow规则链"

    STB->>Biz: "1. 请求域名配置 (MAC, 平台信息)"
    Biz->>Rule: "2. 调用 matchBusinessIds(业务类型=DOMAIN, 设备详情)"
    
    Note right of Rule: "3. 初筛候选规则"
    Rule->>Redis: "获取 MAC专属规则"
    Rule->>Redis: "获取 渠道关联规则"
    Rule->>Redis: "获取 域名业务规则"
    Rule->>Redis: "获取 无限制规则"
    
    Rule->>Rule: "4. 集合运算 (求交集/并集)"
    Note right of Rule: "候选集 = (MAC规则 U 无限制 U 渠道规则) ∩ 业务类型规则"
    
    loop "5. 遍历候选规则"
    Rule->>Redis: "获取规则详情"
    Rule->>Rule: "检查地区限制 (Region Check)"
    alt "地区匹配通过"
    Rule->>LiteFlow: "执行EL表达式匹配 (传入设备上下文)"
    LiteFlow-->>Rule: "返回匹配结果 (True/False)"
    else "地区不匹配"
    Rule->>Rule: "跳过该规则"
    end
    end
    
    Rule-->>Biz: "6. 返回匹配成功的 域名规则ID集合"
    Biz->>Biz: "根据规则ID查询绑定的域名列表"
    Biz-->>STB: "7. 返回最终可用域名列表"

5.3 逻辑详解​

  1. 设备接入: 机顶盒开机或周期性发起请求，上传 MAC 地址、CPU 型号、内存大小、Android 版本等设备指纹信息。
  2. 规则匹配: 服务器端规则引擎接管请求，进行多维度匹配：
    • 身份识别: 优先查找该 MAC 是否有专属测试规则。
    • 分组筛选: 根据设备所属渠道（Channel）查找关联规则。
    • 通用规则: 加载所有无设备限制的全局规则。
    • 特征过滤: 运行 LiteFlow 引擎，执行 EL 表达式判断设备硬件特征（如 内存 > 2G 且 Android版本 >= 10）。
  3. 结果聚合:
    • 系统取所有命中规则所绑定的域名集合的并集。
    • 如果没有任何规则命中，则返回空或默认兜底配置（视具体策略而定）。
  4. 下发响应: 将最终计算出的可用域名列表（包含主域名、备用域名）加密签名后返回给设备。

6. 测试环境模拟配置​

核心概念：域名分发 | 域名分发APP | 测试环境模拟

为了在测试环境中模拟真实生产环境的域名解析，我们需要使用 AdGuard Home 进行 DNS 重写。

6.1 配置步骤​

  1. 登录 AdGuard Home

  2. 添加 DNS 重写规则

    • 在“DNS 重写”页面，点击“添加 DNS 重写”。
    • 输入要劫持的生产环境域名（如 uota.ikb03.com）和测试服务器 IP（如 192.168.1.87）。

    DNS重写

  3. 验证配置

    • 将电脑或测试设备的 DNS 修改为 192.168.1.87。
    • 在终端执行 nslookup 命令验证解析结果。
    nslookup uota.ikb03.com

    如果返回的 Address 是 192.168.1.87，则说明配置生效。

    验证结果

6.2 机顶盒连接配置​

  1. 机顶盒连接测试 Wi-Fi（如 ASUS_2G4 或 ASUS_5G），密码一般为 88888888。
  2. 确保路由器已将 DNS 分配指向 192.168.1.87，或者在机顶盒网络设置中手动将 DNS 设置为 192.168.1.87。

7. 快速验证手册​

核心概念：域名分发 | 域名分发APP | 快速验证手册

本章节提供两种验证配置是否生效的方法。模式一适合快速检查后台配置，模式二适合模拟真实设备行为进行全链路测试。

7.1 模式一：快速验证（免签名）​

为了方便测试，服务端提供了一个跳过签名和加密验证的测试接口。

  • 接口地址：/app-api/hnc2fng/ghbn1hebdsh2/yh65hbfvg3jfdbs
  • 请求方式：POST
  • 特点：不需要 sign 和 time 头，直接返回明文 JSON 数据。

无需新建请求。本项目接口文档已全量导入 Apifox，且包含详细的 测试用例 (Test Cases)。

  1. 搜索接口：在 Apifox 中搜索关键词（如 快速验证 或 yh65hbfvg3jfdbs）。
  2. 选择用例：接口下通常挂载了多个测试用例（如 Allwinner平台, Rockchip平台），直接选择对应场景。
  3. 一键运行：无需手动填写参数，点击“运行”即可。

入参示例 (JSON)：

{
    "platform": "Allwinner",
    "mac": "AA:BB:CC:DD:EE:FF",
    "cpu": "test_cpu_001"
}

7.2 模式二：全流程仿真（带签名）​

核心概念：域名分发 | 域名分发APP | 全流程仿真验证

模拟真实机顶盒的交互流程，包含 获取时间 -> 签名 -> 请求 -> 解密 四个步骤。服务端提供了辅助接口来帮助测试人员生成签名和解密数据。

步骤 1：获取服务器时间​

首先获取服务器当前时间，用于后续签名。

  1. 搜索接口：在 Apifox 中搜索 获取服务器时间 或 dhgb35dg。
  2. 运行：直接点击“运行”，无需参数。

响应示例：

{ "code": 0, "data": { "time": 1753181666064 } }

记下这个 time 值。

步骤 2：生成签名​

调用辅助接口生成签名（模拟设备端算法）。

  1. 搜索接口：在 Apifox 中搜索 签名 或 sign。
  2. 入参示例： 
    {
        "domain": "localhost:48080",
        "mac": "9C:00:D3:58:B3:DF",
        "cpu": "82422823dde3caa6",
        "time": 1753181666064,
        "sdkVersion": 47
    }

响应示例：

{ "code": 0, "data": "2111360344febfc8a6179b19c9450871" }

记下 data 中的签名串。

步骤 3：发起正式请求（获取域名）​

调用正式接口，带上签名头。

  • 接口: /app-api/hnc2fng/ghbn1hebdsh/yh65hbfvg3jfdbs (注意与模式一的接口路径区别)
  • Header: 必须包含 time, sign, mac, cpu。

无需手动签名。本项目接口文档已全量导入 Apifox，且包含详细的 测试用例。

  1. 搜索接口：在 Apifox 中搜索 正式请求 或路径 yh65hbfvg3jfdbs。
  2. 选择用例：选择对应的测试用例（如 正常请求）。
  3. 一键运行：点击“运行”。(部分用例已配置前置脚本自动计算 sign 和 time)。

入参示例 (JSON)：

{
    "platform": "Allwinner"
}

响应示例（Data是加密的）：

{
    "code": 0,
    "data": "DC15hFmkezrskGUxijhd47DMxzS8IXKtuXAwJ6YC0C6mrBBxHJi0Cw6VVJxkIDxSeHU..."
}

步骤 4：解密数据​

调用辅助接口解密响应内容。

  1. 搜索接口：在 Apifox 中搜索 解密 或 decrypt。
  2. 入参示例： 
    {
        "encryptedText": "DC15hFmkezrskGUxijhd47DMxzS8IXKtuXAwJ6YC0C6mrBBxHJi0Cw6VVJxkIDxSeHU...",
        "sdkVersion": 47
    }

最终结果：

{
    "code": 0,
    "data": "{\"uotaApps\":[...], \"domains\":[...]}"
}

此时你可以看到服务端下发的明文域名列表和 UOTA 版本信息。

AI 问答