feat(storage): 增加文件内容校验与存储完整性巡检

[Cloudwhile]

Issue

Closes #50

背景

现有存储对账只能发现对象缺失、孤立对象等问题，无法识别对象大小不变但内容已经损坏的情况。

本次改动为当前文件和历史版本增加独立的 SHA-256 完整性元数据，并提供异步巡检、渐进式回填、异常处理、管理后台及审计能力。

主要改动

文件完整性元数据

• 为 FileNode 和 FileVersion 分别保存：
  • 校验算法与 SHA-256 校验值
  • 完整性状态
  • 最近校验时间
  • 校验失败代码
  • 管理员确认信息
• 新上传或替换的对象先标记为 pending，随后异步计算校验和。
• 历史版本保留自己的校验和，不复用当前文件的完整性数据。
• 文件覆盖、版本创建、恢复和复制流程会正确迁移或重新生成完整性状态。

存储巡检任务

• 支持以下巡检模式：
  • 回填缺失校验和
  • 重新验证已有校验和
  • 全局巡检
  • 工作区巡检
  • 单文件及单版本巡检
• 支持批量大小、并发数、读取带宽和最大重试次数配置。
• 增加任务进度、游标、租约、互斥和失败恢复机制。
• 支持重新执行失败任务或只重试指定异常结果。
• 服务重启后可继续处理已排队或中断的任务。

异常识别

巡检会结构化识别：

• missing-object：存储对象不存在
• size-mismatch：对象实际大小与记录不符
• checksum-mismatch：对象内容 SHA-256 不一致
• verification-failed：对象读取或校验失败

内容不匹配只会被标记、告警和记录审计，不会自动删除对象。未确认的异常历史版本也不会被版本清理任务删除。

本地存储与 S3/MinIO

• 使用流式读取计算 SHA-256，避免将大文件一次性载入内存。
• S3/MinIO 路径通过 GetObject 内容计算校验和。
• 不将 ETag 作为 SHA-256，兼容分片上传和不同 S3 实现。
• 支持中止正在进行的读取和共享带宽限制。

管理后台

• 增加存储完整性管理面板。
• 展示待校验、已验证、不匹配、失败和未知状态数量。
• 支持全局与工作区范围切换。
• 支持选择文件和历史版本发起巡检。
• 展示对象 Key、文件节点、版本、期望值、实际值、大小和最近校验时间。
• 支持重试异常结果和管理员确认。
• 完善任务历史、执行进度、异常详情和状态提示。

审计

新增以下关键操作与异常审计：

• 巡检开始、完成及失败
• 内容不匹配和读取失败
• 任务重试
• 管理员确认异常

审计记录不会包含完整对象内容、原始哈希或未经处理的底层错误信息。

配套修复

• 修复文件层级写入、上传完成和版本操作的事务一致性。
• 修复 OAuth Step-up 回调处理。
• OAuth 交换码改为原子消费，避免并发重复使用。
• 优化管理员面板和 OAuth 配置界面。
• 将应用图标统一迁移至 Reicon。
• 精简空目录状态，修复工作空间图标尺寸及工具栏显示逻辑。

数据库变更

新增迁移：

• 20260813120000_storage_object_integrity
• 20260813123000_blob_integrity_tasks
• 20260813124000_file_node_parent_integrity

部署时需要执行数据库迁移。

已有文件不会在迁移后立即触发全量读取，可通过管理后台任务渐进式回填校验和。

验证结果

• 后端构建通过
• Issue [Feature] 增加文件内容校验和与存储完整性巡检 #50 聚焦测试：70 项通过
• OAuth 后端测试：32 项通过
• 前端单元测试：466 项通过
• 前端构建通过
• ESLint：0 错误
• Playwright 空目录及空间图标回归通过
• 管理员与 OAuth 浏览器回归通过
• 本地文件真实流式校验测试覆盖
• SQLite 任务生命周期测试覆盖
• CI 已配置真实 MinIO 分片上传校验测试

