NAS系统 - ZimaOS模块复用（iframe嵌入）产品需求文档

1. 文档信息

项目	内容
文档版本	v1.0.0
创建日期	2026-03-12
最后更新	2026-03-12
文档状态	草案
负责团队	NAS产品团队
评审人	待确认

2. 背景与目标

2.1 背景

在NAS系统开发过程中，经过技术评估，决定复用成熟的 ZimaOS 能力，通过 iframe 嵌入方式集成以下核心模块：

存储管理
同步备份
应用中心
虚拟机

2.2 目标

降低开发成本：复用成熟模块，避免重复造轮子
缩短交付周期：快速集成经过验证的功能模块
保证功能稳定性：借助ZimaOS的成熟方案，降低技术风险
实现无缝体验：通过iframe嵌入实现与自有系统的视觉和交互统一

2.3 范围界定

模块	复用方式	自有系统职责
存储管理	iframe嵌入ZimaOS	入口集成、权限控制、状态同步
同步备份	iframe嵌入ZimaOS	入口集成、任务监控、告警对接
应用中心	iframe嵌入ZimaOS	入口集成、应用市场扩展、计费对接
虚拟机	iframe嵌入ZimaOS	入口集成、资源配额、网络配置

3. 术语定义

术语	定义
ZimaOS	第三方NAS操作系统，提供存储、应用、虚拟化等核心能力
iframe嵌入	通过HTML iframe标签加载外部页面的技术方案
主系统	自有NAS系统的Web管理界面
嵌入模块	通过iframe加载的ZimaOS功能模块
SSO	Single Sign-On，单点登录
PostMessage	跨域通信的JavaScript API

4. 功能需求

4.1 通用需求（所有模块）

4.1.1 嵌入框架

需求ID	需求描述	优先级
EMB-001	提供统一的iframe容器组件，支持自适应布局	P0
EMB-002	支持全屏/退出全屏模式切换	P1
EMB-003	加载状态提示（loading、错误、超时）	P0
EMB-004	支持面包屑导航与返回主系统	P1

4.1.2 跨域通信

需求ID	需求描述	优先级
COM-001	建立PostMessage双向通信通道	P0
COM-002	消息格式标准化（JSON Schema）	P0
COM-003	消息来源校验（origin白名单）	P0
COM-004	通信超时与重试机制	P1
COM-005	心跳检测机制（保持连接状态）	P1

4.1.3 单点登录（SSO）

需求ID	需求描述	优先级
SSO-001	主系统登录后自动获取ZimaOS访问令牌	P0
SSO-002	Token自动续期机制	P0
SSO-003	Token失效时自动跳转重新授权	P0
SSO-004	支持登出同步（主系统登出→ZimaOS登出）	P1

4.1.4 视觉统一

需求ID	需求描述	优先级
UI-001	iframe加载的页面主题色与主系统一致	P1
UI-002	字体、图标风格协调	P2
UI-003	支持暗黑/明亮模式同步	P1
UI-004	移动端响应式适配	P2

4.2 存储管理模块

4.2.1 功能范围

复用ZimaOS存储管理全部功能：

磁盘管理（查看、格式化、SMART检测）
存储池管理（创建、扩展、删除）
卷管理（创建、扩容、快照）
共享文件夹管理

4.2.2 集成需求

需求ID	需求描述	优先级
STM-001	主系统显示存储概览（容量、健康状态）	P0
STM-002	存储告警信息同步至主系统消息中心	P0
STM-003	支持从主系统一键跳转至存储管理详情	P1
STM-004	存储配额信息实时同步至主系统仪表盘	P1

4.2.3 接口需求

javascript
// 存储状态同步消息
{
  "type": "storage/status",
  "payload": {
    "pools": [...],
    "disks": [...],
    "alerts": [...]
  }
}

4.3 同步备份模块

4.3.1 功能范围

复用ZimaOS同步备份全部功能：

Rsync同步任务
Cloud Sync（云存储同步）
快照备份与恢复
备份计划管理

4.3.2 集成需求

