AIri跨平台部署指南：实现Web/桌面/移动全终端覆盖

AIri作为基于LLM驱动的虚拟角色项目，通过跨平台部署架构实现了从浏览器到移动设备的全场景覆盖。本文将从开发者视角，系统讲解如何通过轻量化Web部署、功能增强的桌面端部署以及便携扩展的移动端方案，构建无缝衔接的多终端体验，同时提供自动化部署工具与性能优化策略，帮助开发者快速实现全平台覆盖。

一、价值定位：多端部署架构解析

1.1 跨平台技术栈选型

AIri采用Web技术栈为核心，通过"一次开发、多端适配"的架构设计，在保证功能一致性的同时显著降低维护成本。技术栈主要包含：

• 前端框架：Vue.js + Vite构建系统
• 桌面端容器：Electron提供系统级API访问
• 移动端方案：PWA技术实现接近原生的体验
• 后端服务：Node.js + TypeScript提供统一接口层

这种架构选择使项目在资源占用（Web端<50MB，桌面端<200MB）与功能完整性之间取得平衡，同时通过WebAssembly技术将计算密集型任务（如Live2D渲染）的性能损耗控制在15%以内。

1.2 多终端协同优势

全平台部署为AIri带来三大核心价值：

• 场景覆盖：办公室（Web）→ 家庭娱乐（桌面端）→ 外出通勤（移动端）的无缝切换
• 功能分层：根据设备性能提供差异化功能集（如桌面端支持GPU加速渲染，移动端侧重低功耗模式）
• 数据同步：通过统一后端实现跨设备状态保持，支持对话历史、角色设置的实时同步

二、环境准备：开发环境校验与配置

2.1 系统需求与依赖管理

部署AIri前需确保环境满足以下要求：

• 操作系统：Windows 10+、macOS 12+或Linux（Ubuntu 20.04+）
• 开发工具链：Git、Node.js 18.18.0+、pnpm 8.6.0+
• 硬件建议：至少4GB RAM，桌面端部署推荐8GB以上以支持流畅的3D渲染

核心依赖定义在项目根目录的package.json中，通过工作区配置实现多包管理：

{
  "workspaces": [
    "apps/*",
    "packages/*",
    "services/*",
    "plugins/*"
  ],
  "engines": {
    "node": ">=18.18.0",
    "pnpm": ">=8.6.0"
  }
}

2.2 项目资源获取与初始化

通过Git克隆项目并安装基础依赖：

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/ai/airi.git
cd airi

# 安装项目依赖（使用pnpm工作区特性）
pnpm install

# 验证环境配置
pnpm run check:env

环境验证脚本会检查Node.js版本、依赖完整性及必要系统工具（如Electron构建工具链），输出类似以下结果表示环境就绪：

[√] Node.js version: 18.18.2 (required: >=18.18.0)
[√] pnpm version: 8.14.0 (required: >=8.6.0)
[√] Electron build tools detected
[√] WASM compilation environment ready

三、平台适配：从轻量化到全功能部署

3.1 Web端：轻量化即时体验

Web端作为零安装门槛的入口，适合快速体验与初步功能验证。其架构基于Vite构建的单页应用，核心配置位于apps/stage-web/vite.config.ts。

部署步骤：

# 启动开发服务器（默认端口5173）
pnpm dev:web

# 生产环境构建
pnpm build:web

# 构建产物位于 apps/stage-web/dist/
# 可通过任何静态服务器部署，如：
cd apps/stage-web/dist
npx serve -p 8080

关键配置参数说明：

// apps/stage-web/vite.config.ts 核心配置
export default defineConfig({
  server: {
    port: 5173,          // 开发端口
    host: true,          // 允许局域网访问（便于移动设备测试）
    proxy: {             // API代理配置
      '/api': {
        target: 'http://localhost:3000',
        rewrite: path => path.replace(/^\/api/, '')
      }
    }
  },
  build: {
    target: 'es2020',    // 浏览器兼容性目标
    assetsInlineLimit: 4096, // 内联资源大小限制
    rollupOptions: {
      output: {
        manualChunks: {   // 代码分割策略
          vendor: ['vue', 'pinia', 'vue-router']
        }
      }
    }
  }
})

Web端部署架构特点：

• 资源占用：首次加载约2.3MB（gzip压缩后），缓存后二次加载<500KB
• 渲染策略：采用按需加载组件，首屏渲染时间<2秒（现代浏览器）
• 离线支持：通过ServiceWorker实现基础离线功能，缓存关键静态资源

3.2 桌面端：功能增强的本地应用

Electron桌面端提供比Web版更丰富的系统集成能力，包括本地文件系统访问、系统通知、全局快捷键等高级特性。核心配置文件为apps/stage-tamagotchi/electron-builder.yml。

部署步骤：

# 进入桌面端项目目录
cd apps/stage-tamagotchi

# 安装依赖（桌面端特有依赖）
pnpm install

# 开发模式启动（带热重载）
pnpm dev

# 打包生成可执行文件（按当前系统自动选择目标平台）
pnpm build

打包配置关键参数：

# apps/stage-tamagotchi/electron-builder.yml
appId: moeru.airi.stage-tamagotchi
productName: AIri
copyright: Copyright © 2023 AIri Project
directories:
  output: dist/
files:
  - '!**/*.md'
  - '!node_modules/**/*'
  - 'dist/**/*'
asar: true  # 资源打包为asar格式，提高安全性
win:
  target:
    - nsis  # Windows安装包
    - portable  # 便携版
