AIri跨平台部署指南：从零开始的多端适配一站式方案

AIri作为基于LLM驱动的虚拟角色项目，通过跨平台部署技术实现了Web浏览器、桌面端与移动设备的无缝体验。本文将系统讲解如何根据不同使用场景选择最优部署方案，掌握跨平台架构的核心原理，以及通过实用工具和决策指南确保部署成功率，让你的虚拟伙伴随时随地陪伴左右。

场景需求：解析多端部署的核心诉求

需求场景拆解

现代用户对虚拟角色的使用场景呈现多元化特征：办公环境下需要轻量级Web访问，家庭娱乐时依赖桌面端的全功能体验，通勤途中则依赖移动设备的便捷性。AIri的跨平台部署架构正是为满足这些场景而设计，其核心优势在于：

• 场景连贯性：在办公室浏览器中发起的对话，回家后可在桌面端继续
• 功能适配性：根据设备性能动态调整AI模型加载策略
• 资源优化：共享核心数据但针对不同设备优化交互体验

设备兼容性矩阵

设备类型	最低配置要求	推荐部署方式	核心限制
桌面浏览器	现代Chrome/Firefox，4GB内存	Web端直接部署	依赖网络连接，本地存储有限
Windows/macOS	8GB内存，支持WebGL	Electron桌面端	安装包体积较大(约500MB)
iOS/Android	6GB内存，支持PWA	移动端PWA	部分高级特性受浏览器限制
低配置设备	2GB内存，低端处理器	轻量Web模式	禁用3D渲染和本地模型

核心价值：跨平台架构的技术优势

跨平台技术原理

AIri采用"核心逻辑共享+平台特性适配"的混合架构，通过以下技术实现多端统一：

PWA技术栈：通过Web App Manifest实现移动端"安装"体验，核心配置位于[apps/stage-web/public/manifest.json]，包含应用名称、图标和启动方式定义。当用户添加到主屏幕时，系统会读取此文件配置应用行为。

Electron桥接层：桌面端通过[apps/stage-tamagotchi/src/main/bridge.ts]实现Node.js API与前端的通信，例如文件系统访问、系统通知等桌面特有功能。这种架构允许Web技术栈调用底层系统能力，同时保持界面一致性。

图：AIri跨平台通信架构示意图，展示核心服务与各端的交互流程

平台特性对比卡片

特性	Web端	桌面端	移动端PWA
离线功能	基础缓存	完全支持	部分支持
系统集成	limited	完全集成	limited
资源占用	低(约100MB)	中(约500MB)	低(约150MB)
启动速度	快(3-5秒)	中(8-12秒)	快(4-6秒)
3D渲染	WebGPU加速	GPU硬件加速	视设备性能而定

实施路径：分平台部署指南

环境适配指南

在开始部署前，请根据目标平台准备相应环境：

基础环境（所有平台通用）：

git clone https://gitcode.com/GitHub_Trending/ai/airi
cd airi
pnpm i  # 安装项目依赖，需Node.js 18+环境

平台特定依赖：

• 桌面端：需安装Electron构建工具 pnpm add -g electron-builder
• 移动端：需配置HTTPS环境或使用localhost开发服务器
• Web生产环境：建议配置Nginx或Caddy作为静态资源服务器

分平台部署实施

Web端部署（最快体验）

Web端是验证功能的首选方式，部署步骤如下：

# 开发模式启动
pnpm dev:web  # 自动启动Vite开发服务器

核心配置文件：

• 端口与代理设置：[apps/stage-web/vite.config.ts]
• 缓存策略定义：[apps/stage-web/public/_headers]
• 响应式布局控制：[apps/stage-web/src/utils/responsive.ts]

当你需要自定义Web端访问端口时，可修改vite.config.ts中的server.port配置项。开发模式下访问http://localhost:5173即可使用Web版AIri。

桌面端部署（功能完整）

桌面端提供最丰富的功能集，包括系统通知、本地文件管理和高级渲染效果：

# 切换到桌面端项目目录
cd apps/stage-tamagotchi

# 开发模式启动
pnpm dev

# 打包生成可执行文件
pnpm build  # 输出位于dist目录，支持Windows/macOS/Linux

关键配置文件：

• 应用打包配置：[apps/stage-tamagotchi/electron-builder.yml]
• 窗口与渲染设置：[apps/stage-tamagotchi/electron.vite.config.ts]
• 系统集成模块：[packages/electron-vueuse/src/main/window.ts]

如果遇到打包失败，可检查electron-builder.yml中的依赖配置，确保系统已安装必要的构建工具链。

移动端部署（PWA方式）

通过PWA技术将Web应用转化为移动体验：

1. 确保Web服务在本地网络可访问（如http://192.168.1.100:5173）
2. 移动设备浏览器访问该地址
3. 使用浏览器"添加到主屏幕"功能完成安装

核心PWA配置：

• manifest定义：[apps/stage-web/public/manifest.json]
• 离线缓存策略：[apps/stage-web/src/service-worker.ts]
• 触摸优化组件：[apps/stage-web/src/components/TouchOptimized.vue]

当移动设备无法安装PWA时，检查Web服务器是否支持HTTPS或是否在localhost环境下运行，现代浏览器通常限制非安全环境的PWA安装。

拓展应用：性能优化与高级配置

性能优化决策树

根据设备性能和网络环境选择合适的优化策略：

1. 网络状况评估

   • 良好网络（>50Mbps）：启用云端AI模型，本地仅处理UI渲染
   • 中等网络（10-50Mbps）：使用混合模式，核心计算在云端，缓存常见响应
   • 弱网络（<10Mbps）：切换到本地模型，配置文件位于[packages/server-runtime/src/config/local-model.ts]

2. 设备性能适配

   • 高端设备：启用完整3D渲染和实时表情模拟
   • 中端设备：禁用部分粒子效果，降低渲染帧率
   • 低端设备：切换到2D模式，配置文件：[apps/stage-web/src/utils/render-mode.ts]

部署复杂度评估表

部署场景	复杂度	耗时	维护成本	推荐指数
单Web端	★☆☆☆☆	10分钟	低	★★★★★
Web+桌面端	★★★☆☆	30分钟	中	★★★★☆
全平台部署	★★★★☆	1小时	高	★★★☆☆
自定义域名部署	★★☆☆☆	20分钟	中	★★★★☆

多设备同步方案

要实现不同设备间的对话历史和设置同步，可配置分布式存储：

1. 启用数据库同步：修改[packages/memory-pgvector/src/index.ts]配置远程数据库
2. 配置用户认证：实现[apps/server/src/api/auth.ts]中的OAuth集成
3. 测试同步功能：使用pnpm test:sync运行同步测试套件

当同步出现延迟时，检查网络连接或调整[packages/stream-kit/src/queue.ts]中的同步优先级设置。

通过本文介绍的跨平台部署方案，你可以根据实际需求灵活选择部署策略，在不同设备上获得一致且优化的AIri体验。无论是追求极致便捷的Web访问，还是需要完整功能的桌面端，或是随时陪伴的移动体验，AIri的多端架构都能满足你的需求。随着项目的持续发展，未来还将支持AR/VR等更多平台，让虚拟伙伴真正融入你的生活场景。