AIri全平台部署技术指南：从环境到体验的完整实现方案

2026-03-30 11:33:18作者：段琳惟

💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.

项目地址：https://gitcode.com/GitHub_Trending/ai/airi

在数字化生活中，我们常面临一个挑战：如何让喜爱的AI虚拟角色突破设备限制，实现跨平台无缝互动？无论是在办公室的Web浏览器、家中的桌面应用，还是通勤时的移动设备，用户都期望获得一致且流畅的体验。本文将通过"问题-方案-验证-拓展"的四象限框架，为你提供一套完整的AIri多平台部署解决方案，让虚拟伙伴真正实现"无处不在"。

环境准备：部署前的必要检查

如何确保部署过程顺利进行？环境准备是基础。就像建造房屋需要稳固的地基，AIri的部署也需要合适的软硬件环境支持。

系统环境要求

AIri作为一款跨平台应用，对运行环境有基本要求。以下是官方推荐的配置方案：

配置类型	最低配置	推荐配置
处理器	双核CPU	四核及以上
内存	4GB RAM	8GB RAM
存储	4GB可用空间	10GB可用空间
网络	稳定宽带连接	50Mbps以上
操作系统	Windows 10/macOS 11/Linux Kernel 5.4	Windows 11/macOS 12/Linux Kernel 5.15

必备工具安装

部署AIri需要以下开发工具，建议提前安装并配置好环境变量：

Node.js：JavaScript运行环境，推荐v18.0.0及以上版本
pnpm：高效的包管理器，用于依赖安装和项目构建
Git：版本控制工具，用于获取项目源码

安装命令示例（以Ubuntu系统为例）：

# 安装Node.js (使用nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
nvm install 18
nvm use 18

# 安装pnpm
npm install -g pnpm

# 安装Git
sudo apt update && sudo apt install git -y

项目资源概览

AIri项目采用模块化结构设计，各平台代码分离但共享核心逻辑。关键目录说明：

Web端：apps/stage-web/ - 基于Vue.js和Vite构建的浏览器应用
桌面端：apps/stage-tamagotchi/ - 基于Electron的跨平台桌面应用
移动端：通过PWA技术实现，核心配置位于apps/stage-web/public/

核心功能部署：构建基础服务

成功部署的核心是什么？答案是先搭建好基础服务。这一步将获取项目源码并启动核心服务，为后续多端适配奠定基础。

获取项目源码

首先需要将AIri项目完整代码下载到本地。项目源码托管在Git仓库中，使用Git命令克隆：

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

安装项目依赖

AIri使用pnpm作为包管理器，并采用monorepo项目结构管理多个子包。在项目根目录执行以下命令安装所有依赖：

# 安装项目所有依赖
pnpm install

# 检查依赖安装状态
pnpm list

⚠️ 注意：依赖安装过程可能需要5-15分钟，具体时间取决于网络速度和硬件配置。如遇依赖安装失败，可尝试删除node_modules目录和pnpm-lock.yaml文件后重新安装。

启动核心服务

AIri的核心服务包含API服务器和Web应用。在开发模式下启动服务：

# 启动Web应用和API服务
pnpm dev:web

服务启动成功后，控制台会显示访问地址，通常为http://localhost:5173。此时打开浏览器访问该地址，应能看到AIri的Web界面。

多端适配：实现跨平台体验

如何让AIri在不同设备上都能提供优质体验？多端适配是关键。本节将分别介绍Web、桌面和移动三个平台的部署方法，实现全场景覆盖。

Web浏览器部署：最快体验途径

Web端是体验AIri的最便捷方式，无需安装额外软件，通过现代浏览器即可访问。

构建生产版本

# 在项目根目录执行构建命令
pnpm build:web

部署到Web服务器 将构建生成的dist目录（位于apps/stage-web/下）部署到Nginx、Apache或其他Web服务器。以Nginx为例，配置示例：

server {
  listen 80;
  server_name airi.example.com;
  root /path/to/airi/apps/stage-web/dist;
  index index.html;
  
  # 支持SPA路由
  location / {
    try_files $uri $uri/ /index.html;
  }
}

访问应用 打开浏览器访问配置的域名或服务器IP，即可使用AIri Web版。

部署效果预览：Web版提供完整的交互界面，支持角色对话、表情展示和基础互动功能，界面响应式设计可适配从手机到桌面的各种屏幕尺寸。

桌面端部署：功能完整解决方案

桌面端提供比Web版更丰富的功能，如系统通知、本地文件访问和硬件加速渲染。

切换到桌面端项目目录
```
cd apps/stage-tamagotchi
```
安装桌面端依赖
```
pnpm install
```

构建桌面应用

# 开发模式运行
pnpm dev

# 构建生产版本
pnpm build

构建完成后，可执行文件将生成在dist目录下，根据操作系统不同，会生成相应格式的安装包或可执行文件。

