LaLaWatch
NAS存储管理模块技术架构文档
编辑
2024-01-15
undefined
00
请注意，本文编写于 947 天前，最后修改于 148 天前，其中某些信息可能已经过时。

目录

NAS存储管理模块技术架构文档
📋 文档信息
📑 版本历史
📖 目录
1. 概述
1.1 文档目的
1.2 项目背景
1.3 术语定义
2. 架构设计
2.1 系统架构图
2.2 架构分层说明
3. 技术栈选型
3.1 前端技术栈
3.2 开发工具链
3.3 技术选型理由
为什么选择 React 18 + TypeScript？
为什么选择 Redux Toolkit？
为什么选择 Ant Design 5？
4. 路由设计
4.1 路由映射表
4.2 路由配置示例
5. API接口规范
5.1 通用规范
5.1.1 请求规范
5.1.2 响应规范
5.2 错误码定义
5.3 硬盘管理接口
5.3.1 获取硬盘列表
5.3.2 获取硬盘详情
5.3.3 获取硬盘S.M.A.R.T信息
5.4 存储池管理接口
5.4.1 创建存储池
5.4.2 扩展存储池
5.4.3 删除存储池
5.5 容量监控接口
5.5.1 获取容量统计
5.5.2 设置告警规则
6. 数据模型设计
6.1 实体关系图
6.2 数据库表结构
6.2.1 硬盘表 (disks)
6.2.2 存储池表 (storage_pools)
6.2.3 告警规则表 (alert_rules)
7. 前端架构设计
7.1 目录结构
7.2 状态管理架构
8. 性能优化策略
8.1 前端优化
8.2 接口优化
9. 安全设计
9.1 认证授权
9.2 数据安全
10. 测试策略
10.1 测试金字塔
10.2 测试用例示例
11. 部署与运维
11.1 构建部署
11.2 监控指标
12. 附录
12.1 参考文档

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

📋 文档信息

项目内容
文档版本v2.1
编写日期2024-01-15
最后更新2026-03-24
文档状态评审中
编写人员架构组

📑 版本历史

版本日期修改人修改内容
v1.02023-12-01架构组初始版本，基础架构设计
v2.02024-01-15架构组完善API定义，添加性能优化策略
v2.12026-03-24架构组优化文档结构，补充错误码规范

📖 目录

1. 概述

1.1 文档目的

本文档旨在定义NAS（网络附加存储）存储管理模块的技术架构，为开发团队提供清晰的技术指引，确保系统设计的一致性、可维护性和可扩展性。

1.2 项目背景

NAS存储管理模块是企业级存储解决方案的核心组件，提供以下核心能力：

  • 硬盘管理：监控硬盘健康状态、S.M.A.R.T信息、温度等
  • 存储池管理：支持RAID 0/1/5/6/10等多种RAID级别的创建和管理
  • 容量监控：实时展示存储使用情况，支持告警配置
  • 性能优化：数据分层、缓存管理、I/O优化

1.3 术语定义

术语英文全称说明
NASNetwork Attached Storage网络附加存储，通过网络提供文件级数据存储服务
RAIDRedundant Array of Independent Disks独立磁盘冗余阵列，提供数据冗余和性能提升
S.M.A.R.TSelf-Monitoring Analysis and Reporting Technology硬盘自我监测、分析与报告技术
存储池Storage Pool由多个物理硬盘组成的逻辑存储单元
LUNLogical Unit Number逻辑单元号，用于标识存储设备

2. 架构设计

2.1 系统架构图

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

    subgraph 前端层 Frontend
        direction TB
        B
        C
        D
    end

    subgraph 服务层 Service
        direction TB
        E
        F
    end

    subgraph 设备层 Device
        direction TB
        G
        H
        I
    end

    style 前端层 fill:#e1f5fe
    style 服务层 fill:#f3e5f5
    style 设备层 fill:#e8f5e9

2.2 架构分层说明

层级职责技术组件
前端层用户界面渲染、状态管理、交互逻辑React 18、Redux Toolkit、Ant Design 5
服务层API网关、业务逻辑处理、数据校验RESTful API、JWT认证、中间件
设备层硬件设备交互、系统监控、告警推送设备驱动、WebSocket、消息队列

3. 技术栈选型

3.1 前端技术栈