建议重点审查

• 上传完成、版本归档及恢复时的事务边界
• 任务租约、恢复、重试和互斥逻辑
• S3/MinIO 流式读取及 ETag 处理
• 异常版本的清理保护规则
• 管理后台范围权限与任务目标选择

[coderabbitai]

Important

Review skipped

Too many files!

This PR contains 112 files, which is 12 over the limit of 100.

To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch.

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 5fe3e891-ceb1-4d13-a077-34ec1bdd09ce

📥 Commits

Reviewing files that changed from the base of the PR and between 0139a44 and 9742cf4.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (112)

• .github/workflows/ci.yml
• .gitignore
• backend/src/app.module.ts
• backend/src/database/file-node-parent-integrity.spec.ts
• backend/src/database/prisma.service.spec.ts
• backend/src/database/prisma.service.ts
• backend/src/main.ts
• backend/src/modules/admin/storage-integrity/storage-integrity.controller.spec.ts
• backend/src/modules/admin/storage-integrity/storage-integrity.controller.ts
• backend/src/modules/admin/storage-integrity/storage-integrity.module.ts
• backend/src/modules/auth/core/auth.dto.ts
• backend/src/modules/auth/core/auth.repository.spec.ts
• backend/src/modules/auth/core/auth.repository.ts
• backend/src/modules/auth/core/auth.service.spec.ts
• backend/src/modules/auth/core/auth.service.ts
• backend/src/modules/files/file-download-preview.service.spec.ts
• backend/src/modules/files/file-integrity.spec.ts
• backend/src/modules/files/file-integrity.ts
• backend/src/modules/files/file-node-hierarchy-write.spec.ts
• backend/src/modules/files/file-node-hierarchy-write.ts
• backend/src/modules/files/file-node-public-response.spec.ts
• backend/src/modules/files/file-node-public-response.ts
• backend/src/modules/files/file-node-versions.repository.spec.ts
• backend/src/modules/files/file-node-versions.repository.ts
• backend/src/modules/files/file-nodes.dto.ts
• backend/src/modules/files/file-nodes.repository.spec-helpers.ts
• backend/src/modules/files/file-nodes.repository.spec.ts
• backend/src/modules/files/file-nodes.repository.ts
• backend/src/modules/files/file-nodes.repository.upload.spec.ts
• backend/src/modules/files/file-nodes.service.spec.ts
• backend/src/modules/files/file-nodes.service.ts
• backend/src/modules/files/file-upload-completion-write.spec.ts
• backend/src/modules/files/file-upload-completion-write.ts
• backend/src/modules/files/file-upload-test-fixtures.helper.ts
• backend/src/modules/files/file-upload-test-repository.helper.ts
• backend/src/modules/files/file-upload.service.ts
• backend/src/modules/logs/audit-events.ts
• backend/src/modules/shares/shares.service.spec-harness.ts
• backend/src/modules/storage/storage-integrity-acknowledgement.repository.spec.ts
• backend/src/modules/storage/storage-integrity-acknowledgement.repository.ts
• backend/src/modules/storage/storage-integrity-acknowledgement.service.spec.ts
• backend/src/modules/storage/storage-integrity-acknowledgement.service.ts
• backend/src/modules/storage/storage-integrity-audit.ts
• backend/src/modules/storage/storage-integrity-result.ts
• backend/src/modules/storage/storage-integrity-target.repository.ts
• backend/src/modules/storage/storage-integrity-task-runner.service.spec.ts
• backend/src/modules/storage/storage-integrity-task-runner.service.ts
• backend/src/modules/storage/storage-integrity-task.audit.spec.ts
• backend/src/modules/storage/storage-integrity-task.dto.spec.ts
• backend/src/modules/storage/storage-integrity-task.dto.ts
• backend/src/modules/storage/storage-integrity-task.repository.spec.ts
• backend/src/modules/storage/storage-integrity-task.repository.sqlite-lifecycle.spec.ts
• backend/src/modules/storage/storage-integrity-task.repository.sqlite.spec.ts
• backend/src/modules/storage/storage-integrity-task.repository.ts
• backend/src/modules/storage/storage-integrity-task.service.spec.ts
• backend/src/modules/storage/storage-integrity-task.service.ts
• backend/src/modules/storage/storage-integrity-task.types.ts
• backend/src/modules/storage/storage-integrity.minio.spec.ts
• backend/src/modules/storage/storage-integrity.service.spec.ts
• backend/src/modules/storage/storage-integrity.service.ts
• backend/src/modules/storage/storage-object.service.spec.ts
• backend/src/modules/storage/storage-object.service.ts
• backend/src/modules/storage/storage.module.ts
• backend/src/modules/storage/storage.service.ts
• database/migrations/20260813120000_storage_object_integrity/migration.sql
• database/migrations/20260813123000_blob_integrity_tasks/migration.sql
• database/migrations/20260813124000_file_node_parent_integrity/migration.sql
• database/schema.prisma
• frontend/package.json
• frontend/src/components/admin/admin-scope-selector.css
• frontend/src/components/admin/admin-scope-selector.test.tsx
• frontend/src/components/admin/admin-scope-selector.tsx
• frontend/src/components/admin/admin-storage-integrity-panel.css
• frontend/src/components/admin/admin-storage-integrity-panel.test.tsx
• frontend/src/components/admin/admin-storage-integrity-panel.tsx
• frontend/src/components/admin/admin-storage-integrity-target.css
• frontend/src/components/admin/admin-storage-integrity-target.test.tsx
• frontend/src/components/admin/admin-storage-integrity-target.tsx
• frontend/src/components/drive/file-collection-state.test.tsx
• frontend/src/components/drive/file-collection-state.tsx
• frontend/src/components/oauth/oauth-admin-parts.tsx
• frontend/src/components/oauth/oauth-provider-dialog.tsx
• frontend/src/components/ui/app-icon.tsx
• frontend/src/features/admin/admin-routes.test.ts
• frontend/src/features/admin/admin-routes.ts
• frontend/src/features/admin/storage-integrity-colors.ts
• frontend/src/features/admin/use-storage-integrity.test.tsx
• frontend/src/features/admin/use-storage-integrity.ts
• frontend/src/i18n/admin-scope-messages.test.ts
• frontend/src/i18n/locales/en_US.tsln
• frontend/src/i18n/locales/zh_CN.tsln
• frontend/src/lib/drive-api-admin-types.ts
• frontend/src/lib/drive-api-admin.test.ts
• frontend/src/lib/drive-api-admin.ts
• frontend/src/lib/drive-api-auth-settings.ts
• frontend/src/lib/drive-api-types.ts
• frontend/src/views/drive/admin-app.tsx
• frontend/src/views/drive/drive-files.test.tsx
• frontend/src/views/drive/drive-files.tsx
• frontend/src/views/drive/drive-layout.test.tsx
• frontend/src/views/drive/drive-layout.tsx
• frontend/src/views/drive/drive-oauth-admin-settings.test.tsx
• frontend/src/views/drive/drive-oauth-admin-settings.tsx
• frontend/src/views/drive/drive-workbench.tsx
• frontend/src/views/drive/oauth-callback-client.test.tsx
• frontend/src/views/drive/oauth-callback-client.tsx
• frontend/src/views/drive/styles/admin-oauth.css
• frontend/src/views/drive/styles/admin.css
• frontend/src/views/drive/styles/sidebar.css
• frontend/tests/e2e/admin-oauth-visual.spec.ts
• frontend/tests/e2e/drive-responsive.spec.ts
• frontend/tests/e2e/storage-integrity.spec.ts

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}