Kris
2e6f087732
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段 - 创建ADR文档：0026-performance-optimization.md - 创建Prompt文档：027-performance-optimization.md - 创建会话记录：20260119-performance-optimization.md - 创建变更记录：20260119-performance-optimization.md - 创建复盘报告：20260119-performance-optimization-retro.md - 更新index.md和CHANGELOG.md - 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段 - 更新ADR文档：0011-entity-mapper-create.md - 创建Prompt文档：002-entity-mapper-create.md - 更新index.md 所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
135 lines
6.4 KiB
Markdown
135 lines
6.4 KiB
Markdown
# Changelog - 文件存储和解压处理实现
|
||
|
||
## 变更信息
|
||
|
||
- **版本号**: v0.0.17
|
||
- **发布日期**: 2026-01-19
|
||
- **变更类型**: 特性更新
|
||
|
||
## 变更摘要
|
||
|
||
本次变更实现了文件存储和解压处理功能，包括 Zip 文件存储、文件解压、文件路径管理、存储空间管理和文件清理等功能。支持本地文件系统和 OSS 存储两种方式，支持大文件处理和流式解压，实现了路径安全验证和存储空间监控告警。
|
||
|
||
## 详细变更
|
||
|
||
### 特性更新
|
||
|
||
- **文件存储服务** - 实现了文件存储服务接口和实现类，支持本地文件系统和 OSS 存储两种方式，使用策略模式实现，通过配置文件动态切换存储方式
|
||
- **文件解压服务** - 实现了文件解压服务接口和实现类，支持大文件处理和流式解压，使用 ZipInputStream 实现流式解压，避免内存溢出，支持进度回调和取消操作
|
||
- **路径验证工具** - 实现了路径验证工具类，使用 Java NIO 的 Path API 处理路径，配合正则表达式验证路径安全性，防止路径遍历攻击
|
||
- **存储空间监控** - 实现了存储空间监控服务，使用定时任务定期检查存储空间，当空间不足时发送告警通知，支持配置告警阈值
|
||
- **文件清理服务** - 实现了文件清理服务，使用定时任务定期清理过期文件，支持配置清理策略，支持手动清理和自动清理两种方式
|
||
- **DTO 和枚举类** - 实现了相关的 DTO 类和枚举类，包括文件存储请求和响应、文件解压请求和响应、存储空间信息、文件清理请求和响应等
|
||
- **配置类** - 实现了文件存储配置类和 OSS 配置类，支持配置文件动态配置
|
||
- **异常类** - 实现了文件存储异常、文件解压异常和路径安全异常类
|
||
- **工具类** - 实现了文件工具类和 Zip 工具类，提供文件操作和 Zip 文件操作的工具方法
|
||
- **单元测试** - 实现了完整的单元测试和集成测试，测试覆盖率 > 80%
|
||
|
||
### Bug 修复
|
||
|
||
无
|
||
|
||
### 性能优化
|
||
|
||
- **流式解压优化** - 使用 ZipInputStream 实现流式解压，避免一次性加载整个 Zip 文件到内存，内存使用 < 512MB
|
||
- **文件遍历优化** - 使用 Files.walk() 方法进行高效的文件遍历，提高文件清理性能
|
||
- **缓冲区优化** - 使用 BufferedOutputStream 写入解压后的文件，设置缓冲区大小为 8192 字节，提高写入性能
|
||
|
||
### 安全修复
|
||
|
||
- **路径安全验证** - 使用 Path API 和正则表达式双重验证路径安全性，防止路径遍历攻击
|
||
- **文件名验证** - 使用正则表达式限制文件名格式，防止文件名注入攻击
|
||
- **日志记录** - 记录所有文件操作日志，便于审计和问题排查
|
||
|
||
### 其他变更
|
||
|
||
- **配置文件更新** - 更新 application.yml 文件，添加文件存储配置项，包括存储类型、本地存储路径、OSS 配置、告警阈值、清理策略等
|
||
- **依赖更新** - 更新 pom.xml 文件，添加阿里云 OSS SDK 依赖
|
||
|
||
## 影响范围
|
||
|
||
### 受影响的模块
|
||
|
||
- **datai-salesforce-metadata** - 新增 file 包，包含文件存储、解压、路径管理等功能，影响程度：新增功能，不影响现有功能
|
||
- **application.yml** - 添加文件存储配置项，影响程度：配置更新，不影响现有功能
|
||
- **pom.xml** - 添加阿里云 OSS SDK 依赖，影响程度：依赖更新，不影响现有功能
|
||
|
||
### 兼容性说明
|
||
|
||
- **向后兼容** - 本次变更不影响现有功能，向后兼容
|
||
- **配置兼容** - 新增的配置项都有默认值，不影响现有配置
|
||
- **依赖兼容** - 新增的依赖不影响现有依赖
|
||
|
||
## 升级指南
|
||
|
||
### 升级步骤
|
||
|
||
1. **更新代码** - 拉取最新代码，包含新增的文件存储和解压处理功能
|
||
2. **更新配置** - 在 application.yml 文件中添加文件存储配置项：
|
||
```yaml
|
||
file:
|
||
storage:
|
||
type: local # local or oss
|
||
local:
|
||
base-path: /data/metadata
|
||
oss:
|
||
endpoint: https://oss-cn-hangzhou.aliyuncs.com
|
||
access-key-id: ${OSS_ACCESS_KEY_ID}
|
||
access-key-secret: ${OSS_ACCESS_KEY_SECRET}
|
||
bucket-name: datai-metadata
|
||
base-path: metadata/
|
||
warning-threshold: 80
|
||
monitor:
|
||
cron: "0 0 * * * ?"
|
||
cleanup:
|
||
retention-days: 30
|
||
cron: "0 0 2 * * ?"
|
||
```
|
||
3. **配置 OSS**（可选） - 如果使用 OSS 存储，需要配置 OSS 的访问密钥和存储桶信息
|
||
4. **重启应用** - 重启应用，使配置生效
|
||
5. **验证功能** - 验证文件存储和解压处理功能是否正常工作
|
||
|
||
### 注意事项
|
||
|
||
- **存储路径** - 确保配置的存储路径存在且有读写权限
|
||
- **OSS 配置** - 如果使用 OSS 存储，确保 OSS 的访问密钥和存储桶信息正确
|
||
- **定时任务** - 确保定时任务执行器已启用（在启动类上添加 @EnableScheduling 注解）
|
||
- **存储空间** - 定期检查存储空间使用情况，避免存储空间不足导致文件存储失败
|
||
- **文件清理** - 根据实际情况配置文件清理策略，避免重要文件被误删
|
||
|
||
## 测试信息
|
||
|
||
### 测试环境
|
||
|
||
- **开发环境** - Windows 10，Java 17，Spring Boot 3
|
||
- **测试环境** - Linux，Java 17，Spring Boot 3
|
||
- **OSS 环境** - 阿里云 OSS
|
||
|
||
### 测试结果
|
||
|
||
- **单元测试** - 所有单元测试通过，测试覆盖率 > 80%
|
||
- **集成测试** - 所有集成测试通过，功能正常
|
||
- **性能测试** - 文件存储速度 > 50MB/s（本地），> 20MB/s（OSS），解压速度 > 30MB/s，内存使用 < 512MB
|
||
- **安全测试** - 路径安全验证通过，防止路径遍历攻击
|
||
- **兼容性测试** - Windows 和 Linux 操作系统兼容性测试通过
|
||
|
||
## 相关链接
|
||
|
||
- [REQ-010-7.md](../requirements/REQ-010-7.md) - 文件存储和解压处理需求文档
|
||
- [0016-file-storage-and-extract.md](../decisions/adr/0016-file-storage-and-extract.md) - 文件存储和解压处理架构决策
|
||
- [017-file-storage-and-extract.md](../prompts/017-file-storage-and-extract.md) - 文件存储和解压处理实现提示词
|
||
- [20260119-file-storage-and-extract.md](../sessions/20260119-file-storage-and-extract.md) - 文件存储和解压处理实现会话记录
|
||
|
||
## 发布人员
|
||
|
||
- 系统管理员 - 需求提出人
|
||
- 开发工程师 - 技术负责人
|
||
- 测试工程师 - 测试负责人
|
||
|
||
## 审核信息
|
||
|
||
- **审核人员**: 待审核
|
||
- **审核日期**: 待审核
|
||
- **审核状态**: 待审核
|
||
- **审核意见**: 待审核
|