mac:
  target: dmg
linux:
  target:
    - AppImage
    - deb

桌面端性能优化建议：

• 启用硬件加速：在electron.vite.config.ts中设置app.commandLine.appendSwitch('enable-gpu-rasterization')
• 内存管理：通过app.on('browser-window-created', window => window.webContents.session.clearCache())定期清理缓存
• 后台进程控制：使用electron-store保存窗口状态，避免重复创建进程

3.3 移动端：PWA便携扩展方案

移动端通过PWA技术实现"安装即应用"的体验，支持添加到主屏幕、离线运行和推送通知。核心配置文件为apps/stage-web/public/manifest.json。

部署步骤：

1. 完成Web端部署并确保服务可被移动设备访问
2. 配置HTTPS（生产环境）或使用localhost（开发环境）
3. 在移动设备浏览器中访问Web服务地址
4. 通过浏览器菜单将应用添加到主屏幕

PWA关键配置：

{
  "name": "AIri",
  "short_name": "AIri",
  "description": "LLM powered virtual character",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#41b883",
  "icons": [
    {
      "src": "web-app-manifest-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "web-app-manifest-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

移动端优化策略：

• 响应式布局：通过apps/stage-web/src/components/ResponsiveContainer.vue实现设备适配
• 触摸优化：在src/utils/touch-handler.ts中实现手势识别与触摸反馈
• 性能控制：根据设备性能动态调整渲染质量，低端设备自动降低动画帧率

四、验证优化：部署效率与问题处理

4.1 部署效率工具链

项目提供自动化部署脚本，位于scripts/目录下，支持多平台批量部署：

全平台一键部署脚本

# 运行全平台部署脚本
pnpm run deploy:all

# 脚本路径：scripts/deploy-all.ts
# 功能：依次构建Web端、桌面端和移动资源，并生成部署报告

配置同步方案

通过packages/stage-shared/src/env-vars.ts实现跨平台配置同步：

// 共享配置示例
export const AppConfig = {
  apiBaseUrl: import.meta.env.VITE_API_URL || 'https://api.airi.example.com',
  syncInterval: 30000, // 数据同步间隔（30秒）
  cacheSizeLimit: 50 * 1024 * 1024, // 缓存上限50MB
  enableAnalytics: true
}

使用pnpm run sync:config命令可将配置同步到所有平台项目中，确保各端行为一致性。

4.2 场景化故障处理

启动失败场景

案例1：Electron启动白屏

• 症状：桌面端启动后显示空白窗口，控制台无报错
• 排查：检查electron.vite.config.ts中的main入口配置
• 解决方案：

  # 清除Electron缓存
  rm -rf node_modules/.vite-electron
  # 重新安装依赖
  pnpm install
  

案例2：Web端API请求404

• 症状：Web界面加载正常，但功能无法使用，控制台显示API 404
• 排查：检查Vite代理配置和后端服务状态
• 解决方案：

  # 确保后端服务已启动
  pnpm dev:server
  # 检查代理配置是否正确
  cat apps/stage-web/vite.config.ts | grep proxy
  

性能瓶颈场景

案例1：桌面端高CPU占用

• 症状：应用运行时CPU占用持续超过80%
• 排查：使用Chrome DevTools的Performance面板分析渲染瓶颈
• 解决方案：

  // 在src/renderer/utils/performance.ts中添加
  export function optimizeRendering() {
    // 降低非活跃窗口渲染频率
    if (!window.isActive) {
      app.config.globalProperties.$setRenderRate(15)
    }
  }
  

案例2：移动端加载缓慢

• 症状：PWA首次加载时间超过10秒
• 排查：通过Lighthouse分析资源加载情况
• 解决方案：

  # 生成优化后的资源
  pnpm run build:web -- --mode production
  # 启用资源预加载
  echo "Link: </assets/main.js>; rel=preload; as=script" >> apps/stage-web/dist/_headers
  

数据同步场景

案例：多设备数据不同步

• 症状：Web端与桌面端对话历史不一致
• 排查：检查packages/memory-pgvector/src/index.ts中的同步逻辑
• 解决方案：

  // 调整同步策略
  export const syncConfig = {
    enableRealTimeSync: true,
    conflictResolution: 'server_wins', // 冲突时以服务器数据为准
    batchSize: 50 // 批量同步大小
  }
  

4.3 边缘设备部署扩展

AIri支持在树莓派等嵌入式设备部署，需进行以下优化：

树莓派部署步骤：

# 安装ARM架构依赖
pnpm install --arch=armhf

# 构建轻量级版本（禁用3D渲染）
pnpm build:web -- --define ENABLE_3D=false

# 使用轻量级服务器运行
cd apps/stage-web/dist
npx serve -l 80

资源限制优化技巧：

1. 模型优化：使用量化版模型models/llm/quantized/，减少内存占用
2. 渲染降级：在src/utils/render-utils.ts中设置disableWebGL: true
3. 服务裁剪：通过packages/server-runtime/src/config.ts禁用非必要服务

五、总结与延伸

通过本文介绍的部署方案，开发者可实现AIri在Web、桌面和移动设备的全平台覆盖。这种架构设计不仅保证了用户体验的连续性，也展示了Web技术栈在跨平台开发中的强大能力。项目后续将重点优化边缘设备支持和AR功能，进一步扩展应用场景。

开发者可通过docs/content/zh-Hans/docs/目录下的官方文档获取更多技术细节，或参与crates/tauri-plugin-mcp/等插件开发，为多平台支持贡献力量。