ryOS - 现代化基于 Web 的桌面环境

2026-06-19T21:29:15.902362

ryOS - 现代化基于 Web 的桌面环境

一款受经典 macOS 与 Windows 启发、基于 React、TypeScript 和 AI 构建的现代化 Web 桌面环境。内置多款应用、熟悉的桌面界面以及系统级 AI 助手，支持桌面、平板和移动端。

阅读 ryOS 文档 — 架构、API 参考和开发者指南

特性

仿真的 macOS 和 Windows 风格桌面交互
支持拖拽、缩放和最小化的多实例窗口管理器
可自定义壁纸（图片、图案或视频）
系统音效与 AI 助手（Ryo）
基于本地存储持久化的虚拟文件系统，支持备份/恢复

主题

System 7 — 经典 Mac OS 外观，顶部菜单栏和信号灯控件
Aqua — Mac OS X 风格，现代美学
Windows XP — 底部任务栏、开始菜单和经典窗口控件
Windows 98 — 复古 Windows 体验，适配移动端控件

内置应用

Finder — 文件管理器，支持快速访问、存储信息与智能文件识别
TextEdit — 富文本编辑器，支持 Markdown、斜杠命令和多窗口
MacPaint — 位图图形编辑器，包含绘图工具、图案和导入/导出
Videos — VCR 风格的 YouTube 播放器，支持播放列表管理
Soundboard — 录制和播放自定义音效，带波形可视化
Synth — 虚拟合成器，支持多种波形、效果和 MIDI
Photo Booth — 相机应用，带实时滤镜和相册
Internet Explorer — 时光机，通过 Wayback Machine 探索网页历史；AI 生成 1996 年之前或未来的站点
Chats — 与 Ryo 的 AI 聊天，公共/私人聊天室，语音消息和工具调用
Control Panels — 系统偏好设置：外观、声音、备份/恢复和文件系统管理
Minesweeper — 经典扫雷游戏
Virtual PC — DOS 模拟器，运行经典游戏（Doom、SimCity 等）
Infinite Mac — 经典 Mac OS 模拟器（System 1.0 到 Mac OS X 10.4），基于 Infinite Mac
Terminal — Unix 风格命令行界面，集成 AI（ryo）
iPod — 第一代 iPod 音乐播放器，支持 YouTube 导入、歌词和翻译
Karaoke — 同步歌词播放器，全屏显示模式
Ryo TV — CRT 风格频道浏览，AI 生成频道内容
Winamp — 经典 Winamp 媒体播放器
Calendar — iCal 风格事件、待办事项和同步
Contacts — 通讯录，支持 vCard 导入和同步
Dashboard — Tiger 风格小部件：天气、股票、翻译、词典、水族馆等
Maps — Apple MapKit 地点搜索，集成聊天
Admin — 受限的分析与系统管理
Applet Store — 浏览、安装和分享社区创建的 HTML 小程序
Stickies — 便签，用于快速备忘

如何使用

从 Finder、桌面或 Apple/开始菜单启动应用
拖动窗口移动，拖动边缘调整大小
使用 Control Panels 自定义外观和音效
与 Ryo AI 聊天获取帮助或控制应用
文件自动保存到浏览器存储

项目结构

├── api/             # API 路由处理（兼容 Vercel 的无服务器函数）
├── electron/        # Electron 外壳、菜单、预加载和更新器
├── public/          # 静态资源（图标、壁纸、音效、字体）
├── scripts/         # 构建、维护和独立 API 运行器
├── tests/           # Bun 测试套件
├── src/
│   ├── api/         # 前端 API 客户端
│   ├── apps/        # 应用模块
│   ├── components/  # 共享 React 组件（UI、对话框、布局）
│   ├── config/      # 配置文件
│   ├── hooks/       # 自定义 React Hooks
│   ├── lib/         # 库和工具函数
│   ├── services/    # VFS 和实时服务外观
│   ├── shared/      # 共享协定和领域类型
│   ├── stores/      # Zustand 状态管理
│   ├── styles/      # CSS 与样式
│   ├── sync/        # Cloud Sync v2 客户端引擎
│   ├── themes/      # OS 主题定义
│   ├── types/       # TypeScript 类型定义
│   ├── utils/       # 工具函数
│   └── workers/     # Web Workers