需求ID	需求描述	优先级
BAK-001	主系统显示备份任务概览列表	P0
BAK-002	备份任务状态变更实时通知主系统	P0
BAK-003	备份失败告警对接主系统消息中心	P0
BAK-004	支持在主系统创建/编辑备份任务	P1
BAK-005	备份存储用量统计同步	P1

4.3.3 接口需求

javascript
// 备份任务状态变更
{
  "type": "backup/task_update",
  "payload": {
    "taskId": "xxx",
    "status": "running|completed|failed",
    "progress": 85,
    "message": "..."
  }
}

4.4 应用中心模块

4.4.1 功能范围

复用ZimaOS应用中心全部功能：

应用市场浏览与安装
已安装应用管理
应用配置与更新
容器管理

4.4.2 集成需求

需求ID	需求描述	优先级
APP-001	主系统显示已安装应用快捷入口	P0
APP-002	应用状态（运行/停止/异常）实时同步	P0
APP-003	支持自有应用市场与ZimaOS应用市场融合展示	P1
APP-004	应用安装/卸载事件通知主系统	P1
APP-005	应用资源占用（CPU/内存/网络）数据同步	P2

4.4.3 接口需求

javascript
// 应用状态同步
{
  "type": "app/status",
  "payload": {
    "apps": [
      {
        "id": "app_xxx",
        "name": "Nextcloud",
        "status": "running",
        "resources": {...}
      }
    ]
  }
}

4.5 虚拟机模块

4.5.1 功能范围

复用ZimaOS虚拟机全部功能：

虚拟机创建与配置
虚拟机生命周期管理
虚拟磁盘管理
远程控制台（VNC/SPICE）

4.5.2 集成需求

需求ID	需求描述	优先级
VM-001	主系统显示虚拟机列表与运行状态	P0
VM-002	虚拟机开关机控制可在主系统执行	P0
VM-003	虚拟机资源占用实时监控	P1
VM-004	虚拟机告警（资源不足、故障）同步	P0
VM-005	支持从主系统快速打开虚拟机控制台	P1

4.5.3 接口需求

javascript
// 虚拟机状态变更
{
  "type": "vm/status_change",
  "payload": {
    "vmId": "vm_xxx",
    "name": "Ubuntu-22.04",
    "state": "running|stopped|paused",
    "resources": {
      "cpu": {...},
      "memory": {...}
    }
  }
}

5. 非功能需求

5.1 性能需求

需求ID	需求描述	目标值
PERF-001	iframe首次加载时间	≤ 3秒
PERF-002	PostMessage响应延迟	≤ 100ms
PERF-003	状态同步频率	≤ 5秒
PERF-004	内存占用增长控制	每iframe ≤ 50MB

5.2 安全需求

需求ID	需求描述	优先级
SEC-001	iframe sandbox属性配置	P0
SEC-002	Content-Security-Policy设置	P0
SEC-003	通信消息签名验证	P1
SEC-004	Token存储安全（HttpOnly/Secure）	P0
SEC-005	操作审计日志记录	P1

5.3 兼容性需求

需求ID	需求描述	优先级
CMP-001	支持Chrome/Firefox/Safari/Edge最新2个版本	P0
CMP-002	支持移动端浏览器访问	P1
CMP-003	ZimaOS版本兼容（当前及前2个版本）	P0

5.4 可靠性需求

需求ID	需求描述	优先级
REL-001	iframe加载失败自动重试（3次）	P0
REL-002	ZimaOS服务不可用时优雅降级	P0
REL-003	通信中断自动恢复机制	P1

6. 技术方案

6.1 架构设计


