+
+ );
+}
+
+// 格式化文件大小
+function formatFileSize(bytes: number): string {
+ if (bytes === 0) return '0 Bytes';
+ const k = 1024;
+ const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+ const i = Math.floor(Math.log(bytes) / Math.log(k));
+ return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
diff --git a/apps/web/components/DownloadTester.tsx b/apps/web/components/DownloadTester.tsx
new file mode 100644
index 0000000..aa472b2
--- /dev/null
+++ b/apps/web/components/DownloadTester.tsx
@@ -0,0 +1,90 @@
+import React, { useState } from 'react';
+import { useTusUpload } from '../hooks/useTusUpload';
+
+export function DownloadTester() {
+ const { serverUrl, getFileInfo } = useTusUpload();
+ const [fileId, setFileId] = useState('2025/05/28/1mVGC8r6jy');
+ const [testResults, setTestResults] = useState高级文件下载
+ + {/* 文件ID输入 */} +
+
+
+
+ {/* 错误信息 */}
+ {(error || downloadError) && (
+
+ setFileId(e.target.value)}
+ placeholder="输入文件ID"
+ className="flex-1 px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+ />
+
+
+
+ {error || downloadError}
+
+ )}
+
+ {/* 下载进度 */}
+ {isDownloading && downloadProgress && (
+
+
+ )}
+
+ {/* 文件信息 */}
+ {fileInfo && (
+
+ 下载进度
+ {downloadProgress.percentage}%
+
+
+
+
+
+ {formatFileSize(downloadProgress.loaded)} / {formatFileSize(downloadProgress.total)}
+
+
+
+ )}
+
+ {/* 操作按钮 */}
+ {fileInfo && (
+
+ {getFileIcon(fileInfo.type || '')}
+
+
+
+
+ {fileInfo.title || '未知文件'}
+{fileInfo.type || '未知类型'}
+
+
+
+ 状态:
+
+ {fileInfo.status || '未知'}
+
+
+ {fileInfo.meta?.size && (
+
+ 大小: {formatFileSize(fileInfo.meta.size)}
+
+ )}
+
+ 创建时间: {new Date(fileInfo.createdAt).toLocaleString()}
+
+
+ 存储类型: {fileInfo.storageType || '未知'}
+
+
+
+ )}
+
+ {/* 使用说明 */}
+
+
+
+ {canPreview(fileInfo.type || '') && (
+
+ )}
+
+
+
+ {/* 文件预览提示 */}
+ {canPreview(fileInfo.type || '') && (
+
+
+ )}
+ 💡 此文件支持在线预览，点击"预览文件"可以在浏览器中直接查看
+
+
+ 功能说明：
+-
+
- + • 快速下载：直接通过浏览器下载文件 + +
- + • 进度下载：显示下载进度，适合大文件 + +
- + • 预览文件：图片、PDF、视频等可在线预览 + +
- + • 复制链接：复制文件访问链接到剪贴板 + +
+
+ );
+}
diff --git a/apps/web/components/FileDownload.tsx b/apps/web/components/FileDownload.tsx
new file mode 100644
index 0000000..3e9b544
--- /dev/null
+++ b/apps/web/components/FileDownload.tsx
@@ -0,0 +1,157 @@
+import React, { useState } from 'react';
+import { useTusUpload } from '../hooks/useTusUpload';
+
+interface FileDownloadProps {
+ fileId?: string;
+ fileName?: string;
+ className?: string;
+}
+
+export function FileDownload({ fileId, fileName, className }: FileDownloadProps) {
+ const { getFileUrlByFileId, getFileInfo } = useTusUpload();
+ const [inputFileId, setInputFileId] = useState(fileId || '');
+ const [fileInfo, setFileInfo] = useState🔧 下载功能测试
+ +
+
+
+
+ {testResults && (
+
+ setFileId(e.target.value)}
+ className="flex-1 px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+ />
+
+
+
+
+ )}
+
+
+ 测试结果
+
+ {JSON.stringify(testResults, null, 2)}
+
+
+
+ );
+}
+
+// 格式化文件大小
+function formatFileSize(bytes: number): string {
+ if (bytes === 0) return '0 Bytes';
+ const k = 1024;
+ const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+ const i = Math.floor(Math.log(bytes) / Math.log(k));
+ return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
diff --git a/apps/web/components/FileUpload.tsx b/apps/web/components/FileUpload.tsx
new file mode 100644
index 0000000..ce8670d
--- /dev/null
+++ b/apps/web/components/FileUpload.tsx
@@ -0,0 +1,218 @@
+'use client';
+import React, { useCallback, useState } from 'react';
+import { useTusUpload } from '../hooks/useTusUpload';
+
+interface UploadedFile {
+ fileId: string;
+ fileName: string;
+ url: string;
+}
+
+export function FileUpload() {
+ const { uploadProgress, isUploading, uploadError, handleFileUpload, getFileUrlByFileId, serverUrl } = useTusUpload();
+
+ const [uploadedFiles, setUploadedFiles] = useState文件下载
+ + {/* 文件ID输入 */} +
+
+
+
+ {/* 错误信息 */}
+ {error &&
+ setInputFileId(e.target.value)}
+ placeholder="输入文件ID"
+ className="flex-1 px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+ />
+
+
+ {error}
}
+
+ {/* 文件信息 */}
+ {fileInfo && (
+
+
+ )}
+
+ {/* 操作按钮 */}
+ {inputFileId && (
+ 文件信息
+
+
+ + 文件名: {fileInfo.title || '未知'} +
++ 类型: {fileInfo.type || '未知'} +
++ 状态: {fileInfo.status || '未知'} +
+ {fileInfo.meta?.size && ( ++ 大小: {formatFileSize(fileInfo.meta.size)} +
+ )} ++ 创建时间: {new Date(fileInfo.createdAt).toLocaleString()} +
+
+
+
+
+
+ )}
+
+ {/* 使用说明 */}
+
+
+ 使用说明：
+-
+
- • 输入文件ID后点击"查询"获取文件信息 +
- • "直接下载"会打开新窗口下载文件 +
- • "预览/查看"适用于图片、PDF等可预览的文件 +
- • "复制链接"将下载地址复制到剪贴板 +
+
+ );
+}
diff --git a/apps/web/components/SimpleUploadExample.tsx b/apps/web/components/SimpleUploadExample.tsx
new file mode 100644
index 0000000..f5eb1d9
--- /dev/null
+++ b/apps/web/components/SimpleUploadExample.tsx
@@ -0,0 +1,75 @@
+import React, { useState } from 'react';
+import { useTusUpload } from '../hooks/useTusUpload';
+
+export function SimpleUploadExample() {
+ const { uploadProgress, isUploading, uploadError, handleFileUpload, getFileUrlByFileId } = useTusUpload();
+ const [uploadedFileUrl, setUploadedFileUrl] = useState文件上传
+ + {/* 服务器信息 */} +
+
+
+ {/* 拖拽上传区域 */}
+ + 服务器地址: {serverUrl} +
+
+
+
+ {/* 上传进度 */}
+ {isUploading && (
+
+
+
+
+
+
+
+ 拖拽文件到这里，或者
+ +支持多文件上传，TUS 协议支持断点续传
+
+
+ )}
+
+ {/* 错误信息 */}
+ {uploadError && (
+
+ 上传中...
+ {uploadProgress}%
+
+
+
+
+
+
+ )}
+
+ {/* 已上传文件列表 */}
+ {uploadedFiles.length > 0 && (
+ + 上传失败： + {uploadError} +
+
+
+ )}
+
+ {/* 使用说明 */}
+ 已上传文件
+
+ {uploadedFiles.map((file, index) => (
+
+
+
+ ))}
+
+
+
+
+
+
+
+ {file.fileName}
+文件ID: {file.fileId}
+
+
+ 查看
+
+
+
+
+
+ 使用说明：
+-
+
- • 支持拖拽和点击上传 +
- • 使用 TUS 协议，支持大文件和断点续传 +
- • 上传完成后可以通过链接直接访问文件 +
- • 图片和 PDF 会在浏览器中直接显示 +
- • 其他文件类型会触发下载 +
+
+ );
+}
diff --git a/apps/web/docs/UPLOAD_HOOK_USAGE.md b/apps/web/docs/UPLOAD_HOOK_USAGE.md
new file mode 100644
index 0000000..c3f27c0
--- /dev/null
+++ b/apps/web/docs/UPLOAD_HOOK_USAGE.md
@@ -0,0 +1,287 @@
+# TUS 上传 Hook 使用指南
+
+## 概述
+
+`useTusUpload` 是一个自定义 React Hook，提供了基于 TUS 协议的文件上传功能，支持大文件上传、断点续传、进度跟踪等特性。
+
+## 环境变量配置
+
+确保在 `.env` 文件中配置了以下环境变量：
+
+```env
+NEXT_PUBLIC_SERVER_PORT=3000
+NEXT_PUBLIC_SERVER_IP=http://localhost
+```
+
+**注意**：在 Next.js 中，客户端组件只能访问以 `NEXT_PUBLIC_` 开头的环境变量。
+
+## Hook API
+
+### 返回值
+
+```typescript
+const {
+ uploadProgress, // 上传进度 (0-100)
+ isUploading, // 是否正在上传
+ uploadError, // 上传错误信息
+ handleFileUpload, // 文件上传函数
+ getFileUrlByFileId, // 根据文件ID获取访问链接
+ getFileInfo, // 获取文件详细信息
+ getUploadStatus, // 获取上传状态
+ serverUrl, // 服务器地址
+} = useTusUpload();
+```
+
+### 主要方法
+
+#### `handleFileUpload(file, onSuccess?, onError?)`
+
+上传文件的主要方法。
+
+**参数：**
+
+- `file: File` - 要上传的文件对象
+- `onSuccess?: (result: UploadResult) => void` - 成功回调
+- `onError?: (error: string) => void` - 失败回调
+
+**返回：** `Promise简单上传示例
+ +
+
+
+
+ {isUploading && (
+
+
+ )}
+
+ {uploadError && (
+
+ 上传进度
+ {uploadProgress}%
+
+
+
+
+ {uploadError}
+ )}
+
+ {uploadedFileUrl && (
+
+
+ )}
+ 上传成功！
+ + 查看文件 + +
+
+
+ {isUploading && (
+
+ );
+}
+```
+
+### 拖拽上传
+
+```tsx
+import React, { useCallback, useState } from 'react';
+import { useTusUpload } from '../hooks/useTusUpload';
+
+function DragDropUpload() {
+ const { handleFileUpload, isUploading, uploadProgress } = useTusUpload();
+ const [dragOver, setDragOver] = useState(false);
+
+ const handleDrop = useCallback(
+ async (e: React.DragEvent) => {
+ e.preventDefault();
+ setDragOver(false);
+
+ const files = e.dataTransfer.files;
+ if (files.length > 0) {
+ await handleFileUpload(files[0]);
+ }
+ },
+ [handleFileUpload],
+ );
+
+ const handleDragOver = useCallback((e: React.DragEvent) => {
+ e.preventDefault();
+ setDragOver(true);
+ }, []);
+
+ return (
+
+
+ )}
+
+ {uploadError && 上传进度: {uploadProgress}%
+ +{uploadError}
} + + {uploadedUrl && ( + + 查看上传的文件 + + )} + setDragOver(false)}
+ style={{
+ border: dragOver ? '2px dashed #0070f3' : '2px dashed #ccc',
+ padding: '20px',
+ textAlign: 'center',
+ backgroundColor: dragOver ? '#f0f8ff' : '#fafafa',
+ }}
+ >
+ {isUploading ?
+ );
+}
+```
+
+### 多文件上传
+
+```tsx
+function MultiFileUpload() {
+ const { handleFileUpload } = useTusUpload();
+ const [uploadingFiles, setUploadingFiles] = useState上传中... {uploadProgress}%
:拖拽文件到这里上传
} +
+
+
+ {uploadingFiles.size > 0 && (
+
+ );
+}
+```
+
+## 特性
+
+### 1. 断点续传
+
+TUS 协议支持断点续传，如果上传过程中断，可以从中断的地方继续上传。
+
+### 2. 大文件支持
+
+适合上传大文件，没有文件大小限制（取决于服务器配置）。
+
+### 3. 进度跟踪
+
+实时显示上传进度，提供良好的用户体验。
+
+### 4. 错误处理
+
+提供详细的错误信息和重试机制。
+
+### 5. 自动重试
+
+内置重试机制，网络异常时自动重试。
+
+## 故障排除
+
+### 1. 环境变量获取不到
+
+确保环境变量以 `NEXT_PUBLIC_` 开头，并且 Next.js 应用已重启。
+
+### 2. 上传失败
+
+检查服务器是否正在运行，端口是否正确。
+
+### 3. CORS 错误
+
+确保后端服务器配置了正确的 CORS 设置。
+
+### 4. 文件无法访问
+
+确认文件上传成功后，检查返回的 URL 是否正确。
+
+## 注意事项
+
+1. **Next.js 环境变量**：客户端组件只能访问 `NEXT_PUBLIC_` 前缀的环境变量
+2. **服务器配置**：确保后端服务器支持 TUS 协议
+3. **文件大小**：虽然支持大文件，但要注意服务器和客户端的内存限制
+4. **网络环境**：在网络不稳定的环境下，断点续传功能特别有用
+
+## API 路由
+
+Hook 会访问以下 API 路由：
+
+- `POST /upload` - TUS 上传端点
+- `GET /download/:fileId` - 文件下载/访问
+- `GET /api/storage/resource/:fileId` - 获取文件信息
+- `HEAD /upload/:fileId` - 获取上传状态
diff --git a/apps/web/hooks/useFileDownload.ts b/apps/web/hooks/useFileDownload.ts
new file mode 100644
index 0000000..4379a4b
--- /dev/null
+++ b/apps/web/hooks/useFileDownload.ts
@@ -0,0 +1,180 @@
+import { useState } from 'react';
+import { useTusUpload } from './useTusUpload';
+
+interface DownloadProgress {
+ loaded: number;
+ total: number;
+ percentage: number;
+}
+
+export function useFileDownload() {
+ const { getFileUrlByFileId, serverUrl } = useTusUpload();
+ const [downloadProgress, setDownloadProgress] = useState
+
+ )}
+ 正在上传的文件:
+ {Array.from(uploadingFiles.entries()).map(([fileId, progress]) => ( +
+ {fileId}: {progress}%
+
+ ))}
+ Loading...
;
+
+ return (
+
+ );
+}
+```
+
+### 文件类型处理
+
+```typescript
+function getFileDisplayUrl(fileId: string, mimeType: string) {
+ const baseUrl = `/download/${fileId}`;
+
+ // 根据文件类型决定显示方式
+ if (mimeType.startsWith('image/')) {
+ // 图片直接显示
+ return baseUrl;
+ } else if (mimeType === 'application/pdf') {
+ // PDF 可以内联显示
+ return baseUrl;
+ } else {
+ // 其他文件类型强制下载
+ return `${baseUrl}?download=true`;
+ }
+}
+```
+
+## 安全考虑
+
+### 1. 访问控制
+
+如需要权限验证，可以添加认证中间件：
+
+```typescript
+import { createFileDownloadRoutes } from '@repo/storage';
+
+const app = new Hono();
+
+// 添加认证中间件
+app.use('/download/*', async (c, next) => {
+ // 检查用户权限
+ const token = c.req.header('Authorization');
+ if (!isValidToken(token)) {
+ return c.json({ error: 'Unauthorized' }, 401);
+ }
+ await next();
+});
+
+// 添加文件下载服务
+app.route('/download', createFileDownloadRoutes());
+```
+
+### 2. 文件类型限制
+
+```typescript
+app.use('/download/*', async (c, next) => {
+ const fileId = c.req.param('fileId');
+
+ // 从数据库获取文件信息
+ const { resource } = await getResourceByFileId(fileId);
+ if (!resource) {
+ return c.json({ error: 'File not found' }, 404);
+ }
+
+ // 检查文件类型
+ const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
+ if (!allowedTypes.includes(resource.mimeType)) {
+ return c.json({ error: 'File type not allowed' }, 403);
+ }
+
+ await next();
+});
+```
+
+## 性能优化
+
+### 1. 缓存设置
+
+```typescript
+app.use('/download/*', async (c, next) => {
+ await next();
+
+ // 设置缓存头
+ c.header('Cache-Control', 'public, max-age=31536000'); // 1年
+ c.header('ETag', generateETag(c.req.path));
+});
+```
+
+### 2. CDN 配置
+
+对于生产环境，建议使用 CDN：
+
+```typescript
+import { StorageUtils } from '@repo/storage';
+
+const storageUtils = StorageUtils.getInstance();
+
+// 使用 CDN 域名
+const cdnUrl = 'https://cdn.yourdomain.com';
+const fileUrl = storageUtils.generateFileUrl(fileId, cdnUrl);
+```
+
+## 故障排除
+
+### 常见问题
+
+1. **404 文件未找到**
+
+ - 检查文件是否存在于数据库
+ - 确认文件路径是否正确
+ - 检查文件权限（本地存储）
+
+2. **下载接口不工作**
+
+ - 检查路由配置
+ - 确认存储配置正确
+ - 查看服务器日志
+
+3. **S3 文件无法访问**
+ - 检查 S3 存储桶权限
+ - 确认文件是否上传成功
+ - 验证 S3 配置是否正确
+
+### 调试方法
+
+```bash
+# 检查文件是否存在
+curl -I http://localhost:3000/download/2024/01/01/abc123/file.jpg
+
+# 检查存储配置
+curl http://localhost:3000/api/storage/storage/info
+
+# 检查文件信息
+curl http://localhost:3000/api/storage/resource/2024/01/01/abc123/file.jpg
+```
diff --git a/env.example b/env.example
new file mode 100644
index 0000000..76e441e
--- /dev/null
+++ b/env.example
@@ -0,0 +1,71 @@
+# ===========================================
+# 存储配置 (@repo/storage)
+# ===========================================
+
+# 存储类型: local | s3
+STORAGE_TYPE=local
+
+# 上传文件过期时间（毫秒），0表示不过期
+UPLOAD_EXPIRATION_MS=0
+
+# ===========================================
+# 本地存储配置 (当 STORAGE_TYPE=local 时)
+# ===========================================
+
+# 本地存储目录路径
+UPLOAD_DIR=./uploads
+
+# ===========================================
+# S3 存储配置 (当 STORAGE_TYPE=s3 时)
+# ===========================================
+
+# S3 存储桶名称 (必需)
+S3_BUCKET=
+
+# S3 区域 (必需)
+S3_REGION=us-east-1
+
+# S3 访问密钥 ID (必需)
+S3_ACCESS_KEY_ID=
+
+# S3 访问密钥 (必需)
+S3_SECRET_ACCESS_KEY=
+
+# 自定义 S3 端点 (可选，用于 MinIO、阿里云 OSS 等)
+S3_ENDPOINT=
+
+# 是否强制使用路径样式 (可选)
+S3_FORCE_PATH_STYLE=false
+
+# 分片上传大小，单位字节 (可选，默认 8MB)
+S3_PART_SIZE=8388608
+
+# 最大并发上传数 (可选)
+S3_MAX_CONCURRENT_UPLOADS=60
+
+# ===========================================
+# 数据库配置
+# ===========================================
+
+# 数据库连接字符串
+DATABASE_URL="postgresql://username:password@localhost:5432/database"
+
+# ===========================================
+# Redis 配置
+# ===========================================
+
+# Redis 连接字符串
+REDIS_URL="redis://localhost:6379"
+
+# ===========================================
+# 应用配置
+# ===========================================
+
+# 应用端口
+PORT=3000
+
+# 应用环境
+NODE_ENV=development
+
+# CORS 允许的源
+CORS_ORIGIN=http://localhost:3001
\ No newline at end of file
diff --git a/packages/storage/.env.example b/packages/storage/.env.example
new file mode 100644
index 0000000..72f65dc
--- /dev/null
+++ b/packages/storage/.env.example
@@ -0,0 +1,3 @@
+STORAGE_TYPE=local
+UPLOAD_DIR=/opt/projects/nice/uploads
+UPLOAD_EXPIRATION_MS=0
\ No newline at end of file
diff --git a/packages/storage/README.md b/packages/storage/README.md
new file mode 100644
index 0000000..c5e4fc3
--- /dev/null
+++ b/packages/storage/README.md
@@ -0,0 +1,324 @@
+# @repo/storage
+
+一个完全兼容 Hono 的存储解决方案，支持本地存储和 S3 兼容存储，提供 TUS 协议上传、文件管理和 REST API。
+
+## 特性
+
+- 🚀 **多存储支持**: 支持本地文件系统和 S3 兼容存储
+- 📤 **TUS 协议**: 支持可恢复的文件上传
+- 🔧 **Hono 集成**: 提供开箱即用的 Hono 中间件
+- 📊 **文件管理**: 完整的文件生命周期管理
+- 🗄️ **数据库集成**: 与 Prisma 深度集成
+- ⏰ **自动清理**: 支持过期文件自动清理
+- 🔄 **存储迁移**: 支持不同存储类型间的数据迁移
+
+## 安装
+
+```bash
+npm install @repo/storage
+```
+
+## 环境变量配置
+
+### 基础配置
+
+| 变量名 | 类型 | 默认值 | 描述 |
+| ---------------------- | --------------- | ------- | ------------------------------------- |
+| `STORAGE_TYPE` | `local` \| `s3` | `local` | 存储类型选择 |
+| `UPLOAD_EXPIRATION_MS` | `number` | `0` | 上传文件过期时间（毫秒），0表示不过期 |
+
+### 本地存储配置
+
+当 `STORAGE_TYPE=local` 时需要配置：
+
+| 变量名 | 类型 | 默认值 | 描述 |
+| ------------ | -------- | ----------- | ---------------- |
+| `UPLOAD_DIR` | `string` | `./uploads` | 本地存储目录路径 |
+
+### S3 存储配置
+
+当 `STORAGE_TYPE=s3` 时需要配置：
+
+| 变量名 | 类型 | 默认值 | 描述 | 必需 |
+| --------------------------- | --------- | ----------- | ---------------------------------- | ---- |
+| `S3_BUCKET` | `string` | - | S3 存储桶名称 | ✅ |
+| `S3_REGION` | `string` | `us-east-1` | S3 区域 | ✅ |
+| `S3_ACCESS_KEY_ID` | `string` | - | S3 访问密钥 ID | ✅ |
+| `S3_SECRET_ACCESS_KEY` | `string` | - | S3 访问密钥 | ✅ |
+| `S3_ENDPOINT` | `string` | - | 自定义 S3 端点（用于兼容其他服务） | ❌ |
+| `S3_FORCE_PATH_STYLE` | `boolean` | `false` | 是否强制使用路径样式 | ❌ |
+| `S3_PART_SIZE` | `number` | `8388608` | 分片上传大小（8MB） | ❌ |
+| `S3_MAX_CONCURRENT_UPLOADS` | `number` | `60` | 最大并发上传数 | ❌ |
+
+## 配置示例
+
+### 本地存储配置
+
+```bash
+# .env
+STORAGE_TYPE=local
+UPLOAD_DIR=./uploads
+UPLOAD_EXPIRATION_MS=86400000 # 24小时过期
+```
+
+### AWS S3 配置
+
+```bash
+# .env
+STORAGE_TYPE=s3
+S3_BUCKET=my-app-uploads
+S3_REGION=us-west-2
+S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+UPLOAD_EXPIRATION_MS=604800000 # 7天过期
+```
+
+### MinIO 配置
+
+```bash
+# .env
+STORAGE_TYPE=s3
+S3_BUCKET=uploads
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=minioadmin
+S3_SECRET_ACCESS_KEY=minioadmin
+S3_ENDPOINT=http://localhost:9000
+S3_FORCE_PATH_STYLE=true
+```
+
+### 阿里云 OSS 配置
+
+```bash
+# .env
+STORAGE_TYPE=s3
+S3_BUCKET=my-oss-bucket
+S3_REGION=oss-cn-hangzhou
+S3_ACCESS_KEY_ID=your-access-key-id
+S3_SECRET_ACCESS_KEY=your-access-key-secret
+S3_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+S3_FORCE_PATH_STYLE=false
+```
+
+### 腾讯云 COS 配置
+
+```bash
+# .env
+STORAGE_TYPE=s3
+S3_BUCKET=my-cos-bucket-1234567890
+S3_REGION=ap-beijing
+S3_ACCESS_KEY_ID=your-secret-id
+S3_SECRET_ACCESS_KEY=your-secret-key
+S3_ENDPOINT=https://cos.ap-beijing.myqcloud.com
+S3_FORCE_PATH_STYLE=false
+```
+
+## 快速开始
+
+### 1. 基础使用
+
+```typescript
+import { createStorageApp, startCleanupScheduler } from '@repo/storage';
+import { Hono } from 'hono';
+
+const app = new Hono();
+
+// 创建存储应用
+const storageApp = createStorageApp({
+ apiBasePath: '/api/storage', // API 路径
+ uploadPath: '/upload', // 上传路径
+});
+
+// 挂载存储应用
+app.route('/', storageApp);
+
+// 启动清理调度器
+startCleanupScheduler();
+```
+
+### 2. 分别使用 API 和上传功能
+
+```typescript
+import { createStorageRoutes, createTusUploadRoutes } from '@repo/storage';
+
+const app = new Hono();
+
+// 只添加存储管理 API
+app.route('/api/storage', createStorageRoutes());
+
+// 只添加文件上传功能
+app.route('/upload', createTusUploadRoutes());
+```
+
+### 3. 使用存储管理器
+
+```typescript
+import { StorageManager, StorageUtils } from '@repo/storage';
+
+// 获取存储管理器实例
+const storageManager = StorageManager.getInstance();
+
+// 获取存储信息
+const storageInfo = storageManager.getStorageInfo();
+console.log('当前存储类型:', storageInfo.type);
+
+// 使用存储工具
+const storageUtils = StorageUtils.getInstance();
+
+// 生成文件访问 URL（统一使用下载接口）
+const fileUrl = storageUtils.generateFileUrl('2024/01/01/abc123/file.jpg');
+// 结果: http://localhost:3000/download/2024/01/01/abc123/file.jpg
+
+// 生成完整的公开访问 URL
+const publicUrl = storageUtils.generateFileUrl('2024/01/01/abc123/file.jpg', 'https://yourdomain.com');
+// 结果: https://yourdomain.com/download/2024/01/01/abc123/file.jpg
+
+// 生成 S3 直接访问 URL（仅 S3 存储）
+try {
+ const directUrl = storageUtils.generateDirectUrl('2024/01/01/abc123/file.jpg');
+ // S3 存储: https://bucket.s3.region.amazonaws.com/2024/01/01/abc123/file.jpg
+} catch (error) {
+ // 本地存储会抛出错误
+}
+
+// 检查文件是否存在
+const exists = await storageUtils.fileExists('file-id');
+```
+
+### 4. 分别配置不同功能
+
+```typescript
+import { createStorageRoutes, createTusUploadRoutes, createFileDownloadRoutes } from '@repo/storage';
+
+const app = new Hono();
+
+// 只添加存储管理 API
+app.route('/api/storage', createStorageRoutes());
+
+// 只添加文件上传功能
+app.route('/upload', createTusUploadRoutes());
+
+// 只添加文件下载功能（所有存储类型）
+app.route('/download', createFileDownloadRoutes());
+```
+
+## API 端点
+
+### 文件资源管理
+
+- `GET /api/storage/resource/:fileId` - 获取文件资源信息
+- `GET /api/storage/resources` - 获取所有资源
+- `GET /api/storage/resources/storage/:storageType` - 按存储类型获取资源
+- `GET /api/storage/resources/status/:status` - 按状态获取资源
+- `GET /api/storage/resources/uploading` - 获取正在上传的资源
+- `DELETE /api/storage/resource/:id` - 删除资源
+- `PATCH /api/storage/resource/:id` - 更新资源
+
+### 文件访问和下载
+
+- `GET /download/:fileId` - 文件下载和访问（支持所有存储类型）
+
+### 统计和管理
+
+- `GET /api/storage/stats` - 获取资源统计信息
+- `POST /api/storage/cleanup` - 手动清理过期上传
+- `POST /api/storage/cleanup/by-status` - 按状态清理资源
+- `POST /api/storage/migrate-storage` - 迁移存储类型
+
+### 存储配置
+
+- `GET /api/storage/storage/info` - 获取存储信息
+- `POST /api/storage/storage/switch` - 切换存储配置
+- `POST /api/storage/storage/validate` - 验证存储配置
+
+### 文件上传
+
+- `POST /upload` - TUS 协议文件上传
+- `PATCH /upload/:id` - 续传文件
+- `HEAD /upload/:id` - 获取上传状态
+
+## 数据库操作
+
+```typescript
+import {
+ getAllResources,
+ getResourceByFileId,
+ createResource,
+ updateResourceStatus,
+ deleteResource,
+} from '@repo/storage';
+
+// 获取所有资源
+const resources = await getAllResources();
+
+// 根据文件ID获取资源
+const { status, resource } = await getResourceByFileId('file-id');
+
+// 创建新资源
+const newResource = await createResource({
+ fileId: 'unique-file-id',
+ filename: 'example.jpg',
+ size: 1024000,
+ mimeType: 'image/jpeg',
+ storageType: 'local',
+});
+```
+
+## 文件生命周期
+
+1. **上传开始**: 创建资源记录，状态为 `UPLOADING`
+2. **上传完成**: 状态更新为 `UPLOADED`
+3. **处理中**: 状态可更新为 `PROCESSING`
+4. **处理完成**: 状态更新为 `PROCESSED`
+5. **清理**: 过期文件自动清理
+
+## 存储迁移
+
+支持在不同存储类型之间迁移数据：
+
+```bash
+# API 调用示例
+curl -X POST http://localhost:3000/api/storage/migrate-storage \
+ -H "Content-Type: application/json" \
+ -d '{"from": "local", "to": "s3"}'
+```
+
+## 安全考虑
+
+1. **环境变量**: 敏感信息（如 S3 密钥）应存储在环境变量中
+2. **访问控制**: 建议在生产环境中添加适当的身份验证
+3. **CORS 配置**: 根据需要配置跨域访问策略
+4. **文件验证**: 建议添加文件类型和大小验证
+
+## 故障排除
+
+### 常见问题
+
+1. **找不到模块错误**: 确保已正确安装依赖包
+2. **S3 连接失败**: 检查网络连接和凭据配置
+3. **本地存储权限**: 确保应用有写入本地目录的权限
+4. **上传失败**: 检查文件大小限制和存储空间
+
+### 调试模式
+
+启用详细日志：
+
+```bash
+DEBUG=storage:* npm start
+```
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 更新日志
+
+### v2.0.0
+
+- 重构为模块化架构
+- 添加完整的 TypeScript 支持
+- 支持多种 S3 兼容服务
+- 改进的错误处理和日志记录
diff --git a/packages/storage/docs/S3_DOWNLOAD_MECHANISM.md b/packages/storage/docs/S3_DOWNLOAD_MECHANISM.md
new file mode 100644
index 0000000..ec61e88
--- /dev/null
+++ b/packages/storage/docs/S3_DOWNLOAD_MECHANISM.md
@@ -0,0 +1,110 @@
+# S3存储下载机制说明
+
+## 问题背景
+
+在文件上传系统中，我们使用了两种存储类型：
+
+- **本地存储（Local）**：文件存储在服务器本地文件系统
+- **S3存储（S3）**：文件存储在AWS S3或兼容的对象存储服务中
+
+对于文件访问，我们使用了目录格式的 `fileId`，例如：`2025/05/28/RHwt8AkkZp`
+
+## 存储结构差异
+
+### 本地存储
+
+- **fileId**：`2025/05/28/RHwt8AkkZp` （目录路径）
+- **实际存储**：`/uploads/2025/05/28/RHwt8AkkZp/filename.ext`
+- **下载方式**：扫描目录，找到实际文件，返回文件流
+
+### S3存储
+
+- **fileId**：`2025/05/28/RHwt8AkkZp` （目录路径）
+- **S3 Key**：`2025/05/28/RHwt8AkkZp/filename.ext` （完整对象路径）
+- **下载方式**：重定向到S3 URL
+
+## 核心问题
+
+S3存储中，对象的完整路径（S3 Key）包含文件名，但我们的 `fileId` 只是目录路径，缺少文件名部分。
+
+## 解决方案
+
+### 1. 文件名重建策略
+
+我们通过以下方式重建完整的S3路径：
+
+```typescript
+const fileName = resource.title || 'file';
+const fullS3Key = `${fileId}/${fileName}`;
+```
+
+### 2. URL生成逻辑
+
+```typescript
+// AWS S3
+const s3Url = `https://${bucket}.s3.${region}.amazonaws.com/${fullS3Key}`;
+
+// 自定义S3兼容服务（如MinIO）
+const s3Url = `${endpoint}/${bucket}/${fullS3Key}`;
+```
+
+### 3. 下载流程
+
+1. 从数据库获取文件信息（fileId + resource.title）
+2. 重建完整S3 Key：`${fileId}/${fileName}`
+3. 生成S3直接访问URL
+4. 302重定向到S3 URL，让客户端直接从S3下载
+
+## 优势
+
+### 性能优势
+
+- **302重定向**：避免服务器中转，减少带宽消耗
+- **直接下载**：客户端直接从S3下载，速度更快
+- **CDN友好**：可配合CloudFront等CDN使用
+
+### 安全考虑
+
+- **公开读取**：需要确保S3 bucket配置了适当的公开读取权限
+- **预签名URL**：未来可扩展支持预签名URL用于私有文件
+
+## 局限性
+
+### 文件名依赖
+
+- 依赖数据库中存储的 `resource.title` 字段
+- 如果文件名不匹配，会导致404错误
+
+### 替代方案
+
+如果需要更可靠的方案，可以考虑：
+
+1. **存储完整S3 Key**：在数据库中存储完整的S3对象路径
+2. **S3 ListObjects API**：动态查询S3中的实际对象（会增加API调用成本）
+
+## 环境配置
+
+确保S3配置正确：
+
+```env
+STORAGE_TYPE=s3
+S3_BUCKET=your-bucket-name
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=your-access-key
+S3_SECRET_ACCESS_KEY=your-secret-key
+S3_ENDPOINT=https://s3.amazonaws.com # 可选，用于其他S3兼容服务
+```
+
+## 测试验证
+
+使用以下URL格式测试下载：
+
+```
+/download/2025%2F05%2F28%2FRHwt8AkkZp
+```
+
+应该会302重定向到：
+
+```
+https://your-bucket.s3.us-east-1.amazonaws.com/2025/05/28/RHwt8AkkZp/filename.ext
+```
diff --git a/packages/storage/package.json b/packages/storage/package.json
new file mode 100644
index 0000000..aa68897
--- /dev/null
+++ b/packages/storage/package.json
@@ -0,0 +1,62 @@
+{
+ "name": "@repo/storage",
+ "version": "2.0.0",
+ "description": "Storage implementation for Hono - 完全兼容 Hono 的 Storage",
+ "main": "dist/index.js",
+ "types": "dist/index.d.ts",
+ "scripts": {
+ "build": "tsc",
+ "dev": "tsc --watch",
+ "clean": "rm -rf dist"
+ },
+ "dependencies": {
+ "@hono/zod-validator": "^0.5.0",
+ "@repo/db": "workspace:*",
+ "@repo/tus": "workspace:*",
+ "hono": "^4.7.10",
+ "ioredis": "5.4.1",
+ "jose": "^6.0.11",
+ "nanoid": "^5.1.5",
+ "transliteration": "^2.3.5",
+ "zod": "^3.25.23"
+ },
+ "devDependencies": {
+ "@types/node": "^22.15.21",
+ "typescript": "^5.0.0"
+ },
+ "peerDependencies": {
+ "@repo/db": "workspace:*",
+ "@repo/tus": "workspace:*",
+ "hono": "^4.0.0",
+ "ioredis": "^5.0.0"
+ },
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js",
+ "require": "./dist/index.js"
+ }
+ },
+ "files": [
+ "dist",
+ "README.md"
+ ],
+ "keywords": [
+ "storage",
+ "hono",
+ "tus",
+ "upload",
+ "typescript"
+ ],
+ "author": "Your Name",
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/your-org/your-repo.git",
+ "directory": "packages/storage"
+ },
+ "bugs": {
+ "url": "https://github.com/your-org/your-repo/issues"
+ },
+ "homepage": "https://github.com/your-org/your-repo/tree/main/packages/storage#readme"
+}
diff --git a/apps/backend/src/upload/storage.adapter.ts b/packages/storage/src/core/adapter.ts
similarity index 89%
rename from apps/backend/src/upload/storage.adapter.ts
rename to packages/storage/src/core/adapter.ts
index 6ba69fd..4104e22 100644
--- a/apps/backend/src/upload/storage.adapter.ts
+++ b/packages/storage/src/core/adapter.ts
@@ -1,33 +1,6 @@
import { FileStore, S3Store } from '@repo/tus';
import type { DataStore } from '@repo/tus';
-
-// 存储类型枚举
-export enum StorageType {
- LOCAL = 'local',
- S3 = 's3',
-}
-
-// 存储配置接口
-export interface StorageConfig {
- type: StorageType;
- // 本地存储配置
- local?: {
- directory: string;
- expirationPeriodInMilliseconds?: number;
- };
- // S3 存储配置
- s3?: {
- bucket: string;
- region: string;
- accessKeyId: string;
- secretAccessKey: string;
- endpoint?: string; // 用于兼容其他 S3 兼容服务
- forcePathStyle?: boolean;
- partSize?: number;
- maxConcurrentPartUploads?: number;
- expirationPeriodInMilliseconds?: number;
- };
-}
+import { StorageType, StorageConfig } from '../types';
// 从环境变量获取存储配置
export function getStorageConfig(): StorageConfig {
diff --git a/packages/storage/src/core/index.ts b/packages/storage/src/core/index.ts
new file mode 100644
index 0000000..095283d
--- /dev/null
+++ b/packages/storage/src/core/index.ts
@@ -0,0 +1,5 @@
+// 存储适配器
+export * from './adapter';
+
+// 便捷导出
+export { StorageManager } from './adapter';
diff --git a/packages/storage/src/database/index.ts b/packages/storage/src/database/index.ts
new file mode 100644
index 0000000..4811dbb
--- /dev/null
+++ b/packages/storage/src/database/index.ts
@@ -0,0 +1,2 @@
+// 数据库操作
+export * from './operations';
diff --git a/apps/backend/src/upload/upload.index.ts b/packages/storage/src/database/operations.ts
similarity index 75%
rename from apps/backend/src/upload/upload.index.ts
rename to packages/storage/src/database/operations.ts
index 83066fc..3cbe6e9 100644
--- a/apps/backend/src/upload/upload.index.ts
+++ b/packages/storage/src/database/operations.ts
@@ -1,6 +1,6 @@
import { prisma } from '@repo/db';
import type { Resource } from '@repo/db';
-import { StorageType } from './storage.adapter';
+import { StorageType } from '../types';
export async function getResourceByFileId(fileId: string): Promise<{ status: string; resource?: Resource }> {
const resource = await prisma.resource.findFirst({
@@ -11,7 +11,10 @@ export async function getResourceByFileId(fileId: string): Promise<{ status: str
return { status: 'pending' };
}
- return { status: 'ready', resource };
+ return {
+ status: resource.status || 'unknown',
+ resource,
+ };
}
export async function getAllResources(): Promise