npm-tool/.qoder/repowiki/zh/content/配置指南/存储配置.md

存储配置

**本文档引用的文件** - [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)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构概览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排除指南
9. 结论
10. 附录

简介

本指南专注于 TsStorage 模块的存储配置，这是一个基于 localStorage 的轻量级存储解决方案。该模块提供了完整的数据持久化功能，包括基础存储操作、用户令牌管理、数据加密以及全局配置管理。通过本文档，您将了解如何正确配置和使用存储功能，包括存储前缀、加密开关、存储策略等关键配置选项。

项目结构

该项目采用模块化设计，主要包含以下核心文件：

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
• TsStorage.js:1-55
• TsCrypto.js:1-34

章节来源

• index.js:1-16
• package.json:1-24

核心组件

TsStorage 模块

TsStorage 是整个存储系统的核心模块，提供了以下主要功能：

• 基础存储操作：提供通用的保存和获取方法
• 用户令牌管理：专门处理用户认证令牌的存储
• 加密开关控制：支持启用或禁用数据加密功能
• 数据序列化：自动处理 JSON 序列化和反序列化

TsCrypto 模块

负责数据加密和解密的核心模块，基于 SM4 算法实现：

• SM4 加密算法：实现中国国家密码标准的 SM4 对称加密
• 密钥管理：从全局配置中获取和管理加密密钥
• 模式支持：支持 ECB 和 CBC 两种加密模式

TsSM4 模块

SM4 算法的具体实现，包含完整的加密和解密逻辑：

• 算法实现：完整的 SM4 加密算法实现
• 填充机制：支持 PKCS7 填充标准
• 多种输出格式：支持 Base64 和文本两种输出格式

章节来源

• TsStorage.js:1-55
• TsCrypto.js:1-34
• TsSM4.js:1-456

架构概览

存储系统的整体架构采用分层设计，确保了功能的模块化和可维护性：

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
• TsCrypto.js:5-31
• TsGlobalConfig.js:19-29

详细组件分析

存储配置选项详解

基础存储配置

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
• TsStorage.js:31-43
• TsCrypto.js:7-13

存储场景配置建议

用户会话存储

配置策略

• 启用加密：用户会话数据包含敏感信息，必须启用加密
• 设置过期时间：结合业务需求设置合理的过期时间
• 清理策略：定期清理过期的会话数据

实现示例

// 启用加密存储
Storage.saveEncryptBody(true);

// 存储用户令牌
Storage.saveUserToken(token);

// 获取用户令牌
const token = Storage.getUserToken();

应用状态存储

配置策略

• 非敏感数据：非敏感的应用状态可以不启用加密
• 性能优化：对于大量数据的存储，考虑启用加密可能影响性能
• 数据压缩：对于大体量数据，考虑先压缩再存储

实现示例

// 根据数据敏感性选择加密
if (isSensitiveData) {
    Storage.saveEncryptBody(true);
} else {
    Storage.saveEncryptBody(false);
}

// 存储应用配置
Storage.save('appConfig', configData);

临时数据存储

配置策略

• 短期存储：临时数据适合短期存储，不需要长期保留
• 自动清理：设置合理的过期时间，避免占用过多存储空间
• 批量清理：定期清理过期的临时数据

章节来源

• TsStorage.js:47-54

存储容量限制和清理策略

容量限制

localStorage 限制

• 浏览器限制：每个域名下通常有 5-10MB 的存储限制
• 平台差异：不同浏览器的限制可能有所不同
• 存储检查：需要定期检查存储使用情况

容量监控

• 使用率计算：监控已用空间与总容量的比例
• 预警机制：当使用率达到一定阈值时发出警告
• 自动清理：超过阈值时自动清理过期数据

清理策略

定时清理

• 周期性清理：定期执行清理任务，删除过期数据
• 条件清理：根据存储使用情况触发清理
• 批量清理：一次性清理多个过期项目

智能清理

• 优先级清理：优先清理低优先级的过期数据
• 空间回收：清理后释放存储空间
• 性能优化：清理过程不影响正常的数据访问

章节来源

• TsCommon.js:34-44

加密存储配置方法和性能影响

加密配置方法

基本加密配置

// 创建加密实例
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
• TsSM4.js:338-387

存储配置的安全考虑和最佳实践

安全配置

密钥管理

• 密钥强度：确保密钥具有足够的随机性和长度
• 密钥轮换：定期更换加密密钥
• 安全存储：密钥的存储和传输要确保安全

数据保护

• 敏感数据：识别和保护敏感数据
• 访问控制：限制对敏感数据的访问权限
• 审计日志：记录重要的数据访问和修改操作

传输安全

• HTTPS 传输：确保数据在传输过程中的安全
• 中间人攻击：防范中间人攻击和数据篡改
• 会话管理：安全的会话管理和令牌处理

最佳实践

配置最佳实践

• 最小权限原则：只授予必要的存储权限
• 数据最小化：只存储必要的数据
• 及时清理：及时清理不再需要的数据

性能最佳实践

• 异步操作：使用异步方式处理存储操作
• 批量处理：批量处理多个存储请求
• 缓存策略：合理使用缓存提高性能

错误处理最佳实践