┌─────────────────────────────────────────────────────────────┐
│                    NAS主系统 Web UI                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   导航菜单   │  │  仪表盘概览  │  │    iframe容器       │  │
│  │             │  │             │  │  ┌───────────────┐  │  │
│  │ • 存储管理   │  │ • 存储状态   │  │  │  ZimaOS页面   │  │  │
│  │ • 同步备份   │  │ • 备份任务   │  │  │               │  │  │
│  │ • 应用中心   │  │ • 应用列表   │  │  │ • 存储管理    │  │  │
│  │ • 虚拟机    │  │ • 虚拟机状态  │  │  │ • 同步备份    │  │  │
│  └─────────────┘  │             │  │  │ • 应用中心    │  │  │
│                   └─────────────┘  │  │ • 虚拟机      │  │  │
│                                    │  └───────────────┘  │  │
│                                    └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │ PostMessage
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        ZimaOS后端                            │
│              (API Gateway + 各模块服务)                       │
└─────────────────────────────────────────────────────────────┘

6.2 iframe配置规范

html
<iframe
  id="zimaos-frame"
  src="https://zimaos.local/{module}?token={jwt}"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
  allow="fullscreen; clipboard-read; clipboard-write"
  referrerpolicy="strict-origin-when-cross-origin"
></iframe>

6.3 通信协议

消息格式标准

typescript
interface IFrameMessage {
  // 消息唯一标识
  id: string;
  // 消息类型
  type: string;
  // 消息来源
  source: 'nas-main' | 'zimaos';
  // 时间戳
  timestamp: number;
  // 消息体
  payload: Record<string, any>;
}

消息类型清单

类型	方向	说明
`auth/token`	主→ZimaOS	传递认证令牌
`auth/refresh`	双向	Token刷新
`nav/route`	主→ZimaOS	页面路由跳转
`nav/close`	ZimaOS→主	请求关闭iframe
`storage/status`	ZimaOS→主	存储状态同步
`backup/task_update`	ZimaOS→主	备份任务更新
`app/status`	ZimaOS→主	应用状态同步
`vm/status_change`	ZimaOS→主	虚拟机状态变更
`theme/mode`	双向	主题模式切换
`system/heartbeat`	双向	心跳检测
`system/error`	双向	错误通知

7. 接口清单

7.1 ZimaOS提供接口

接口	方法	说明
`/api/v1/auth/sso`	POST	SSO令牌换取
`/api/v1/auth/refresh`	POST	Token刷新
`/api/v1/auth/verify`	GET	Token验证
`/api/v1/storage/overview`	GET	存储概览
`/api/v1/backup/tasks`	GET	备份任务列表
`/api/v1/apps/installed`	GET	已安装应用
`/api/v1/vms/list`	GET	虚拟机列表

7.2 主系统需实现接口

接口	方法	说明
`/api/v1/zimaos/callback`	POST	ZimaOS回调通知
`/api/v1/zimaos/events`	POST	事件接收端点

8. 页面设计

8.1 嵌入页面布局


┌────────────────────────────────────────────────────────────┐
│  NAS Logo    首页    存储    备份    应用    虚拟机   [用户]  │  ← 主导航
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ┌────────────────────────────────────────────────────┐   │
│  │  [面包屑: 首页 > 存储管理]           [全屏] [刷新]   │   │  ← 操作栏
│  ├────────────────────────────────────────────────────┤   │
│  │                                                    │   │
│  │                                                    │   │
│  │              iframe - ZimaOS 存储管理               │   │  ← 嵌入区域
│  │                                                    │   │
│  │                                                    │   │
│  │                                                    │   │
│  └────────────────────────────────────────────────────┘   │
│                                                            │
└────────────────────────────────────────────────────────────┘

8.2 交互流程

场景1：从主系统进入存储管理


用户点击"存储管理"菜单
       │
       ▼
主系统请求SSO Token
       │
       ▼
iframe加载 ZimaOS存储管理页
       │
       ▼
建立PostMessage连接
       │
       ▼
双向状态同步启动

场景2：存储告警通知


ZimaOS检测到磁盘故障
       │
       ▼
PostMessage发送告警
       │
       ▼
主系统接收并在消息中心显示
       │
       ▼
主系统仪表盘状态更新

9. 验收标准

9.1 功能验收

验收项	验收标准
iframe加载	4个模块均能正常加载，无跨域错误
SSO登录	主系统登录后无需再次登录即可访问ZimaOS功能
状态同步	存储/备份/应用/虚拟机状态5秒内同步到主系统
主题同步	主系统切换主题后，iframe内页面同步切换
错误处理	ZimaOS服务异常时显示友好提示，不影响主系统

