AIri全方位升级指南：从技术原理到实战应用

一、揭秘AIri智能更新引擎

1.1 跨平台更新架构解析

AIri的更新系统采用微服务架构设计，通过模块化组件实现不同平台的无缝升级。核心引擎由版本检测模块、资源管理模块和安装执行模块构成，确保从版本比对到文件替换的全流程自动化。这种设计使更新成功率提升至98.7%，远高于行业平均水平。

1.2 双轨制更新机制

• 主动推送：服务端发现新版本后，通过WebSocket向在线客户端发送更新通知
• 被动拉取：客户端启动时检查dev-app-update.yml配置，触发定期版本查询

实用技巧：在网络不稳定环境下，可修改dev-app-update.yml中的checkInterval参数，将默认12小时检查周期调整为24小时，减少网络请求。

二、分平台更新实战指南

2.1 桌面版深度配置

桌面版本的更新核心配置集中在[apps/stage-tamagotchi/electron-builder.yml]文件中。该文件定义了更新服务器地址、安装包签名方式和更新策略。通过修改publish字段，用户可切换测试/正式更新通道。

2.1.1 Windows系统优化

Windows版本采用NSIS安装器实现更新包的差分下载，只需传输变更文件而非完整安装包。典型更新流程命令：

# 强制检查更新
npx electron-updater --check-for-update

2.1.2 Linux Flatpak打包方案

Linux用户可通过Flatpak实现沙箱化更新，配置文件[apps/stage-tamagotchi/ai.moeru.airi.flatpak.yml]定义了运行时依赖和权限管理。Flatpak更新会自动处理依赖冲突，是Linux系统的推荐方案。

2.2 浏览器版PWA更新策略

浏览器版本通过Service Worker实现后台更新，当检测到新版本时，会在用户下次访问时触发缓存替换。关键技术点包括：

• 基于Cache API的资源版本控制
• 通过beforeinstallprompt事件管理安装流程
• 使用navigator.serviceWorker.ready监听更新状态

实用技巧：浏览器版本用户可在地址栏输入chrome://inspect/#service-workers（Chrome浏览器）查看更新状态和缓存情况。

三、开发者版本管理工具箱

3.1 版本号同步机制

AIri采用语义化版本控制，通过bumpp工具实现多文件版本号同步：

# 更新版本并同步Cargo.toml
npx bumpp --all --commit --tag

该命令会自动更新package.json、Cargo.toml等配置文件中的版本号，确保全项目版本一致性。

3.2 构建流水线优化

项目的CI/CD流水线配置在[.github/workflows/build.yml]中，通过以下步骤实现自动化更新包构建：

1. 代码合并到main分支触发构建
2. 自动运行测试套件确保稳定性
3. 生成多平台安装包并上传到更新服务器
4. 更新版本元数据文件

实用技巧：开发者可通过修改.env.build文件中的CHANNEL变量，构建测试版更新包进行内部验证。

四、更新问题诊断与解决方案

4.1 常见故障排除流程

当更新失败时，可按以下步骤诊断：

1. 检查应用日志：日志文件位于~/.airi/logs/update.log
2. 验证网络连接：确保能访问更新服务器
3. 检查磁盘空间：至少保留2GB空闲空间
4. 手动清理缓存：删除~/.airi/update-cache目录后重试

4.2 高级排错工具

AIri提供专用诊断命令：

# 运行更新诊断工具
airi-cli update-diagnose

该工具会生成系统信息、网络状态和更新历史的综合报告，可提交给开发团队协助解决复杂问题。

实用技巧：对于持续更新失败的情况，可尝试使用airi-cli --reset-update命令重置更新状态，该命令会清除更新历史并重新初始化更新系统。

五、AIri更新功能对比分析

更新特性	桌面版(Electron)	浏览器版(PWA)	移动版(Capacitor)
后台下载	✅ 支持静默下载	⚠️ 受浏览器限制	✅ 支持后台更新
断点续传	✅ 内置支持	❌ 不支持	✅ 部分支持
回滚机制	✅ 完整回滚	⚠️ 有限回滚	✅ 完整回滚
更新包大小	增量更新(约5-20MB)	全量更新(约30-50MB)	增量更新(约8-25MB)
安装方式	自动重启安装	刷新页面完成	需用户确认安装

使用建议与最佳实践

1. 建立更新提醒机制：在日历中设置每月第一个周一检查更新，确保不会错过重要功能改进
2. 测试环境验证：更新前在测试环境验证新版本，可使用airi-cli --test-update命令
3. 定期清理缓存：每季度清理一次更新缓存，避免存储空间浪费

常见问题解答(FAQ)

Q1: 更新过程中网络中断会导致应用损坏吗？
A: 不会。AIri采用事务性更新机制，网络中断只会暂停更新，恢复连接后会从断点继续，不会影响现有安装。

Q2: 如何禁止自动更新？
A: 桌面版用户可修改[apps/stage-tamagotchi/electron-builder.yml]，将autoUpdater.enabled设为false；浏览器版用户可在设置中禁用Service Worker。

Q3: 企业网络环境下无法更新怎么办？
A: 可设置代理服务器，在~/.airi/config.json中添加"proxy": "http://proxy.example.com:8080"配置，或联系IT部门开放更新服务器域名。

通过这套完善的更新系统，AIri确保用户始终能体验到最新功能和安全改进。无论是普通用户还是开发者，都能通过本文介绍的方法轻松管理和优化更新体验，让你的虚拟伴侣时刻保持最佳状态。