技术栈

前端：React 19, TypeScript, Tailwind CSS v4, shadcn/ui, Motion
音频：Tone.js, WaveSurfer.js
3D：Three.js（着色器）
文本编辑器：TipTap
状态管理：Zustand
存储：IndexedDB, LocalStorage, Redis（Upstash REST 或 REDIS_URL）
AI：OpenAI, Anthropic, Google（通过 Vercel AI SDK）
实时通信：Pusher 或本地 WebSocket
API 运行时：Vercel Node 处理程序 + 独立 Bun 服务器
构建：Vite, Bun
桌面端：Electron + electron-updater
部署：Vercel, Docker/GHCR + Coolify, Electron 桌面发布

开发命令

bun run dev          # 启动全栈（API + 带代理的 Vite）—— 默认
bun run dev:vite     # 仅启动 Vite 开发服务器（仅前端，无 API）
bun run dev:api      # 仅启动独立 Bun API 服务器（端口 3000）
bun run build        # 构建生产版本
bun run start        # 启动自托管/Coolify 生产服务器
bun run lint         # 运行 ESLint
bun run preview      # 预览生产构建
bun run api:start    # 以生产模式运行独立 API 服务器
bun run electron:dev # 打包并启动 Electron 外壳，连接本地 Vite
bun run electron:build # 使用 electron-builder 构建桌面安装包

本地开发时，bun run dev 会同时启动独立 Bun API 服务器和带 /api 代理的 Vite 开发服务器 — 无需 Vercel CLI。

当只需要 API 服务器时（例如运行测试），使用：

# 终端 1 —— 独立 API（加载 .env/.env.local）
bun run dev:api

# 终端 2 —— 前端（如果需要 UI 则可选）
bun run dev:vite

独立 API 监听端口：
- API_PORT（回退：PORT，然后 3000）
- API_HOST（回退：0.0.0.0）

可以直接针对它运行 API 测试：

API_URL=http://localhost:3000 bun run test:new-api

测试

单元测试和集成测试使用 Bun 原生运行器：

bun run test:unit   # 无需服务器的单元/连接测试
bun run test:api    # API 集成测试；需要先运行 `bun run dev:api`

自托管与生产部署

ryOS 现在支持单个 Bun 生产服务器，用于自托管和 Coolify 等容器平台。该服务器负责：
- /api/*
- dist/ 中的静态前端资源
- SPA 深层链接
- doc 的整洁 URL
- 可选的本地 WebSocket 实时通信

bun install
bun run build
APP_PUBLIC_ORIGIN="https://your-domain.com" \
API_ALLOWED_ORIGINS="https://your-domain.com" \
bun run start

Redis 配置

使用以下任一方式：

# 标准 Redis / Valkey / 自托管 Redis
REDIS_URL="redis://default:password@redis:6379/0"

或者：

# Upstash REST（现有 Vercel 风格路径）
REDIS_KV_REST_API_URL="https://..."
REDIS_KV_REST_API_TOKEN="..."

实时通信配置

使用以下任一方式：

# 现有 Pusher 路径
REALTIME_PROVIDER="pusher"
PUSHER_APP_ID="..."
PUSHER_KEY="..."
PUSHER_SECRET="..."
PUSHER_CLUSTER="us3"

或者：

# 本地 WebSocket 路径（最好配合 REDIS_URL）
REALTIME_PROVIDER="local"
REALTIME_WS_PATH="/ws"

详细运行手册：docs/1.3-self-hosting-vps.md

CI/CD

拉取请求运行 bun run test:unit 和 bun run build。
推送到 main 分支时构建并发布 GHCR 镜像，用于 Coolify 部署。
v* 标签会构建带更新源的 macOS 和 Windows 签名 Electron 发布包。

许可证

AGPL-3.0 — 详见 LICENSE。

欢迎贡献！请提交 Pull Request。

查看原文