类别技术/工具版本用途说明
框架React18.x核心UI框架，支持并发特性
语言TypeScript5.x静态类型检查，提升代码质量
状态管理Redux Toolkit1.9.x全局状态管理，简化Redux配置
UI组件Ant Design5.x企业级UI组件库
构建工具Vite4.x快速构建，支持HMR热更新
路由React Router6.x单页应用路由管理
HTTP客户端Axios1.xHTTP请求库，支持拦截器
样式方案CSS Modules + Less-组件级样式隔离

3.2 开发工具链

类别工具版本配置说明
代码规范ESLint + Prettier8.x / 3.xAirbnb规则集，统一代码风格
Git钩子Husky + lint-staged8.x提交前自动格式化
单元测试Jest + React Testing Library29.x / 14.x组件和Hook测试
E2E测试Playwright1.x端到端自动化测试
Mock工具MSW1.xMock Service Worker，API模拟
国际化i18next23.x多语言支持
API文档Swagger/OpenAPI3.0接口文档自动生成

3.3 技术选型理由

为什么选择 React 18 + TypeScript？

  1. 并发渲染：React 18的并发特性提升复杂界面响应速度
  2. 类型安全：TypeScript在编译期捕获类型错误，减少运行时bug
  3. 生态成熟：丰富的第三方库支持，活跃的社区

为什么选择 Redux Toolkit？

  1. 配置简化：减少样板代码，内置Immer实现不可变更新
  2. 开发体验：内置Redux DevTools集成，方便调试
  3. 中间件支持：内置thunk，支持异步逻辑

为什么选择 Ant Design 5？

  1. 企业级设计：符合B端产品设计规范
  2. 组件丰富：提供表格、表单、图表等复杂组件
  3. 主题定制：支持Design Token，便于品牌定制

4. 路由设计

4.1 路由映射表

路由路径页面组件权限要求功能描述
/storageStorageDashboarduser存储概览页面，显示总体统计信息
/storage/disksDiskManagementuser盘位管理，硬盘列表和状态监控
/storage/disks/:idDiskDetailuser硬盘详情页，显示S.M.A.R.T信息
/storage/poolsPoolManagementuser存储池列表和管理
/storage/pools/createPoolCreateWizardadminRAID创建向导（分步表单）
/storage/pools/:idPoolDetailuser存储池详情页面
/storage/pools/:id/editPoolEditadmin存储池编辑页面
/storage/monitoringCapacityMonitoringuser容量监控和趋势分析
/storage/alertsAlertSettingsadmin告警规则配置

4.2 路由配置示例

typescript
// src/app/routes.tsx
export const storageRoutes: RouteObject[] = [
  {
    path: '/storage',
    element: <StorageLayout />,
    children: [
      { index: true, element: <StorageDashboard /> },
      { path: 'disks', element: <DiskManagement /> },
      { path: 'disks/:id', element: <DiskDetail /> },
      {
        path: 'pools',
        element: <PoolManagement />,
        children: [
          { path: 'create', element: <PoolCreateWizard /> },
          { path: ':id', element: <PoolDetail /> },
          { path: ':id/edit', element: <PoolEdit /> },
        ],
      },
      { path: 'monitoring', element: <CapacityMonitoring /> },
      { path: 'alerts', element: <AlertSettings /> },
    ],
  },
];

5. API接口规范

5.1 通用规范

5.1.1 请求规范

  • Base URL: /api/v1
  • Content-Type: application/json
  • 字符编码: UTF-8
  • 时间格式: ISO 8601 (例如: 2024-01-15T10:30:00Z)
  • 容量单位: 字节 (Bytes)

5.1.2 响应规范

typescript
// 统一响应结构
interface ApiResponse<T> {
  code: number;       // 业务状态码，0表示成功
  message: string;    // 提示信息
  data: T;           // 响应数据
  timestamp: number; // 服务器时间戳
  requestId: string; // 请求追踪ID
}

// 分页响应结构
interface PaginatedResponse<T> {
  total: number;      // 总记录数
  page: number;       // 当前页码
  size: number;       // 每页大小
  items: T[];        // 数据列表
}

5.2 错误码定义

