NanoMDM 设备注册迁移指南：3 步用 nano2nano 换存储后端、搬 MDM 服务器，不重新注册
【免费下载链接】audacityAudio Editor项目地址: https://gitcode.com/GitHub_Trending/au/audacity
先说结论：在 NanoMDM 里做设备注册迁移，靠的是官方的 nano2nano 命令行工具加目标端的/migration端点，三步走完，设备不用重新注册。MDM（移动设备管理）场景下，设备注册是指设备向服务器声明身份并交换推送令牌的过程，之后设备才能持续受管。问题出在换存储后端或搬 MDM 服务器的时候：比如注册数据还留在 file 文件后端，你想升级到 mysql；或者服务器换了机器、重装了系统，不想让几十上百台设备再走一遍注册流程。
nano2nano 能做什么，不能做什么
nano2nano 从旧存储读出每台设备的注册报文，按固定顺序逐条发给目标 NanoMDM 的/migration端点，由目标端用常规的 MDM check-in（即设备与服务器的"报到"交互）处理逻辑重建注册记录。它做不到两件事：不搬历史命令和库存数据，也不能替你改设备侧的服务器指向。目标服务器上的迁移端点默认关闭，必须显式开启并提供 API Key，这一点决定了两边怎么配合。
迁移前检查清单
动手之前，先逐项确认，任何一条不满足都会让迁移白跑：
服务器 URL 完全一致：
源与目标的 MDM 服务器 URL 必须完全一致（协议、域名、端口、路径都要相同）。MDM 协议把服务器 URL 绑定在设备证书里，URL 一变设备就不认新服务器，这是硬限制，没有变通办法。
目标端开
-migration且配了-api，两个参数缺一不可，否则/migration端点不存在。旧存储完整备份：注册迁移是有损的，出问题要能回滚。
第 1 步：目标服务器开启迁移端点
先在新服务器上配好存储（例如 mysql，按schema.sql建表），然后带两个参数启动：
nanomdm -api <APIKey> -migration -ca ca.pem \ -storage mysql -storage-dsn <dsn>启用后，/migration路径上会注册一个 check-in 处理器。它走 API Basic 认证（用户名固定nanomdm，密码就是 API Key），但不校验设备证书——因为请求是迁移工具发的，不是真设备。
第 2 步：从 file 切到 mysql 的完整迁移命令
工具以只读方式打开旧存储，读出各设备的注册报文并发送。两类核心报文：Authenticate是设备注册时声明身份与通道的报文，TokenUpdate是更新 APNs 推送令牌的报文（推送令牌决定服务器能否主动唤醒设备）。顺序很敏感：设备通道的TokenUpdate必须紧跟Authenticate，用户通道又在设备通道之后，所以工具故意用单线程串行发送，不并发：
nano2nano -storage file -storage-dsn db \ -url http://127.0.0.1:9000/migration \ -key <APIKey> -debug跑完后核对日志，每台设备应依次出现两条 info：
checkin=Authenticate device_id=99385AF6-... type=Device checkin=TokenUpdate device_id=99385AF6-... type=Device如果源是multi类型存储，注意它只用第一个后端参与迁移。
第 3 步：确认无误后切换流量
确认日志无报错、设备数量对得上，再把设备的目标服务器切到新后端实例，并用新存储重启。由于两边 URL 一致，设备不重新注册就能继续受管。旧服务器可先留着做回滚兜底。
nano2nano 参数速查
| 参数 | 说明 |
|---|---|
-storage | 源存储后端：file、mysql、pgsql等，与主程序语法一致 |
-storage-dsn | 源后端数据源名称（目录路径或连接串） |
-storage-options | 后端选项，部分后端需要（file 需enable_deprecated=1） |
-url | 目标迁移端点，如http://127.0.0.1:9000/migration |
-key | 目标服务器 API Key，用于 Basic 认证 |
-debug | 输出调试日志，排障时建议常开 |
-version | 打印版本后退出 |
参数与发送逻辑的完整实现在cmd/nano2nano/main.go，各存储后端的读取实现在storage/kv/migrate.go、storage/mysql/migrate.go、storage/pgsql/migrate.go。
结果验证：日志怎么读
- ✅ 成功：每台设备依次出现
Authenticate+TokenUpdate，全程无 error 级别输出，设备数与源存储一致。 - ❌ 失败：出现
sending to migration endpoint加错误信息。按状态码定位——401 查-key；404 查-url是否打到/migration；连接超时就查网络与端口。
迁移会丢什么：注册迁移是有损的
- ✅ 会搬：设备身份（
Authenticate）、推送令牌（TokenUpdate，含设备与用户两条通道）、可选的SetBootstrapToken。 - ❌ 不搬：历史命令与响应记录、库存（inventory）数据。
- ⚠️ 边缘风险：iOS 的解锁令牌（unlock token）。如果设备最后一次
TokenUpdate没带上注册时的 unlock token，迁移后这份信息就找不回来了——这也是迁移前必须备份旧存储的原因。
排障：现象 → 原因 → 处理
| 现象 | 原因 | 处理 |
|---|---|---|
| 请求返回 401 | -key与目标-api不一致 | 两边值对齐后再跑 |
| 设备重新注册或连不上新服务器 | 源与目标 URL 不一致 | 硬性前提，URL 必须完全一致；迁到不同 URL 的服务器不支持 |
| multi 后端迁移结果不符预期 | multi 只用第一个后端迁移 | 确认第一个后端就是你要迁的那份 |
| 迁移期间担心影响在线设备 | 担心工具写坏旧存储 | 工具只读旧存储，旧服务器可继续运行到切换完成 |
总结与扩展资源
整套 MDM 迁移的本质，是把注册报文按序重放给新服务器。所以顺序永远是：目标端先开迁移端点，再跑 nano2nano 核对日志，最后切流量，设备侧零改动。三件事别忘：URL 一致、端点开启、旧存储备份。
想深入可以继续看：
docs/operations-guide.md：各后端配置与 nano2nano 的完整参数说明；test/e2e/migrate.go：端到端迁移测试，迁移流程的活文档；Makefile：交叉编译 nano2nano，覆盖 darwin/linux/windows 的 amd64/arm64/arm，如make nano2nano-linux-amd64。
【免费下载链接】audacityAudio Editor项目地址: https://gitcode.com/GitHub_Trending/au/audacity
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
