545 lines
16 KiB
Markdown
545 lines
16 KiB
Markdown
# 存储配置
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [TsStorage.js](file://src/utils/TsStorage.js)
|
||
- [TsCrypto.js](file://src/utils/TsCrypto.js)
|
||
- [TsSM4.js](file://src/utils/TsSM4.js)
|
||
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
|
||
- [TsCommon.js](file://src/utils/TsCommon.js)
|
||
- [index.js](file://index.js)
|
||
- [package.json](file://package.json)
|
||
- [README.md](file://README.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
|
||
本指南专注于 TsStorage 模块的存储配置，这是一个基于 localStorage 的轻量级存储解决方案。该模块提供了完整的数据持久化功能，包括基础存储操作、用户令牌管理、数据加密以及全局配置管理。通过本文档，您将了解如何正确配置和使用存储功能，包括存储前缀、加密开关、存储策略等关键配置选项。
|
||
|
||
## 项目结构
|
||
|
||
该项目采用模块化设计，主要包含以下核心文件：
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "核心模块"
|
||
A[index.js<br/>主入口文件]
|
||
B[TsStorage.js<br/>存储模块]
|
||
C[TsCrypto.js<br/>加密模块]
|
||
D[TsSM4.js<br/>SM4算法实现]
|
||
E[TsGlobalConfig.js<br/>全局配置]
|
||
F[TsCommon.js<br/>通用工具]
|
||
end
|
||
subgraph "外部依赖"
|
||
G[base64-js<br/>Base64编码]
|
||
H[umi-request<br/>HTTP请求]
|
||
end
|
||
A --> B
|
||
A --> C
|
||
A --> D
|
||
A --> E
|
||
A --> F
|
||
C --> D
|
||
C --> E
|
||
B --> F
|
||
D --> G
|
||
A --> H
|
||
```
|
||
|
||
**图表来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||
|
||
**章节来源**
|
||
- [index.js:1-16](file://index.js#L1-L16)
|
||
- [package.json:1-24](file://package.json#L1-L24)
|
||
|
||
## 核心组件
|
||
|
||
### TsStorage 模块
|
||
|
||
TsStorage 是整个存储系统的核心模块，提供了以下主要功能：
|
||
|
||
- **基础存储操作**：提供通用的保存和获取方法
|
||
- **用户令牌管理**：专门处理用户认证令牌的存储
|
||
- **加密开关控制**：支持启用或禁用数据加密功能
|
||
- **数据序列化**：自动处理 JSON 序列化和反序列化
|
||
|
||
### TsCrypto 模块
|
||
|
||
负责数据加密和解密的核心模块，基于 SM4 算法实现：
|
||
|
||
- **SM4 加密算法**：实现中国国家密码标准的 SM4 对称加密
|
||
- **密钥管理**：从全局配置中获取和管理加密密钥
|
||
- **模式支持**：支持 ECB 和 CBC 两种加密模式
|
||
|
||
### TsSM4 模块
|
||
|
||
SM4 算法的具体实现，包含完整的加密和解密逻辑：
|
||
|
||
- **算法实现**：完整的 SM4 加密算法实现
|
||
- **填充机制**：支持 PKCS7 填充标准
|
||
- **多种输出格式**：支持 Base64 和文本两种输出格式
|
||
|
||
**章节来源**
|
||
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
|
||
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
|
||
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
|
||
|
||
## 架构概览
|
||
|
||
存储系统的整体架构采用分层设计，确保了功能的模块化和可维护性：
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph "应用层"
|
||
App[应用程序]
|
||
end
|
||
subgraph "存储接口层"
|
||
Storage[Storage 接口]
|
||
Crypto[Crypto 接口]
|
||
end
|
||
subgraph "业务逻辑层"
|
||
Token[用户令牌管理]
|
||
Config[配置管理]
|
||
Utils[通用工具]
|
||
end
|
||
subgraph "数据访问层"
|
||
LocalStorage[localStorage]
|
||
Memory[内存缓存]
|
||
end
|
||
App --> Storage
|
||
App --> Crypto
|
||
Storage --> Token
|
||
Storage --> Config
|
||
Storage --> Utils
|
||
Crypto --> SM4
|
||
Utils --> LocalStorage
|
||
Storage --> LocalStorage
|
||
Crypto --> Memory
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsStorage.js:26-43](file://src/utils/TsStorage.js#L26-L43)
|
||
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
|
||
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
|
||
|
||
## 详细组件分析
|
||
|
||
### 存储配置选项详解
|
||
|
||
#### 基础存储配置
|
||
|
||
TsStorage 模块提供了灵活的基础存储配置选项：
|
||
|
||
**数据序列化配置**
|
||
- 自动 JSON 序列化：所有存储的数据都会被自动转换为 JSON 字符串
|
||
- 安全反序列化：使用安全的 JSON 解析机制，避免异常导致的应用崩溃
|
||
- 默认值处理：支持为不存在的键提供默认值
|
||
|
||
**存储策略配置**
|
||
- 键值映射：每个存储项都以键值对的形式保存在 localStorage 中
|
||
- 数据包装：内部使用 `{data: value}` 的包装格式存储原始数据
|
||
- 类型保持：通过 JSON 序列化保持数据类型信息
|
||
|
||
#### 加密存储配置
|
||
|
||
**加密开关配置**
|
||
- `saveEncryptBody(bool)`：设置是否启用数据加密
|
||
- `getEncryptBody()`：获取当前加密状态
|
||
- 默认启用：加密功能默认处于启用状态
|
||
|
||
**加密算法配置**
|
||
- SM4 算法：采用中国国家密码标准的对称加密算法
|
||
- ECB 模式：默认使用 ECB 模式进行加密
|
||
- Base64 输出：加密结果以 Base64 格式存储
|
||
|
||
**密钥配置**
|
||
- 全局密钥管理：密钥从全局配置中获取
|
||
- Base64 编码：密钥以 Base64 格式存储和传输
|
||
- 配置覆盖：支持运行时动态修改密钥
|
||
|
||
#### 用户令牌配置
|
||
|
||
**令牌存储配置**
|
||
- 专用令牌键：使用固定的 'token' 键存储用户令牌
|
||
- 自动序列化：令牌数据自动进行 JSON 序列化
|
||
- 空值处理：未找到令牌时返回空字符串
|
||
|
||
**令牌管理策略**
|
||
- 单一令牌模型：系统只支持单一用户令牌
|
||
- 简化接口：提供简化的 get/set 方法
|
||
- 安全存储：令牌数据同样遵循加密配置
|
||
|
||
**章节来源**
|
||
- [TsStorage.js:9-23](file://src/utils/TsStorage.js#L9-L23)
|
||
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||
- [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)
|
||
|
||
### 存储场景配置建议
|
||
|
||
#### 用户会话存储
|
||
|
||
**配置策略**
|
||
- 启用加密：用户会话数据包含敏感信息，必须启用加密
|
||
- 设置过期时间：结合业务需求设置合理的过期时间
|
||
- 清理策略：定期清理过期的会话数据
|
||
|
||
**实现示例**
|
||
```javascript
|
||
// 启用加密存储
|
||
Storage.saveEncryptBody(true);
|
||
|
||
// 存储用户令牌
|
||
Storage.saveUserToken(token);
|
||
|
||
// 获取用户令牌
|
||
const token = Storage.getUserToken();
|
||
```
|
||
|
||
#### 应用状态存储
|
||
|
||
**配置策略**
|
||
- 非敏感数据：非敏感的应用状态可以不启用加密
|
||
- 性能优化：对于大量数据的存储，考虑启用加密可能影响性能
|
||
- 数据压缩：对于大体量数据，考虑先压缩再存储
|
||
|
||
**实现示例**
|
||
```javascript
|
||
// 根据数据敏感性选择加密
|
||
if (isSensitiveData) {
|
||
Storage.saveEncryptBody(true);
|
||
} else {
|
||
Storage.saveEncryptBody(false);
|
||
}
|
||
|
||
// 存储应用配置
|
||
Storage.save('appConfig', configData);
|
||
```
|
||
|
||
#### 临时数据存储
|
||
|
||
**配置策略**
|
||
- 短期存储：临时数据适合短期存储，不需要长期保留
|
||
- 自动清理：设置合理的过期时间，避免占用过多存储空间
|
||
- 批量清理：定期清理过期的临时数据
|
||
|
||
**章节来源**
|
||
- [TsStorage.js:47-54](file://src/utils/TsStorage.js#L47-L54)
|
||
|
||
### 存储容量限制和清理策略
|
||
|
||
#### 容量限制
|
||
|
||
**localStorage 限制**
|
||
- 浏览器限制：每个域名下通常有 5-10MB 的存储限制
|
||
- 平台差异：不同浏览器的限制可能有所不同
|
||
- 存储检查：需要定期检查存储使用情况
|
||
|
||
**容量监控**
|
||
- 使用率计算：监控已用空间与总容量的比例
|
||
- 预警机制：当使用率达到一定阈值时发出警告
|
||
- 自动清理：超过阈值时自动清理过期数据
|
||
|
||
#### 清理策略
|
||
|
||
**定时清理**
|
||
- 周期性清理：定期执行清理任务，删除过期数据
|
||
- 条件清理：根据存储使用情况触发清理
|
||
- 批量清理：一次性清理多个过期项目
|
||
|
||
**智能清理**
|
||
- 优先级清理：优先清理低优先级的过期数据
|
||
- 空间回收：清理后释放存储空间
|
||
- 性能优化：清理过程不影响正常的数据访问
|
||
|
||
**章节来源**
|
||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||
|
||
### 加密存储配置方法和性能影响
|
||
|
||
#### 加密配置方法
|
||
|
||
**基本加密配置**
|
||
```javascript
|
||
// 创建加密实例
|
||
const crypto = new TsCrypto();
|
||
|
||
// 加密数据
|
||
const encrypted = crypto.encrypt("敏感数据");
|
||
|
||
// 解密数据
|
||
const decrypted = crypto.decrypt(encrypted);
|
||
```
|
||
|
||
**高级配置选项**
|
||
- 模式选择：ECB 或 CBC 模式的选择
|
||
- 输出格式：Base64 或文本格式的输出
|
||
- IV 参数：CBC 模式的初始化向量配置
|
||
|
||
#### 性能影响分析
|
||
|
||
**CPU 开销**
|
||
- 加密开销：加密操作需要额外的 CPU 时间
|
||
- 解密开销：解密操作同样消耗 CPU 资源
|
||
- 批量处理：批量处理数据时的性能考虑
|
||
|
||
**内存使用**
|
||
- 内存占用：加密算法需要额外的内存空间
|
||
- 数据复制：加密过程中可能产生数据副本
|
||
- 缓存策略：合理使用缓存减少重复计算
|
||
|
||
**I/O 影响**
|
||
- 序列化成本：JSON 序列化和反序列化的影响
|
||
- 存储效率：加密后的数据大小变化
|
||
- 网络传输：加密数据在网络传输中的影响
|
||
|
||
**章节来源**
|
||
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
|
||
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
|
||
|
||
### 存储配置的安全考虑和最佳实践
|
||
|
||
#### 安全配置
|
||
|
||
**密钥管理**
|
||
- 密钥强度：确保密钥具有足够的随机性和长度
|
||
- 密钥轮换：定期更换加密密钥
|
||
- 安全存储：密钥的存储和传输要确保安全
|
||
|
||
**数据保护**
|
||
- 敏感数据：识别和保护敏感数据
|
||
- 访问控制：限制对敏感数据的访问权限
|
||
- 审计日志：记录重要的数据访问和修改操作
|
||
|
||
**传输安全**
|
||
- HTTPS 传输：确保数据在传输过程中的安全
|
||
- 中间人攻击：防范中间人攻击和数据篡改
|
||
- 会话管理：安全的会话管理和令牌处理
|
||
|
||
#### 最佳实践
|
||
|
||
**配置最佳实践**
|
||
- 最小权限原则：只授予必要的存储权限
|
||
- 数据最小化：只存储必要的数据
|
||
- 及时清理：及时清理不再需要的数据
|
||
|
||
**性能最佳实践**
|
||
- 异步操作：使用异步方式处理存储操作
|
||
- 批量处理：批量处理多个存储请求
|
||
- 缓存策略：合理使用缓存提高性能
|
||
|
||
**错误处理最佳实践**
|
||
- 异常捕获：妥善处理存储操作中的异常
|
||
- 降级策略：在存储失败时提供降级方案
|
||
- 用户提示：向用户提供清晰的错误信息
|
||
|
||
**章节来源**
|
||
- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
|
||
- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
|
||
|
||
### 存储配置的迁移和备份策略
|
||
|
||
#### 迁移策略
|
||
|
||
**版本兼容性**
|
||
- 数据格式升级：确保新版本能够读取旧版本的数据
|
||
- 渐进式迁移：逐步将旧数据迁移到新格式
|
||
- 回滚机制：提供数据迁移失败时的回滚方案
|
||
|
||
**配置迁移**
|
||
- 配置项更新：处理配置项的新增、删除和重命名
|
||
- 默认值处理：为新配置项设置合理的默认值
|
||
- 兼容性测试：确保迁移过程不影响现有功能
|
||
|
||
#### 备份策略
|
||
|
||
**数据备份**
|
||
- 定期备份：建立定期备份机制
|
||
- 多点备份：在多个位置保存备份数据
|
||
- 自动恢复：提供自动数据恢复功能
|
||
|
||
**配置备份**
|
||
- 配置导出：支持配置的导出和导入
|
||
- 版本管理：管理配置的不同版本
|
||
- 快速恢复：提供快速恢复到之前配置的能力
|
||
|
||
**章节来源**
|
||
- [TsStorage.js:26-43](file://src/utils/TsStorage.js#L26-L43)
|
||
- [TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)
|
||
|
||
### 存储配置的调试和监控方法
|
||
|
||
#### 调试方法
|
||
|
||
**存储调试**
|
||
- 数据验证：验证存储的数据是否正确
|
||
- 格式检查：检查数据的格式是否符合预期
|
||
- 性能监控：监控存储操作的性能指标
|
||
|
||
**加密调试**
|
||
- 加密验证：验证加密和解密过程的正确性
|
||
- 密钥检查：确认使用的密钥是否正确
|
||
- 算法验证：验证加密算法的实现是否正确
|
||
|
||
#### 监控方法
|
||
|
||
**性能监控**
|
||
- 响应时间：监控存储操作的响应时间
|
||
- 错误率：统计存储操作的错误率
|
||
- 资源使用：监控存储相关的资源使用情况
|
||
|
||
**健康监控**
|
||
- 存储状态：监控存储系统的健康状态
|
||
- 数据完整性：检查数据的完整性和一致性
|
||
- 安全监控：监控存储相关的安全事件
|
||
|
||
**章节来源**
|
||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||
|
||
## 依赖关系分析
|
||
|
||
存储系统的依赖关系相对简单，主要依赖于几个核心模块：
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "直接依赖"
|
||
A[TsStorage.js]
|
||
B[TsCrypto.js]
|
||
C[TsSM4.js]
|
||
D[TsCommon.js]
|
||
end
|
||
subgraph "外部依赖"
|
||
E[base64-js]
|
||
F[umi-request]
|
||
end
|
||
subgraph "全局配置"
|
||
G[TsGlobalConfig.js]
|
||
end
|
||
A --> D
|
||
B --> C
|
||
B --> G
|
||
C --> E
|
||
A --> G
|
||
A --> F
|
||
```
|
||
|
||
**图表来源**
|
||
- [TsStorage.js:1](file://src/utils/TsStorage.js#L1)
|
||
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
|
||
- [TsSM4.js:1](file://src/utils/TsSM4.js#L1)
|
||
- [TsGlobalConfig.js:1-3](file://src/utils/TsGlobalConfig.js#L1-L3)
|
||
|
||
**章节来源**
|
||
- [package.json:19-22](file://package.json#L19-L22)
|
||
- [index.js:1-7](file://index.js#L1-L7)
|
||
|
||
## 性能考虑
|
||
|
||
### 存储性能优化
|
||
|
||
**序列化优化**
|
||
- JSON 序列化：使用高效的 JSON 序列化方法
|
||
- 数据压缩：对于大数据量考虑压缩存储
|
||
- 批量操作：合并多个存储请求减少 I/O 操作
|
||
|
||
**内存管理**
|
||
- 对象复用：复用对象减少内存分配
|
||
- 及时释放：及时释放不再使用的对象引用
|
||
- 垃圾回收：合理安排垃圾回收时机
|
||
|
||
**并发处理**
|
||
- 异步操作：使用异步方式处理存储操作
|
||
- 锁机制：在需要时使用锁机制保证数据一致性
|
||
- 队列管理：使用队列管理并发的存储请求
|
||
|
||
### 加密性能优化
|
||
|
||
**算法优化**
|
||
- 缓存密钥：缓存加密密钥避免重复计算
|
||
- 批量加密：批量处理多个数据项
|
||
- 异步加密：使用异步方式处理加密操作
|
||
|
||
**资源配置**
|
||
- 线程池：合理配置加密操作的线程池
|
||
- 内存池：使用内存池减少内存分配开销
|
||
- 缓存策略：合理使用缓存提高加密性能
|
||
|
||
## 故障排除指南
|
||
|
||
### 常见问题诊断
|
||
|
||
**存储失败**
|
||
- 检查浏览器兼容性：确认目标浏览器支持 localStorage
|
||
- 验证存储空间：检查是否有足够的存储空间
|
||
- 检查权限设置：确认应用有足够的存储权限
|
||
|
||
**数据损坏**
|
||
- 验证数据格式：检查存储的数据格式是否正确
|
||
- 检查序列化问题：确认 JSON 序列化和反序列化正常
|
||
- 处理异常数据：对异常数据进行特殊处理
|
||
|
||
**加密问题**
|
||
- 密钥验证：确认使用的密钥是否正确
|
||
- 算法兼容性：检查加密算法的兼容性
|
||
- 性能问题：监控加密操作的性能表现
|
||
|
||
### 调试技巧
|
||
|
||
**日志记录**
|
||
- 关键操作日志：记录重要的存储操作
|
||
- 错误日志：详细记录存储操作中的错误
|
||
- 性能日志：记录存储操作的性能指标
|
||
|
||
**监控工具**
|
||
- 浏览器开发者工具：使用开发者工具监控存储操作
|
||
- 性能分析器：使用性能分析器分析存储性能
|
||
- 日志分析：定期分析存储相关的日志
|
||
|
||
**章节来源**
|
||
- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
|
||
- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||
|
||
## 结论
|
||
|
||
TsStorage 模块提供了一个功能完整、配置灵活的存储解决方案。通过本文档的详细说明，您可以：
|
||
|
||
1. **正确配置存储选项**：理解存储前缀、加密开关和存储策略的配置方法
|
||
2. **优化存储性能**：掌握性能优化的最佳实践和注意事项
|
||
3. **确保存储安全**：实施有效的安全措施和最佳实践
|
||
4. **制定迁移策略**：规划数据迁移和备份的完整方案
|
||
5. **有效调试监控**：建立完善的调试和监控体系
|
||
|
||
该模块的设计充分考虑了实际应用场景的需求，在保证功能完整性的同时，也注重了性能和安全性的平衡。通过合理配置和使用，可以满足大多数应用的存储需求。
|
||
|
||
## 附录
|
||
|
||
### 配置参考表
|
||
|
||
| 配置项 | 类型 | 默认值 | 描述 |
|
||
|--------|------|--------|------|
|
||
| base64Key | string | WmdUzPJXbngVNiaSsQrihg== | 加密密钥（Base64编码） |
|
||
| prefix | string | "" | 存储键前缀 |
|
||
| encrypt_body | boolean | true | 是否启用数据加密 |
|
||
| token | string | "" | 用户令牌存储 |
|
||
|
||
### 使用示例路径
|
||
|
||
- [基础存储操作:31-43](file://src/utils/TsStorage.js#L31-L43)
|
||
- [用户令牌管理:9-15](file://src/utils/TsStorage.js#L9-L15)
|
||
- [加密开关配置:17-23](file://src/utils/TsStorage.js#L17-L23)
|
||
- [全局配置管理:19-29](file://src/utils/TsGlobalConfig.js#L19-L29) |