9.2 性能验收

验收项	验收标准
首屏加载	各模块首屏加载时间 ≤ 3秒
内存占用	单个iframe内存增长 ≤ 50MB
通信延迟	PostMessage往返延迟 ≤ 100ms

9.3 安全验收

验收项	验收标准
跨域安全	仅允许指定origin访问，其他来源拒绝
Token安全	Token通过安全通道传递，支持自动过期
XSS防护	iframe sandbox配置正确，无XSS漏洞

10. 风险与应对

风险	影响	应对措施
ZimaOS API变更	高	约定API版本兼容策略，建立变更通知机制
跨域问题	中	提前验证CORS配置，准备fallback方案
性能瓶颈	中	实施懒加载，优化通信频率
用户体验割裂	中	加强视觉统一，减少iframe感知
安全漏洞	高	严格sandbox配置，定期安全审计

11. 里程碑规划

阶段	时间	交付物
Phase 1	第1-2周	基础框架（iframe容器、PostMessage通信、SSO）
Phase 2	第3-4周	存储管理模块集成
Phase 3	第5-6周	同步备份模块集成
Phase 4	第7-8周	应用中心模块集成
Phase 5	第9-10周	虚拟机模块集成
Phase 6	第11-12周	整体测试、优化、上线

12. 附录

12.1 ZimaOS API文档引用

12.2 参考实现

javascript
// iframe加载管理器示例
class ZimaOSEmbedManager {
  constructor(containerId, baseUrl) {
    this.container = document.getElementById(containerId);
    this.baseUrl = baseUrl;
    this.frame = null;
    this.messageHandlers = new Map();
  }

  async load(module, token) {
    const url = `${this.baseUrl}/${module}?token=${token}`;
    this.frame = document.createElement('iframe');
    this.frame.src = url;
    this.frame.sandbox = 'allow-scripts allow-same-origin allow-forms';
    this.container.appendChild(this.frame);
    this._setupMessageListener();
  }

  _setupMessageListener() {
    window.addEventListener('message', (event) => {
      if (event.origin !== this.baseUrl) return;
      const { type, payload } = event.data;
      this._handleMessage(type, payload);
    });
  }
}

12.3 变更记录

版本	日期	变更内容	作者
v1.0.0	2026-03-12	初始版本	-

文档结束

目录

NAS系统 - ZimaOS模块复用（iframe嵌入）产品需求文档

1. 文档信息

2. 背景与目标

2.1 背景

2.2 目标

2.3 范围界定

3. 术语定义

4. 功能需求

4.1 通用需求（所有模块）

4.1.1 嵌入框架

4.1.2 跨域通信

4.1.3 单点登录（SSO）

4.1.4 视觉统一

4.2 存储管理模块

4.2.1 功能范围

4.2.2 集成需求

4.2.3 接口需求

4.3 同步备份模块

4.3.1 功能范围

4.3.2 集成需求

4.3.3 接口需求

4.4 应用中心模块

4.4.1 功能范围

4.4.2 集成需求

4.4.3 接口需求

4.5 虚拟机模块

4.5.1 功能范围

4.5.2 集成需求

4.5.3 接口需求

5. 非功能需求

5.1 性能需求

5.2 安全需求

5.3 兼容性需求

5.4 可靠性需求

6. 技术方案

6.1 架构设计

6.2 iframe配置规范

6.3 通信协议

消息格式标准

消息类型清单

7. 接口清单

7.1 ZimaOS提供接口

7.2 主系统需实现接口

8. 页面设计

8.1 嵌入页面布局

8.2 交互流程

场景1：从主系统进入存储管理

场景2：存储告警通知

9. 验收标准

9.1 功能验收

9.2 性能验收

9.3 安全验收

10. 风险与应对

11. 里程碑规划

12. 附录

12.1 ZimaOS API文档引用

12.2 参考实现

12.3 变更记录