• 异常捕获：妥善处理存储操作中的异常
• 降级策略：在存储失败时提供降级方案
• 用户提示：向用户提供清晰的错误信息

章节来源

• TsGlobalConfig.js:5-13
• TsCrypto.js:8-12

存储配置的迁移和备份策略

迁移策略

版本兼容性

• 数据格式升级：确保新版本能够读取旧版本的数据
• 渐进式迁移：逐步将旧数据迁移到新格式
• 回滚机制：提供数据迁移失败时的回滚方案

配置迁移

• 配置项更新：处理配置项的新增、删除和重命名
• 默认值处理：为新配置项设置合理的默认值
• 兼容性测试：确保迁移过程不影响现有功能

备份策略

数据备份

• 定期备份：建立定期备份机制
• 多点备份：在多个位置保存备份数据
• 自动恢复：提供自动数据恢复功能

配置备份

• 配置导出：支持配置的导出和导入
• 版本管理：管理配置的不同版本
• 快速恢复：提供快速恢复到之前配置的能力

章节来源

• TsStorage.js:26-43
• TsGlobalConfig.js:27-29

存储配置的调试和监控方法

调试方法

存储调试

• 数据验证：验证存储的数据是否正确
• 格式检查：检查数据的格式是否符合预期
• 性能监控：监控存储操作的性能指标

加密调试

• 加密验证：验证加密和解密过程的正确性
• 密钥检查：确认使用的密钥是否正确
• 算法验证：验证加密算法的实现是否正确

监控方法

性能监控

• 响应时间：监控存储操作的响应时间
• 错误率：统计存储操作的错误率
• 资源使用：监控存储相关的资源使用情况

健康监控

• 存储状态：监控存储系统的健康状态
• 数据完整性：检查数据的完整性和一致性
• 安全监控：监控存储相关的安全事件

章节来源

• TsCommon.js:34-44
• TsStorage.js:31-43

依赖关系分析

存储系统的依赖关系相对简单，主要依赖于几个核心模块：

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
• TsCrypto.js:1-3
• TsSM4.js:1
• TsGlobalConfig.js:1-3

章节来源

• package.json:19-22
• index.js:1-7

性能考虑

存储性能优化

序列化优化

• JSON 序列化：使用高效的 JSON 序列化方法
• 数据压缩：对于大数据量考虑压缩存储
• 批量操作：合并多个存储请求减少 I/O 操作

内存管理

• 对象复用：复用对象减少内存分配
• 及时释放：及时释放不再使用的对象引用
• 垃圾回收：合理安排垃圾回收时机

并发处理

• 异步操作：使用异步方式处理存储操作
• 锁机制：在需要时使用锁机制保证数据一致性
• 队列管理：使用队列管理并发的存储请求

加密性能优化

算法优化

• 缓存密钥：缓存加密密钥避免重复计算
• 批量加密：批量处理多个数据项
• 异步加密：使用异步方式处理加密操作

资源配置

• 线程池：合理配置加密操作的线程池
• 内存池：使用内存池减少内存分配开销
• 缓存策略：合理使用缓存提高加密性能

故障排除指南

常见问题诊断

存储失败

• 检查浏览器兼容性：确认目标浏览器支持 localStorage
• 验证存储空间：检查是否有足够的存储空间
• 检查权限设置：确认应用有足够的存储权限

数据损坏

• 验证数据格式：检查存储的数据格式是否正确
• 检查序列化问题：确认 JSON 序列化和反序列化正常
• 处理异常数据：对异常数据进行特殊处理

加密问题

• 密钥验证：确认使用的密钥是否正确
• 算法兼容性：检查加密算法的兼容性
• 性能问题：监控加密操作的性能表现

调试技巧

日志记录

• 关键操作日志：记录重要的存储操作
• 错误日志：详细记录存储操作中的错误
• 性能日志：记录存储操作的性能指标

监控工具

• 浏览器开发者工具：使用开发者工具监控存储操作
• 性能分析器：使用性能分析器分析存储性能
• 日志分析：定期分析存储相关的日志

章节来源

• TsCommon.js:34-44
• TsStorage.js:31-43

结论

TsStorage 模块提供了一个功能完整、配置灵活的存储解决方案。通过本文档的详细说明，您可以：

1. 正确配置存储选项：理解存储前缀、加密开关和存储策略的配置方法
2. 优化存储性能：掌握性能优化的最佳实践和注意事项
3. 确保存储安全：实施有效的安全措施和最佳实践
4. 制定迁移策略：规划数据迁移和备份的完整方案
5. 有效调试监控：建立完善的调试和监控体系

该模块的设计充分考虑了实际应用场景的需求，在保证功能完整性的同时，也注重了性能和安全性的平衡。通过合理配置和使用，可以满足大多数应用的存储需求。

附录

配置参考表

配置项	类型	默认值	描述
base64Key	string	WmdUzPJXbngVNiaSsQrihg==	加密密钥（Base64编码）
prefix	string	""	存储键前缀
encrypt_body	boolean	true	是否启用数据加密
token	string	""	用户令牌存储

使用示例路径

• 基础存储操作:31-43
• 用户令牌管理:9-15
• 加密开关配置:17-23
• 全局配置管理:19-29