# NAS存储管理模块技术架构文档 v2.0

## 1. 架构设计

```mermaid
graph TD
    A[用户浏览器] --> B[React前端应用]
    B --> C[Redux状态管理]
    B --> D[Ant Design组件库]
    B --> E[API服务层]
    E --> F[NAS管理后端]
    F --> G[存储设备API]
    F --> H[系统监控服务]
    
    subgraph "前端层"
        B
        C
        D
    end
    
    subgraph "服务层"
        E
        F
    end
    
    subgraph "设备层"
        G
        H
    end
```

## 2. 技术栈描述

### 2.1 前端技术
- **框架**：React 18 + TypeScript 5
- **状态管理**：Redux Toolkit 1.9
- **UI组件**：Ant Design 5.x
- **构建工具**：Vite 4.x
- **初始化工具**：vite-init
- **路由**：React Router 6
- **HTTP客户端**：Axios 1.x

### 2.2 开发工具
- **代码规范**：ESLint + Prettier + Husky
- **测试框架**：Jest + React Testing Library
- **Mock工具**：MSW (Mock Service Worker)
- **国际化**：i18next

## 3. 路由定义

| 路由路径 | 页面组件 | 功能描述 |
|----------|----------|----------|
| /storage | StorageDashboard | 存储概览页面，显示总体统计 |
| /storage/disks | DiskManagement | 盘位管理，硬盘列表和状态 |
| /storage/pools | PoolManagement | 存储池列表和管理 |
| /storage/pools/create | PoolCreateWizard | RAID创建向导 |
| /storage/pools/:id | PoolDetail | 存储池详情页面 |
| /storage/monitoring | CapacityMonitoring | 容量监控和告警设置 |

## 4. API接口定义

### 4.1 硬盘管理接口

#### 获取硬盘列表
```
GET /api/storage/disks
```

请求参数：
| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| size | number | 否 | 每页数量，默认20 |
| status | string | 否 | 过滤状态：healthy/warning/error |