配置入口：apps/stage-tamagotchi/electron-builder.yml - 可在此自定义应用名称、图标、窗口大小等参数。

部署效果预览：桌面版提供独立窗口运行环境，支持系统托盘集成、全局快捷键和更高性能的渲染效果，适合长时间交互使用。

移动端部署：PWA渐进式体验

如何在没有原生应用的情况下实现接近原生的移动体验？PWA（渐进式Web应用）技术是理想选择。

确保Web服务支持HTTPS PWA需要在HTTPS环境下运行（localhost除外）。可通过Let's Encrypt等服务获取免费SSL证书。
在移动设备上访问Web服务 用手机浏览器访问已部署的Web服务地址，确保与服务器在同一网络环境。
添加到主屏幕
- iOS (Safari)：点击分享按钮 → "添加到主屏幕"
- Android (Chrome)：点击菜单按钮 → "安装应用"

核心原理：PWA通过apps/stage-web/public/manifest.json配置文件实现应用化体验，包括离线缓存、全屏显示和桌面图标等功能。

部署效果预览：移动版提供触控优化界面，支持离线使用和推送通知，在手机主屏幕上创建图标后，使用体验接近原生应用。

体验优化：从可用到优质

基础部署完成后，如何进一步提升各平台的使用体验？体验优化是关键环节，涉及性能调优、数据同步和安全加固等方面。

跨平台兼容性对比

不同平台各有特点，了解其差异有助于针对性优化：

功能特性	Web版	桌面版	移动版(PWA)
离线运行	❌ 不支持	✅ 完全支持	⚠️ 部分支持
系统通知	⚠️ 需要授权	✅ 完全支持	⚠️ 需要授权
本地存储	⚠️ 有限制	✅ 无限制	⚠️ 有限制
硬件加速	⚠️ 浏览器限制	✅ 完全支持	⚠️ 设备限制
资源占用	低	中	低
启动速度	快	中	快

性能调优建议

根据不同平台特点，可采取以下优化措施：

Web端优化：

启用HTTP缓存：配置apps/stage-web/public/_headers设置适当的缓存策略
图片优化：使用AVIF格式图片，位于apps/stage-web/src/assets/
代码分割：通过Vite配置实现按需加载，配置文件：apps/stage-web/vite.config.ts

桌面端优化：

硬件加速：在electron-builder.yml中启用GPU加速
内存管理：优化渲染进程内存占用，配置入口：apps/stage-tamagotchi/src/main/

移动版优化：

资源压缩：减小PWA包体积，配置Service Worker缓存策略
触控优化：调整UI元素大小适应触摸操作，源码位于apps/stage-web/src/components/

数据同步实现

如何确保不同设备间的对话历史和设置同步？AIri提供两种同步方案：

基础版：使用浏览器本地存储

优点：简单无需额外配置
缺点：仅在单设备生效
实现路径：packages/stage-shared/src/export-csv.ts - 支持手动导出/导入数据

进阶版：配置数据库同步

优点：多设备实时同步
实现路径：修改packages/memory-pgvector/src/index.ts配置外部数据库

部署验证与问题排查

部署完成后如何确认各平台功能正常？有效的验证和排查流程能帮助快速定位问题。

功能验证清单

各平台部署完成后，建议按以下清单验证核心功能：

Web端验证：

✅ 页面加载完成无控制台错误
✅ 角色对话功能正常响应
✅ 表情动画显示正常
✅ 响应式布局适配不同屏幕尺寸

桌面端验证：

✅ 应用启动无错误提示
✅ 系统通知功能正常
✅ 窗口大小调整和最小化/最大化正常
✅ 本地文件访问功能可用（如有）

移动版验证：

✅ 成功添加到主屏幕
✅ 离线状态下可打开应用
✅ 触摸操作响应流畅
✅ 横屏/竖屏切换布局正常

常见部署陷阱及解决方案

问题现象	可能原因	解决方案
Web端白屏	依赖未安装完整	重新执行`pnpm install`
桌面端构建失败	Node.js版本不兼容	确保使用Node.js 18+版本
移动版无法添加到主屏幕	非HTTPS环境	配置SSL证书或使用localhost测试
启动后无响应	端口被占用	修改配置文件中的端口号
角色模型加载失败	资源文件缺失	检查网络连接，重新构建项目

部署后安全检查

为确保部署安全，建议完成以下检查：

环境变量安全 检查是否有敏感信息硬编码在配置文件中，特别是API密钥和数据库凭证。配置文件位置：packages/server-runtime/src/config.ts
权限配置审核 桌面端应用默认权限是否合理，可在electron.vite.config.ts中调整权限设置。
依赖安全扫描 执行pnpm audit检查依赖包安全漏洞，及时更新存在安全问题的依赖。