错误码说明HTTP状态码处理建议
0成功200-
10001参数错误400检查请求参数格式
10002认证失败401重新登录获取Token
10003权限不足403确认用户角色权限
10004资源不存在404检查资源ID是否正确
20001硬盘不存在404确认硬盘ID有效
20002硬盘正在使用409先从存储池中移除
20003S.M.A.R.T检测失败500检查硬盘连接状态
30001存储池不存在404确认存储池ID
30002磁盘数量不足400RAID5至少需要3块盘
30003RAID创建失败500查看系统日志
30004存储池名称已存在409更换存储池名称
50000服务器内部错误500联系管理员

5.3 硬盘管理接口

5.3.1 获取硬盘列表

http
GET /api/v1/storage/disks

请求参数：

参数名类型必需默认值描述
pageinteger否1页码，从1开始
sizeinteger否20每页数量，最大100
statusstring否-过滤状态：healthy/warning/error/offline
pool_idstring否-按存储池过滤
sort_bystring否created_at排序字段
sort_orderstring否desc排序方向：asc/desc

响应示例（成功）：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 8,
    "page": 1,
    "size": 20,
    "items": [
      {
        "disk_id": "disk_001",
        "model": "ST4000VN008",
        "serial_number": "ZGY0K3MZ",
        "capacity": 4000787030016,
        "capacity_formatted": "3.64 TB",
        "health_status": "healthy",
        "smart_status": "passed",
        "temperature": 42,
        "temperature_status": "normal",
        "power_on_hours": 8760,
        "rotation_rate": 5400,
        "interface": "SATA",
        "pool_id": "pool_001",
        "pool_name": "数据存储池",
        "bay_location": "Bay-1",
        "filesystem": "ext4",
        "created_at": "2024-01-15T08:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ]
  },
  "timestamp": 1705312200,
  "requestId": "req_abc123"
}

5.3.2 获取硬盘详情

http
GET /api/v1/storage/disks/{disk_id}

路径参数：

参数名类型必需描述
disk_idstring是硬盘唯一标识

5.3.3 获取硬盘S.M.A.R.T信息

http
GET /api/v1/storage/disks/{disk_id}/smart

响应示例：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "disk_id": "disk_001",
    "smart_enabled": true,
    "overall_health": "PASSED",
    "attributes": [
      {
        "id": 1,
        "name": "Raw_Read_Error_Rate",
        "value": 100,
        "worst": 100,
        "threshold": 50,
        "raw_value": "0",
        "status": "ok"
      },
      {
        "id": 194,
        "name": "Temperature_Celsius",
        "value": 58,
        "worst": 58,
        "threshold": 0,
        "raw_value": "42",
        "status": "ok"
      }
    ],
    "power_on_hours": 8760,
    "power_cycle_count": 150,
    "last_updated": "2024-01-15T10:30:00Z"
  }
}

5.4 存储池管理接口

5.4.1 创建存储池

http
POST /api/v1/storage/pools

请求体：

json
{
  "pool_name": "数据存储池",
  "description": "用于存放用户数据",
  "raid_level": "raid5",
  "disk_ids": ["disk_001", "disk_002", "disk_003"],
  "stripe_size": 64,
  "filesystem": "ext4",
  "mount_point": "/mnt/data"
}

字段说明：

字段名类型必需约束描述
pool_namestring是1-100字符存储池名称，唯一
descriptionstring否最大500字符存储池描述
raid_levelstring是枚举值RAID级别：raid0/raid1/raid5/raid6/raid10
disk_idsarray是见下表硬盘ID列表
stripe_sizeinteger否4/8/16/32/64/128/256/512/1024条带大小，单位KB，默认64
filesystemstring否枚举值文件系统：ext4/btrfs/xfs，默认ext4
mount_pointstring否路径格式挂载点路径

RAID级别磁盘数量要求：

RAID级别最小磁盘数最大磁盘数容错能力
RAID 02无限制0块
RAID 1221块
RAID 53无限制1块
RAID 64无限制2块
RAID 104无限制(偶数)每组1块

响应示例（成功）：

json
{
  "code": 0,
  "message": "存储池创建任务已提交",
  "data": {
    "pool_id": "pool_001",
    "pool_name": "数据存储池",
    "raid_level": "raid5",
    "status": "creating",
    "task_id": "task_abc123",
    "estimated_time": 300
  }
}

5.4.2 扩展存储池

http
POST /api/v1/storage/pools/{pool_id}/expand

请求体：

json
{
  "disk_ids": ["disk_004", "disk_005"],
  "expand_type": "add_disk"
}

5.4.3 删除存储池

