小米设备令牌提取工具技术指南

1. 理解设备令牌提取的技术价值

设备令牌（Device Token）是实现小米智能设备与第三方平台集成的关键认证凭证。本工具通过小米云服务API接口，自动化完成设备身份信息的提取过程，为智能家居系统集成、自定义设备控制应用开发提供必要的身份验证基础。

2. 环境准备与安装部署

2.1 系统兼容性要求

操作系统	最低配置要求	支持状态
Windows 10/11	64位系统，4GB内存	完全支持
macOS 10.15+	Intel/Apple Silicon架构	完全支持
Linux	kernel 4.15+，Python 3.8+	完全支持

2.2 安装方式选择

2.2.1 Windows平台部署

1. 访问项目发布页面获取最新版token_extractor.exe
2. 保存至本地目录并双击运行
3. 系统可能提示安全警告，选择"更多信息"→"仍要运行"

原理简析：Windows版本采用PyInstaller打包为独立可执行文件，包含所有依赖组件，无需额外配置Python环境。

2.2.2 Linux平台部署

# 一键安装脚本
bash <(curl -L https://gitcode.com/gh_mirrors/xia/Xiaomi-cloud-tokens-extractor/raw/master/run.sh)

原理简析：Bash脚本自动处理依赖安装、权限配置和环境变量设置，适用于大多数Linux发行版。

2.2.3 Docker容器部署

# Docker版本运行
bash <(curl -L https://gitcode.com/gh_mirrors/xia/Xiaomi-cloud-tokens-extractor/raw/master/run_docker.sh)

原理简析：容器化部署隔离系统环境差异，通过预配置镜像确保工具在任何支持Docker的平台上一致运行。

2.2.4 Python手动部署

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/xia/Xiaomi-cloud-tokens-extractor
cd Xiaomi-cloud-tokens-extractor

# 安装依赖包
pip3 install -r requirements.txt

# 运行主程序
python3 token_extractor.py

原理简析：直接使用Python解释器运行源代码，适合开发调试和自定义修改场景。

3. 核心功能与操作流程

3.1 认证机制选择

工具提供两种身份验证方式：

3.1.1 账号密码认证

1. 启动工具后选择"账号密码登录"选项
2. 输入小米账号（支持邮箱、手机号或用户ID）
3. 输入对应密码
4. 选择服务器区域（cn-中国、de-德国、us-美国等）

原理简析：通过小米账号系统API进行身份验证，获取临时访问令牌用于后续设备信息查询。

3.1.2 二维码认证

1. 启动工具后选择"二维码登录"选项
2. 工具将显示二维码图像
3. 使用小米家庭App扫描二维码
4. 在手机端确认登录授权

建议配图：二维码登录界面展示，标注扫码区域和确认步骤

原理简析：基于OAuth 2.0授权流程，通过扫码建立设备信任关系，避免直接输入密码的安全风险。

3.2 设备信息提取过程

1. 完成身份验证后，工具自动连接小米云服务器
2. 读取账号关联的设备列表
3. 解析设备元数据，提取关键信息
4. 生成结构化输出结果

[!WARNING] 每日设备信息请求存在限制（通常为3-5次），频繁请求可能导致临时封禁。

4. 设备兼容性清单

设备类型	支持状态	特殊说明
智能灯泡	完全支持	需固件版本2.0.0以上
扫地机器人	部分支持	仅Roborock系列可提取完整令牌
智能插座	完全支持	所有型号均兼容
空调伴侣	完全支持	需开启云同步功能
BLE温湿度传感器	部分支持	需获取加密密钥
智能门锁	有限支持	仅部分型号提供令牌

5. 跨平台操作差异对比

5.1 命令执行方式

操作场景	Windows	macOS	Linux
启动程序	双击.exe文件	终端执行./token_extractor	终端执行./run.sh
依赖安装	自动包含	需brew install python3	需apt-get install python3
配置文件位置	%APPDATA%\XiaomiTokens	~/Library/Application Support/XiaomiTokens	~/.config/xiaomi-tokens

5.2 常见平台特有问题

• Windows: 可能被 Defender 误报为恶意软件，需在安全中心添加信任
• macOS: 首次运行需在"系统偏好设置→安全性与隐私"中允许执行
• Linux: 无图形界面环境需使用--headless参数运行命令行模式

6. 技术原理与数据流程

6.1 认证流程

1. 客户端向小米账号服务器发送认证请求
2. 服务器返回授权令牌（Access Token）
3. 使用授权令牌请求设备列表API
4. 服务器返回加密的设备信息
5. 客户端解密并提取设备令牌

6.2 数据安全

• 所有网络通信采用TLS 1.3加密
• 本地存储的凭证采用AES-256加密
• 不收集或上传任何用户数据至第三方服务器

7. 常见问题诊断与解决

7.1 认证失败

• 检查账号密码正确性，注意区分大小写
• 确认选择正确的服务器区域
• 如开启两步验证，需在密码后添加验证码

7.2 设备列表为空

[!WARNING] 确保使用小米家庭App关联设备，而非品牌独立App（如Roborock、Yeelight等）

解决步骤：

1. 登录小米家庭App确认设备在线
2. 确认设备已开启云同步功能
3. 尝试在工具中切换服务器区域重新登录

7.3 网络连接错误

• 检查防火墙设置，确保允许工具访问网络
• 禁用VPN或代理后重试
• 尝试修改DNS服务器为公共DNS（如8.8.8.8）

8. 高级应用与扩展开发

获取设备令牌后，可实现以下高级应用：

8.1 Home Assistant集成

将提取的令牌配置到Xiaomi Miio组件，实现设备状态监控和控制。

8.2 自定义控制脚本

基于Python-miio库开发个性化控制逻辑，示例代码：

from miio import Device

device = Device("设备IP", "设备令牌")
device.send("set_power", ["on"])

8.3 数据可视化

通过收集设备状态数据，构建智能家居监控仪表盘，分析设备使用模式。

9. 安全最佳实践

1. 令牌信息应视为敏感数据，避免明文存储
2. 定期（建议每3个月）重新提取令牌以确保有效性
3. 仅在可信环境中运行工具，避免在公共计算机使用
4. 实现令牌轮换机制，降低长期使用同一令牌的安全风险

10. 故障排除与技术支持

如遇到本指南未覆盖的问题，可通过以下方式获取支持：

• 检查工具内置帮助文档（--help参数）
• 查看项目issue跟踪系统获取已知问题解决方案
• 提交详细错误报告至项目维护团队