Onion系统迁移升级全流程指南

准备阶段：系统升级前置准备

确认操作前置条件

1. 设备兼容性验证

   • Miyoo Mini系列掌机需满足硬件版本要求
   • 检查设备电量需高于50%，避免升级中断

2. 数据安全保障

   • 执行游戏内存档(in-game saves)创建操作
   • 备份/Roms、/BIOS和/Saves目录至外部存储

版本适配矩阵

设备型号	支持升级路径	推荐升级方式	最低系统版本要求
Miyoo Mini	v3.9+ → 最新版	手动升级	v3.12.3
Miyoo Mini+	v4.0+ → 最新版	OTA/手动	v4.0.0
Miyoo Mini 2	v4.2+ → 最新版	OTA升级	v4.2.0

风险预判与应对策略

1. 存档兼容性风险

   • 风险：即时存档(save states)可能与新版模拟器不兼容
   • 应对：升级前将所有游戏进度保存为内存档

2. 文件系统损坏风险

   • 风险：SD卡读写错误导致系统文件损坏
   • 应对：使用fsck命令检查SD卡健康状态

   fsck /dev/mmcblk0p1  # 检查SD卡分区完整性
   

3. 电源中断风险

   • 风险：升级过程中设备断电导致变砖
   • 应对：连接外接电源或确保电池满电状态

执行流程：系统升级分步实施

获取升级文件

1. 下载官方升级包

   • 访问项目仓库获取最新稳定版：

   git clone https://gitcode.com/gh_mirrors/on/Onion
   

2. 验证文件完整性

   • 计算并比对SHA256校验值：

   sha256sum Onion-v4.x.x.zip  # 生成校验值
   

   💡 建议：校验值不匹配时重新下载升级包，避免使用损坏文件

3. 解压升级文件

   • Windows系统：右键选择"全部解压缩"
   • Linux/macOS系统：

   unzip Onion-v4.x.x.zip -d Onion-Upgrade  # 解压到指定目录
   

部署系统文件

1. 挂载SD卡

   • 插入SD卡并确认挂载路径：

   mount | grep mmcblk0p1  # 查看挂载点
   

2. 复制系统文件

   • Linux系统执行复制命令：

   cp -rf Onion-Upgrade/* /run/media/mmcblk0p1  # 替换为实际挂载路径
   

   💡 提示：Mac用户需使用"合并"选项处理文件夹冲突

3. 处理版本差异

   • 从v3.9及更早版本升级时：

   rm -rf /run/media/mmcblk0p1/.tmp_update  # 删除旧版本临时文件
   

启动升级程序

1. 安全移除SD卡

   • 执行卸载命令避免数据损坏：

   umount /run/media/mmcblk0p1  # 安全卸载SD卡
   

2. 启动设备升级

   • 将SD卡插入掌机并开机，系统自动进入升级流程
   • 观察屏幕显示的升级进度条，全程约需3-5分钟

图1：Onion系统升级欢迎界面，显示版本更新提示

3. 完成首次启动
   • Miyoo Mini：升级完成后按A键关机再重启
   • Miyoo Mini+：系统将自动重启进入新系统

图2：Onion系统启动LOGO，表明系统升级成功

验证与排障：系统功能确认

系统完整性验证

1. 检查核心目录结构

   • 确认关键文件夹存在且完整：

   /BIOS        # 存放系统BIOS文件
   /Roms        # 游戏ROM目录
   /Saves       # 存档文件位置
   .tmp_update  # 系统临时文件目录（必须保留）
   

2. 验证ROM列表加载

   • 开机后进入游戏菜单
   • 按SELECT键刷新ROM列表，确认游戏正常显示

3. 检查系统版本信息

   • 进入系统设置界面
   • 查看"关于"选项中的版本号是否为最新版

故障排除流程图解

常见问题处理路径：

1. 升级后无法开机 → 检查SD卡是否插好 → 重新制作升级卡（可能文件损坏） → 尝试恢复模式启动（长按SELECT+电源键）

2. 存档丢失 → 检查/Saves目录文件完整性 → 从备份恢复存档文件 → 使用内存档替代即时存档

3. 电量显示异常

图3：低电量状态指示

图4：满电量状态指示

→ 重启设备重新校准电量 → 检查电池接触是否良好 → 升级电池管理组件

系统优化建议

1. 性能调优

   • 进入"系统设置-性能"调整CPU频率
   • 禁用不必要的后台服务

2. 存储管理

   • 定期清理/tmp目录临时文件
   • 使用du命令分析磁盘使用情况：

   du -sh /run/media/mmcblk0p1/*  # 查看各目录占用空间
   

3. 功能探索

   • 体验新增特性：主题切换、网络功能、游戏统计
   • 访问"设置-系统更新"开启自动更新功能

通过以上步骤，您已成功完成Onion系统的迁移升级。新系统将提供更稳定的性能和更丰富的功能体验，建议定期检查更新以获取最新改进。