响应示例：
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 8,
    "items": [
      {
        "disk_id": "disk_001",
        "model": "ST4000VN008",
        "capacity": 4000787030016,
        "health_status": "healthy",
        "smart_status": "passed",
        "temperature": 42,
        "power_on_hours": 8760,
        "pool_id": "pool_001",
        "filesystem": "ext4"
      }
    ]
  }
}
```

#### 获取硬盘S.M.A.R.T信息
```
GET /api/storage/disks/{disk_id}/smart
```

### 4.2 存储池管理接口

#### 创建存储池
```
POST /api/storage/pools
```

请求体：
```json
{
  "pool_name": "数据存储池",
  "raid_level": "raid5",
  "disk_ids": ["disk_001", "disk_002", "disk_003"],
  "stripe_size": 64
}
```

#### 扩展存储池
```
POST /api/storage/pools/{pool_id}/expand
```

### 4.3 容量监控接口

#### 获取容量统计
```
GET /api/storage/capacity
```

#### 设置告警规则
```
POST /api/storage/alerts/rules
```

## 5. 数据模型设计

### 5.1 实体关系图

```mermaid
erDiagram
    DISK ||--o{ POOL : belongs_to
    POOL ||--o{ VOLUME : contains
    POOL ||--o{ ALERT : triggers
    
    DISK {
        string disk_id PK
        string model
        bigint capacity
        string health_status
        string smart_status
        int temperature
        int power_on_hours
        string pool_id FK
        timestamp created_at
    }
    
    POOL {
        string pool_id PK
        string pool_name
        string raid_level
        bigint total_capacity
        bigint used_capacity
        string status
        timestamp created_at
        timestamp updated_at
    }
    
    VOLUME {
        string volume_id PK
        string pool_id FK
        string volume_name
        bigint capacity
        string filesystem
        string mount_point
    }
    
    ALERT {
        string alert_id PK
        string pool_id FK
        string alert_type
        string severity
        decimal threshold
        boolean is_enabled
        timestamp created_at
    }
```

### 5.2 数据库表结构

#### 硬盘表 (disks)
```sql
CREATE TABLE disks (
    disk_id VARCHAR(50) PRIMARY KEY,
    model VARCHAR(100) NOT NULL,
    capacity BIGINT NOT NULL,
    health_status VARCHAR(20) DEFAULT 'healthy',
    smart_status VARCHAR(20) DEFAULT 'unknown',
    temperature INTEGER DEFAULT 0,
    power_on_hours INTEGER DEFAULT 0,
    pool_id VARCHAR(50),
    filesystem VARCHAR(20),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_disks_pool_id ON disks(pool_id);
CREATE INDEX idx_disks_health ON disks(health_status);
```

#### 存储池表 (storage_pools)
```sql
CREATE TABLE storage_pools (
    pool_id VARCHAR(50) PRIMARY KEY,
    pool_name VARCHAR(100) NOT NULL UNIQUE,
    raid_level VARCHAR(20) NOT NULL,
    total_capacity BIGINT NOT NULL,
    used_capacity BIGINT DEFAULT 0,
    status VARCHAR(20) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## 6. 前端架构设计

### 6.1 目录结构
```
src/
├── features/
│   └── nas/
│       ├── components/          # 组件
│       │   ├── DiskCard/
│       │   ├── PoolList/
│       │   ├── RaidWizard/
│       │   └── CapacityChart/
│       ├── hooks/              # 自定义Hook
│       │   ├── useDiskStatus.ts
│       │   ├── usePoolActions.ts
│       │   └── useCapacityAlert.ts
│       ├── services/           # API服务
│       │   ├── diskService.ts
│       │   ├── poolService.ts
│       │   └── monitorService.ts
│       ├── types/              # TypeScript类型
│       │   ├── disk.types.ts
│       │   ├── pool.types.ts
│       │   └── api.types.ts
│       └── store/              # Redux Store
│           ├── diskSlice.ts
│           ├── poolSlice.ts
│           └── index.ts
├── shared/
│   ├── components/             # 通用组件
│   ├── utils/                  # 工具函数
│   └── constants/              # 常量定义
└── app/
    ├── App.tsx
    └── store.ts
```

### 6.2 状态管理架构
```mermaid
graph TD
    A[React Components] --> B[Redux Store]
    B --> C[diskSlice]
    B --> D[poolSlice]
    B --> E[alertSlice]
    
    C --> F[Disk API]
    D --> G[Pool API]
    E --> H[Monitor API]
    
    F --> I[Backend Service]
    G --> I
    H --> I
```

## 7. 性能优化策略

### 7.1 前端优化
- **代码分割**：按路由和特性进行代码分割
- **懒加载**：组件和路由级别的懒加载
- **缓存策略**：API响应缓存，减少重复请求
- **虚拟滚动**：大数据列表使用虚拟滚动

### 7.2 接口优化
- **分页加载**：列表数据分页获取
- **增量更新**：状态变化使用增量更新而非全量刷新
- **WebSocket**：实时状态推送，减少轮询

## 8. 安全设计

### 8.1 认证授权
- **JWT认证**：使用JWT Token进行身份验证
- **RBAC权限**：基于角色的访问控制
- **路由守卫**：前端路由级别权限验证

### 8.2 数据安全
- **输入验证**：前端表单输入验证和过滤
- **XSS防护**：React默认XSS防护，额外配置CSP
- **敏感信息**：敏感数据前端脱敏显示

## 9. 测试策略

### 9.1 单元测试
- **覆盖率目标**：≥80%
- **测试工具**：Jest + React Testing Library
- **测试范围**：组件、Hook、工具函数、Reducer

### 9.2 集成测试
- **API Mock**：使用MSW模拟后端接口
- **测试用例**：覆盖正常流程、异常流程、边界条件
- **性能测试**：关键路径性能基准测试

### 9.3 测试用例示例
```typescript
// 硬盘状态组件测试
describe('DiskCard Component', () => {
  it('should display disk information correctly', () => {
    const disk = {
      disk_id: 'disk_001',
      model: 'ST4000VN008',
      capacity: 4000787030016,
      health_status: 'healthy'
    };
    
    render(<DiskCard disk={disk} />);
    
    expect(screen.getByText('ST4000VN008')).toBeInTheDocument();
    expect(screen.getByText('4.0 TB')).toBeInTheDocument();
    expect(screen.getByText('健康')).toBeInTheDocument();
  });
});
```

## 10. 部署与监控

### 10.1 构建部署
- **构建命令**：`npm run build`
- **输出目录**：`dist/`
- **部署方式**：静态文件部署到GitHub Pages

### 10.2 监控指标
- **性能监控**：LCP、FID、CLS指标收集
- **错误监控**：JS错误、API错误统计
- **用户行为**：页面访问、功能使用统计

### 10.3 运维支持
- **日志收集**：前端错误日志上传
- **健康检查**：定期心跳检测
- **版本管理**：支持版本回滚和灰度发布

NAS存储管理技术架构文档_v2

NAS帮助中心页面原型级线框说明

NAS帮助中心产品需求文档(PRD)

NAS帮助中心竞品分析报告-群晖威联通绿联飞牛极空间

# NAS帮助中心功能框架思维导图

> 整理依据：`NAS帮助中心产品需求文档(PRD).md`、`软件需求规划.md`、`NAS帮助中心页面原型级线框说明.md`、`NAS帮助中心产品竞品分析.md`

## 功能框架思维导图

```mermaid
mindmap
  root((NAS帮助中心))
    产品定位
      统一支持门户
      知识中心
      服务中台入口
      基础闭环
        搜索自助
        文章解决
        人工支持升级
    目标用户
      NAS新手用户
      家庭用户
      技术爱好者
      小型企业管理员
      内容运营与客服
    前台功能
      帮助中心首页
        全局搜索框
        热门问题
        新手任务卡片
        问题排障入口
        联系支持入口
        支持资源入口
        重要公告
      统一搜索
        搜索入口
          首页
          搜索结果页
          文章详情页
          排障页面
        搜索对象
          知识文章
          FAQ
          排障专题
          公告内容
          支持资源
        筛选维度
          内容类型
          问题类型
          系统版本
          产品型号
        无结果兜底
          关键词建议
          热门问题推荐
          联系支持入口
      知识文章
        结构化模板
          标题
          摘要
          适用产品
          适用系统版本
          内容类型
          问题类型
          前置条件
          操作步骤
          风险提示
          相关资源
          更新时间
        页面能力
          适用范围前置展示
          相关推荐
          文章反馈
          未解决引导支持
      新手入门
        任务导向
        首期专题
          第一次安装与初始化
          创建存储池或卷
          创建共享文件夹
          添加用户与权限
          配置远程访问
          设置备份
        专题信息
          预计耗时
          操作难度
          风险提示
          分步骤导航
      问题排障
        症状导向
        首期症状
          无法访问NAS
          硬盘未识别或RAID异常
          空间不足
          性能过慢
          备份失败
          系统升级失败
          权限异常
        专题结构
          症状说明
          可能原因
          快速检查项
          修复步骤
          风险提示
          何时联系客服
        高风险规则
          格式化
          重置
          重建RAID
          恢复数据
      联系支持
        问题主题选择
        相关文章推荐
        工单入口
        支持说明
        上下文透传
          搜索关键词
          已读文章ID
          设备型号
          系统版本
          错误码
          问题主题
      支持资源聚合
        下载中心
        兼容性说明
        安全公告
        服务状态
    后台运营
      文章管理
        新建文章
        编辑文章
        发布文章
        下线文章
        草稿管理
      分类标签管理
        内容分类
        问题类型标签
        系统版本标签
        适用产品
        标签复用与规范
      推荐位配置
        首页热门问题
        新手任务卡片
        专题入口
        首页公告
        排序与上下线时间
      内容关联
        相关文章
        相关下载
        相关公告
        相关资源
      基础数据
        搜索词
        无结果词
        结果点击
        文章浏览
        阅读深度
        是否解决反馈
        工单转化
    页面范围
      前台页面
        帮助中心首页
        搜索结果页
        知识文章详情页
        新手入门专区页
        新手任务专题页
        排障中心页
        排障专题页
        联系支持页
        支持资源聚合页
        通用空状态
      后台页面
        文章管理列表页
        文章编辑页
        分类标签管理页
        首页推荐位配置页
    关键规则
      搜索优先
      新手按任务组织
      排障按症状组织
      文章必须声明适用范围
      高风险操作必须强提示
      自助失败必须可升级支持
      前台展示必须后台可配置
      首期克制不做复杂AI
    版本规划
      V1.0基础闭环
        首页与统一导航
        搜索结果页
        结构化知识文章
        新手入门专区
        排障中心
        联系支持
        内容后台基础能力
        基础数据埋点
      V1.1支持门户增强
        支持资源聚合
        搜索联想
        错误码归档
        更多筛选
        内容效果看板
      V1.2运营与国际化
        内容关联增强
        多语言结构
        资源半自动关联
      V2.0智能支持
        AI搜索
        智能问答
        设备个性化推荐
        故障诊断向导
```

## 主干框架说明

帮助中心的核心不是单纯文章库，而是围绕 NAS 用户问题解决建立的统一支持门户。前台承接用户的四类高频意图：搜索问题、新手学习、故障排障、联系人工支持；后台承接内容生产、标签维护、首页推荐和数据复盘。

首期 V1.0 应优先做通基础闭环：用户进入首页后可通过搜索、新手任务或排障症状进入结构化文章；文章明确适用产品和系统版本，并在未解决时推荐相关内容或进入联系支持；联系支持页再把搜索词、已读文章、设备型号、系统版本、错误码等上下文传给工单系统，减少重复沟通。

后续版本再逐步增强支持资源聚合、搜索联想、错误码归档、内容效果看板、多语言和 AI 搜索，不建议首期就追求大而全。



NAS存储管理模块技术架构文档 v2.0

1. 架构设计

NAS帮助中心页面原型级线框说明

文档信息

NAS帮助中心产品需求文档（PRD）

NAS 帮助中心竞品分析报告：群晖 / 威联通 / 绿联 / 飞牛 / 极空间

NAS帮助中心功能框架思维导图