http
DELETE /api/v1/storage/pools/{pool_id}

查询参数：

参数名类型必需描述
forceboolean否是否强制删除（忽略警告）

5.5 容量监控接口

5.5.1 获取容量统计

http
GET /api/v1/storage/capacity

响应示例：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "summary": {
      "total_raw_capacity": 16003148752064,
      "total_usable_capacity": 12000000000000,
      "used_capacity": 8000000000000,
      "free_capacity": 4000000000000,
      "usage_percent": 66.7
    },
    "by_pool": [
      {
        "pool_id": "pool_001",
        "pool_name": "数据存储池",
        "total_capacity": 8000000000000,
        "used_capacity": 6000000000000,
        "free_capacity": 2000000000000,
        "usage_percent": 75.0,
        "status": "warning"
      }
    ],
    "trend": {
      "period": "7d",
      "data_points": [
        { "date": "2024-01-08", "used": 7500000000000 },
        { "date": "2024-01-15", "used": 8000000000000 }
      ],
      "growth_rate": "5.2 GB/天"
    }
  }
}

5.5.2 设置告警规则

http
POST /api/v1/storage/alerts/rules

请求体：

json
{
  "rule_name": "容量告警-80%",
  "rule_type": "capacity",
  "target_type": "pool",
  "target_id": "pool_001",
  "threshold": 80,
  "severity": "warning",
  "notification_channels": ["email", "webhook"],
  "enabled": true
}

6. 数据模型设计

6.1 实体关系图

