设备激活流程 v2

概述

当前流程是虾哥设备认证v2版本，目前最新固件已经存在，但本项目还未移植

激活流程

每个设备都有一个唯一的序列号(Serial Number)和HMAC密钥(HMAC Key)，用于身份验证和安全通信。新设备首次使用时需要通过以下流程进行激活：

客户端启动时，向服务器发送设备信息，包括序列号、MAC地址和客户端ID
服务器检查设备是否已激活：
- 如果已激活，客户端正常工作
- 如果未激活，服务器返回包含验证码和Challenge的激活请求
客户端显示验证码，提示用户前往xiaozhi.me网站输入验证码
客户端使用HMAC密钥对Challenge进行签名，并发送给服务器验证
客户端通过轮询方式等待服务器确认验证结果：
- 如果验证成功，设备激活完成
- 如果验证失败或超时，设备激活失败

┌────────────┐                      ┌────────────┐                      ┌────────────┐
│            │                      │            │                      │            │
│  设备客户端  │                      │   服务器    │                      │  用户浏览器  │
│            │                      │            │                      │            │
└─────┬──────┘                      └─────┬──────┘                      └─────┬──────┘
      │                                   │                                   │
      │  请求设备状态 (MAC, ClientID, SN)   │                                   │
      │ ────────────────────────────────> │                                   │
      │                                   │                                   │
      │  返回激活请求 (验证码, Challenge)    │                                   │
      │ <──────────────────────────────── │                                   │
      │                                   │                                   │
      │ 显示验证码                          │                                   │
      │ ┌─────────────┐                   │                                   │
      │ │请前往网站输入 │                   │                                   │
      │ │验证码: 123456│                   │                                   │
      │ └─────────────┘                   │                                   │
      │                                   │                                   │
      │                                   │          用户访问xiaozhi.me        │
      │                                   │ <─────────────────────────────────│
      │                                   │                                   │
      │                                   │          输入验证码 123456          │
      │                                   │ <─────────────────────────────────│
      │                                   │                                   │
      │ 计算HMAC签名                        │                                   │
      │ ┌─────────────┐                   │                                   │
      │ │ HMAC(密钥,   │                   │                                   │
      │ │  Challenge) │                   │                                   │
      │ └─────────────┘                   │                                   │
      │                                   │                                   │
      │  发送激活请求 (SN, Challenge, 签名)  │                                   │
      │ ────────────────────────────────> │                                   │
      │                                   │  ┌───────────────┐                │
      │                                   │  │ 等待用户输入验证码 │                │
      │                                   │  │ 超时返回202    │                │
      │                                   │  └───────────────┘                │
      │                                   │                                   │
      │  轮询等待 (HTTP Long Polling)       │                                   │
      │ ────────────────────────────────> │                                   │
      │  HTTP 202 (Pending)               │                                   │
      │ <──────────────────────────────── │                                   │
      │                                   │                                   │
      │  继续轮询...                        │                                   │
      │ ────────────────────────────────> │                                   │
      │                                   │                                   │
      │                                   │          验证码验证成功             │
      │                                   │───────────────────────────────────│
      │                                   │                                   │
      │  激活成功 (HTTP 200)                │                                   │
      │ <──────────────────────────────── │                                   │
      │                                   │                                   │
      │ ┌─────────────┐                   │                                   │
      │ │设备激活成功！ │                   │                                   │
      │ └─────────────┘                   │                                   │
      │                                   │                                   │

安全机制

设备激活流程v2版本采用以下安全机制：

设备唯一标识：每个设备有一个唯一的序列号(Serial Number)
HMAC签名验证：使用HMAC-SHA256算法对Challenge进行签名，确保设备身份的真实性
验证码验证：通过要求用户在网页端输入验证码，防止自动化的激活攻击
轮询等待机制：使用HTTP Long Polling等待服务器验证结果，适应各种网络环境

配置说明

相关配置项在config.json中的SYSTEM_OPTIONS部分：

json

"SYSTEM_OPTIONS": {
  "CLIENT_ID": "a45f36c9-c855-4deb-ac46-6847997c29a2",
  "DEVICE_ID": "54:1f:8d:e0:7b:91",
  "SERIAL_NUMBER": "",
  "HMAC_KEY": "",
  "ACTIVATED": false,
  ...
}

SERIAL_NUMBER: 设备唯一序列号，如果为空则自动生成
HMAC_KEY: HMAC签名密钥，如果为空则自动生成
ACTIVATED: 设备激活状态，激活成功后设置为true

开发者说明

设备激活相关代码实现：

src/utils/device_activation.py: 设备激活管理类，负责序列号和HMAC密钥管理、签名计算和激活流程
src/application.py中的_check_device_activation()和_handle_activation_result()方法处理设备激活流程

如需在其他平台上实现兼容的激活流程，需要遵循相同的协议和安全机制。

常见问题

设备激活失败怎么办？
- 检查网络连接是否正常
- 确保验证码输入正确且未过期
- 重启设备重新尝试激活
如何手动设置序列号和HMAC密钥？
- 可以在config.json中直接设置SERIAL_NUMBER和HMAC_KEY
- 也可以在config/serial_number.txt和config/hmac_key.txt中手动设置
激活过的设备需要重新激活吗？
- 正常情况下，设备激活成功后不需要重新激活
- 如果设备配置被重置或ACTIVATED被设为false，则需要重新激活

设备激活流程 v2 ​

概述 ​

激活流程 ​

安全机制 ​

配置说明 ​

开发者说明 ​