erDiagram
    DISK ||--o{ POOL : belongs_to
    POOL ||--o{ VOLUME : contains
    POOL ||--o{ ALERT_RULE : triggers
    POOL ||--o{ TASK : generates

    DISK {
        string disk_id PK "硬盘唯一标识"
        string model "型号"
        string serial_number "序列号"
        bigint capacity "容量(字节)"
        string health_status "健康状态"
        string smart_status "S.M.A.R.T状态"
        int temperature "温度(°C)"
        int power_on_hours "通电时间(小时)"
        int rotation_rate "转速(RPM)"
        string interface "接口类型"
        string pool_id FK "所属存储池"
        string bay_location "物理位置"
        string filesystem "文件系统"
        timestamp created_at "创建时间"
        timestamp updated_at "更新时间"
    }

    POOL {
        string pool_id PK "存储池唯一标识"
        string pool_name "存储池名称"
        string description "描述"
        string raid_level "RAID级别"
        bigint total_capacity "总容量"
        bigint used_capacity "已用容量"
        string status "状态"
        string filesystem "文件系统"
        string mount_point "挂载点"
        timestamp created_at "创建时间"
        timestamp updated_at "更新时间"
    }

    VOLUME {
        string volume_id PK "卷唯一标识"
        string pool_id FK "所属存储池"
        string volume_name "卷名称"
        bigint capacity "容量"
        bigint used_capacity "已用容量"
        string filesystem "文件系统"
        string mount_point "挂载点"
        boolean is_snapshot "是否快照"
        string parent_volume_id "父卷ID(快照用)"
    }

    ALERT_RULE {
        string rule_id PK "规则唯一标识"
        string rule_name "规则名称"
        string rule_type "规则类型"
        string target_type "目标类型"
        string target_id FK "目标ID"
        decimal threshold "阈值"
        string severity "严重级别"
        json notification_channels "通知渠道"
        boolean is_enabled "是否启用"
        timestamp created_at "创建时间"
    }

    TASK {
        string task_id PK "任务唯一标识"
        string task_type "任务类型"
        string target_type "目标类型"
        string target_id FK "目标ID"
        string status "任务状态"
        int progress "进度(%)"
        json result "执行结果"
        timestamp started_at "开始时间"
        timestamp completed_at "完成时间"
    }

6.2 数据库表结构

6.2.1 硬盘表 (disks)

sql
CREATE TABLE disks (
    disk_id VARCHAR(50) PRIMARY KEY COMMENT '硬盘唯一标识',
    model VARCHAR(100) NOT NULL COMMENT '硬盘型号',
    serial_number VARCHAR(100) UNIQUE COMMENT '序列号',
    capacity BIGINT NOT NULL COMMENT '容量(字节)',
    health_status VARCHAR(20) DEFAULT 'unknown' COMMENT '健康状态: healthy/warning/error/unknown',
    smart_status VARCHAR(20) DEFAULT 'unknown' COMMENT 'S.M.A.R.T状态: passed/failed/unknown',
    temperature INTEGER DEFAULT 0 COMMENT '温度(摄氏度)',
    power_on_hours INTEGER DEFAULT 0 COMMENT '通电时间(小时)',
    rotation_rate INTEGER COMMENT '转速(RPM)',
    interface VARCHAR(20) COMMENT '接口类型: SATA/SAS/NVMe',
    pool_id VARCHAR(50) COMMENT '所属存储池ID',
    bay_location VARCHAR(50) COMMENT '物理盘位位置',
    filesystem VARCHAR(20) COMMENT '文件系统类型',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

    INDEX idx_disks_pool_id (pool_id),
    INDEX idx_disks_health (health_status),
    INDEX idx_disks_status_temp (health_status, temperature),
    FOREIGN KEY (pool_id) REFERENCES storage_pools(pool_id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='硬盘信息表';

6.2.2 存储池表 (storage_pools)

sql
CREATE TABLE storage_pools (
    pool_id VARCHAR(50) PRIMARY KEY COMMENT '存储池唯一标识',
    pool_name VARCHAR(100) NOT NULL UNIQUE COMMENT '存储池名称',
    description VARCHAR(500) COMMENT '存储池描述',
    raid_level VARCHAR(20) NOT NULL COMMENT 'RAID级别: raid0/raid1/raid5/raid6/raid10',
    total_capacity BIGINT NOT NULL COMMENT '总容量(字节)',
    used_capacity BIGINT DEFAULT 0 COMMENT '已用容量(字节)',
    free_capacity BIGINT GENERATED ALWAYS AS (total_capacity - used_capacity) COMMENT '可用容量',
    status VARCHAR(20) DEFAULT 'creating' COMMENT '状态: creating/active/degraded/failed/deleting',
    filesystem VARCHAR(20) DEFAULT 'ext4' COMMENT '文件系统: ext4/btrfs/xfs',
    mount_point VARCHAR(255) COMMENT '挂载点路径',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

    INDEX idx_pools_status (status),
    INDEX idx_pools_name (pool_name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='存储池信息表';

6.2.3 告警规则表 (alert_rules)

sql
CREATE TABLE alert_rules (
    rule_id VARCHAR(50) PRIMARY KEY COMMENT '规则唯一标识',
    rule_name VARCHAR(100) NOT NULL COMMENT '规则名称',
    rule_type VARCHAR(50) NOT NULL COMMENT '规则类型: capacity/health/performance',
    target_type VARCHAR(50) NOT NULL COMMENT '目标类型: pool/disk/system',
    target_id VARCHAR(50) COMMENT '目标ID',
    threshold DECIMAL(5,2) COMMENT '阈值',
    severity VARCHAR(20) DEFAULT 'warning' COMMENT '严重级别: info/warning/critical',
    notification_channels JSON COMMENT '通知渠道配置',
    is_enabled BOOLEAN DEFAULT TRUE COMMENT '是否启用',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

    INDEX idx_rules_type (rule_type),
    INDEX idx_rules_enabled (is_enabled)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='告警规则表';

7. 前端架构设计

7.1 目录结构

采用 Feature-Based 目录结构，将相关功能代码组织在一起，提升可维护性。

src/
├── app/                          # 应用层
│   ├── App.tsx                   # 根组件
│   ├── routes.tsx                # 路由配置
│   ├── store.ts                  # Redux Store配置
│   └── providers.tsx             # 全局Provider
│
├── features/                     # 特性模块（按功能划分）
│   └── nas/                      # NAS存储管理特性
│       ├── components/           # 组件
│       │   ├── DiskCard/         # 硬盘卡片组件
│       │   │   ├── index.tsx
│       │   │   ├── DiskCard.module.less
│       │   │   └── DiskCard.test.tsx
│       │   ├── PoolList/         # 存储池列表
│       │   ├── RaidWizard/       # RAID创建向导
│       │   │   ├── steps/        # 向导步骤
│       │   │   ├── hooks/        # 向导专用hooks
│       │   │   └── utils/        # 向导工具函数
│       │   ├── CapacityChart/    # 容量图表
│       │   └── AlertConfig/      # 告警配置
│       │
│       ├── hooks/                # 自定义Hooks
│       │   ├── useDiskStatus.ts      # 硬盘状态订阅
│       │   ├── usePoolActions.ts     # 存储池操作
│       │   ├── useCapacityAlert.ts   # 容量告警
│       │   └── useWebSocket.ts       # WebSocket连接
│       │
│       ├── services/             # API服务层
│       │   ├── diskService.ts        # 硬盘API
│       │   ├── poolService.ts        # 存储池API
│       │   ├── monitorService.ts     # 监控API
│       │   └── client.ts             # Axios实例
│       │
│       ├── types/                # TypeScript类型定义
│       │   ├── disk.types.ts
│       │   ├── pool.types.ts
│       │   ├── api.types.ts
│       │   └── enums.ts
│       │
│       └── store/                # Redux状态管理
│           ├── diskSlice.ts      # 硬盘状态
│           ├── poolSlice.ts      # 存储池状态
│           ├── alertSlice.ts     # 告警状态
│           └── index.ts          # Reducer组合
│
├── shared/                       # 共享资源
│   ├── components/               # 通用组件
│   │   ├── DataTable/            # 数据表格
│   │   ├── StatusBadge/          # 状态标签
│   │   ├── CapacityBar/          # 容量进度条
│   │   └── ConfirmModal/         # 确认弹窗
│   │
│   ├── hooks/                    # 通用Hooks
│   │   ├── usePagination.ts
│   │   ├── useDebounce.ts
│   │   └── useLocalStorage.ts
│   │
│   ├── utils/                    # 工具函数
│   │   ├── formatters.ts         # 格式化（容量、日期等）
│   │   ├── validators.ts         # 表单校验
│   │   └── constants.ts          # 常量定义
│   │
│   └── styles/                   # 全局样式
│       ├── variables.less        # 变量
│       └── mixins.less           # 混入
│
└── locales/                      # 国际化
    ├── zh-CN/                    # 中文
    └── en-US/                    # 英文

7.2 状态管理架构

graph TD
    subgraph 视图层 View
        A1[DiskList组件]
        A2[PoolDetail组件]
        A3[AlertConfig组件]
    end

    subgraph Redux Store
        B[Root Reducer]
        B --> C[diskSlice<br/>硬盘状态]
        B --> D[poolSlice<br/>存储池状态]
        B --> E[alertSlice<br/>告警状态]
        B --> F[uiSlice<br/>UI状态]
    end

    subgraph 服务层 Service
        G[Disk API]
        H[Pool API]
        I[Monitor API]
    end

    subgraph 后端 Backend
        J[NAS后端服务]
    end

    A1 -->|useSelector| C
    A2 -->|useSelector| D
    A3 -->|useSelector| E

    C -->|thunk| G
    D -->|thunk| H
    E -->|thunk| I

    G --> J
    H --> J
    I --> J

    J -->|WebSocket| F
    F -->|通知| A1
    F -->|通知| A2

    style 视图层 fill:#e3f2fd
    style Redux fill:#f3e5f5
    style 服务层 fill:#e8f5e9
    style 后端 fill:#fff3e0

状态管理原则：

  1. Server State（服务端状态）：使用RTK Query管理，自动缓存和失效
  2. Client State（客户端状态）：使用Redux Slice管理，如UI状态、表单草稿
  3. URL State（URL状态）：使用React Router管理，如分页、筛选条件

8. 性能优化策略

8.1 前端优化

优化策略实现方式预期效果
代码分割React.lazy() + Suspense减少首包体积
路由懒加载按路由代码分割按需加载页面
组件懒加载模态框、图表组件懒加载延迟非关键资源
Tree ShakingVite自动摇树优化移除无用代码
图片优化WebP格式、懒加载、占位符减少图片体积
虚拟滚动react-window 大数据列表流畅渲染万级数据
Memo优化React.memo、useMemo减少重渲染
状态订阅细粒度selector订阅避免不必要更新

8.2 接口优化

优化策略实现方式适用场景
分页加载后端分页 + 前端虚拟滚动硬盘列表、日志列表
增量更新WebSocket推送状态变化硬盘状态、容量变化
数据缓存RTK Query缓存 + SWR配置数据、静态数据
请求合并防抖/节流处理高频请求搜索输入、滑块调整
预加载路由预加载、数据预取详情页、下一步向导
压缩传输Gzip/Brotli压缩响应大JSON数据

9. 安全设计

9.1 认证授权

安全措施实现方式说明
JWT认证Access Token + Refresh Token无状态认证，支持Token刷新
RBAC权限角色-权限-资源模型admin/user/viewer三级角色
路由守卫高阶组件 + 路由配置前端路由级权限控制
API鉴权请求头携带Token401未授权自动跳转登录
Token安全HttpOnly Cookie存储防XSS攻击

9.2 数据安全

安全措施实现方式说明
输入验证Formik + Yup校验前端表单输入验证
XSS防护React自动转义 + CSP内容安全策略
CSRF防护SameSite Cookie + Token跨站请求伪造防护
敏感信息前端脱敏显示序列号、密钥部分隐藏
操作审计关键操作记录日志创建、删除操作留痕

10. 测试策略

10.1 测试金字塔

        /\
       /  \
      / E2E \      <--- 端到端测试 (5%)
     /--------\         Playwright
    /          \
   / Integration \   <--- 集成测试 (15%)
  /--------------\       React Testing Library
 /                \
/    Unit Tests    \<--- 单元测试 (80%)
/--------------------\   Jest
测试类型工具覆盖率目标测试范围
单元测试Jest + RTL≥80%工具函数、Hooks、Reducers
组件测试React Testing Library≥70%UI组件渲染、交互
集成测试MSW + RTL核心流程API + 组件联动
E2E测试Playwright主流程关键用户场景

10.2 测试用例示例

typescript
// src/features/nas/components/DiskCard/DiskCard.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { DiskCard } from './index';
import type { Disk } from '../../types/disk.types';

describe('DiskCard Component', () => {
  const mockDisk: Disk = {
    disk_id: 'disk_001',
    model: 'ST4000VN008',
    serial_number: 'ZGY0K3MZ',
    capacity: 4000787030016,
    capacity_formatted: '3.64 TB',
    health_status: 'healthy',
    smart_status: 'passed',
    temperature: 42,
    temperature_status: 'normal',
    power_on_hours: 8760,
  };

  it('应正确显示硬盘基本信息', () => {
    render(<DiskCard disk={mockDisk} />);

    expect(screen.getByText('ST4000VN008')).toBeInTheDocument();
    expect(screen.getByText('3.64 TB')).toBeInTheDocument();
    expect(screen.getByText('健康')).toBeInTheDocument();
    expect(screen.getByText('42°C')).toBeInTheDocument();
  });

  it('点击应触发onSelect回调', async () => {
    const onSelect = jest.fn();
    render(<DiskCard disk={mockDisk} onSelect={onSelect} />);

    await userEvent.click(screen.getByTestId('disk-card'));
    expect(onSelect).toHaveBeenCalledWith('disk_001');
  });

  it('健康状态为error时应显示警告样式', () => {
    const errorDisk = { ...mockDisk, health_status: 'error' };
    render(<DiskCard disk={errorDisk} />);

    const card = screen.getByTestId('disk-card');
    expect(card).toHaveClass('disk-card--error');
  });
});

11. 部署与运维

11.1 构建部署

yaml
# 构建配置
build:
  command: npm run build
  output_dir: dist/
  node_version: 18.x

# 部署配置
deploy:
  target: github_pages
  branch: gh-pages
  cdn:
    enabled: true
    cache_control: "public, max-age=31536000"
环境部署目标触发条件备注
开发Vercel预览PR创建自动部署
测试GitHub Pages (test)合并到develop功能验证
生产GitHub Pages (prod)合并到main手动确认

11.2 监控指标

类别指标告警阈值采集方式
性能LCP（最大内容绘制）> 2.5sWeb Vitals API
性能FID（首次输入延迟）> 100msWeb Vitals API
性能CLS（累积布局偏移）> 0.1Web Vitals API
错误JS错误率> 1%Sentry
错误API错误率> 5%Axios拦截器
业务页面加载时间> 3sPerformance API
业务用户会话数-Google Analytics

12. 附录

12.1 参考文档

文档链接说明
React官方文档https://react.devReact 18新特性
Redux Toolkithttps://redux-toolkit.js.org状态管理最佳实践
Ant Designhttps://ant.designUI组件库文档
Vite配置指南https://vitejs.dev/config/构建工具配置
Web Vitalshttps://web.dev/vitals/性能指标标准

文档结束

如有疑问，请联系架构组。

本文作者:oyph

本文链接:

版权声明:本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！