sa2kit 1.0.0

package/dist/universalFile/server/index.d.ts

@@ -0,0 +1,2428 @@
+import { F as FileMetadata, A as AccessPermission, i as UploadStatus, f as StorageType$1, U as UploadFileInfo$1, g as CDNType$1, h as ProcessorType$1, j as ProcessingOptions$1, I as ImageProcessingOptions, k as AudioProcessingOptions, V as VideoProcessingOptions, a as UploadProgress, o as FileEventListener$1 } from '../../types-CoGG1rNV.js';
+import { EventEmitter } from 'events';
+import { NextResponse } from 'next/server';
+
+/**
+ * UniversalFile Server 端类型定义
+ */
+
+type StorageType = StorageType$1;
+type CDNType = CDNType$1;
+type ProcessorType = ProcessorType$1;
+type UploadFileInfo = UploadFileInfo$1;
+type ProcessingOptions = ProcessingOptions$1;
+/** 存储提供者接口 */
+interface IStorageProvider {
+    /** 提供者类型 */
+    readonly type: StorageType;
+    /** 初始化 */
+    initialize(config: StorageConfig): Promise<void>;
+    /** 上传文件 */
+    upload(fileInfo: UploadFileInfo, path: string): Promise<StorageResult>;
+    /** 下载文件 */
+    download(path: string): Promise<Buffer>;
+    /** 删除文件 */
+    delete(path: string): Promise<StorageResult>;
+    /** 获取文件信息 */
+    getFileInfo(path: string): Promise<StorageResult>;
+    /** 生成访问URL */
+    getAccessUrl(path: string, expiresIn?: number): Promise<string>;
+    /** 生成预签名上传URL */
+    getUploadUrl(path: string, expiresIn?: number): Promise<string>;
+    /** 检查文件是否存在 */
+    exists(path: string): Promise<boolean>;
+    /** 列出文件 */
+    list(prefix: string, maxKeys?: number): Promise<string[]>;
+}
+/** CDN 提供者接口 */
+interface ICDNProvider {
+    /** 提供者类型 */
+    readonly type: CDNType;
+    /** 初始化 */
+    initialize(config: CDNConfig): Promise<void>;
+    /** 生成CDN URL */
+    generateUrl(originalUrl: string): Promise<string>;
+    /** 刷新缓存 */
+    refreshCache(urls: string[]): Promise<CDNResult>;
+    /** 预热缓存 */
+    preheatCache(urls: string[]): Promise<CDNResult>;
+    /** 获取访问统计 */
+    getAccessStats(startTime: Date, endTime: Date): Promise<CDNResult>;
+}
+/** 文件处理器接口 */
+interface IFileProcessor {
+    /** 处理器类型 */
+    readonly type: ProcessorType;
+    /** 初始化 */
+    initialize(): Promise<void>;
+    /** 处理文件 */
+    process(inputPath: string, outputPath: string, options: ProcessingOptions): Promise<ProcessingResult>;
+    /** 检查文件是否支持处理 */
+    supports(mimeType: string): boolean;
+    /** 获取文件信息 */
+    getFileInfo(filePath: string): Promise<Record<string, any>>;
+}
+/** 存储配置基础接口 */
+interface StorageConfig {
+    /** 存储类型 */
+    type: StorageType;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/** 本地存储配置 */
+interface LocalStorageConfig extends StorageConfig {
+    type: 'local';
+    /** 存储根目录 */
+    rootPath: string;
+    /** 基础URL */
+    baseUrl: string;
+}
+/** 阿里云 OSS 配置 */
+interface AliyunOSSConfig extends StorageConfig {
+    type: 'aliyun-oss';
+    /** 地域 */
+    region: string;
+    /** 存储桶名称 */
+    bucket: string;
+    /** 访问密钥ID */
+    accessKeyId: string;
+    /** 访问密钥密码 */
+    accessKeySecret: string;
+    /** 自定义域名 */
+    customDomain?: string;
+    /** 是否使用HTTPS */
+    secure?: boolean;
+    /** 是否使用内网访问 */
+    internal?: boolean;
+}
+/** CDN配置基础接口 */
+interface CDNConfig {
+    /** CDN类型 */
+    type: CDNType;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/** 阿里云 CDN 配置 */
+interface AliyunCDNConfig extends CDNConfig {
+    type: 'aliyun-cdn';
+    /** CDN域名 */
+    domain: string;
+    /** 访问密钥ID */
+    accessKeyId: string;
+    /** 访问密钥密码 */
+    accessKeySecret: string;
+    /** 地域 */
+    region?: string;
+}
+/** 缓存配置 */
+interface CacheConfig {
+    /** 是否启用缓存 */
+    enabled: boolean;
+    /** 最大缓存大小 */
+    maxSize?: number;
+    /** 缓存 TTL（秒） */
+    ttl?: number;
+    /** 是否使用 Redis */
+    useRedis?: boolean;
+    /** Redis 配置 */
+    redisConfig?: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+    };
+}
+/** 文件服务配置 */
+/** 缓存配置扩展 */
+interface CacheConfig {
+    /** 是否启用缓存 */
+    enabled: boolean;
+    /** 元数据缓存TTL（秒） */
+    metadataTTL?: number;
+    /** URL缓存TTL（秒） */
+    urlTTL?: number;
+    /** 最大缓存条目数 */
+    maxSize?: number;
+}
+interface UniversalFileServiceConfig {
+    /** 存储配置 */
+    storage: StorageConfig;
+    /** CDN 配置（可选） */
+    cdn?: CDNConfig;
+    /** 缓存配置（可选） */
+    cache?: CacheConfig;
+    /** 数据库持久化配置（可选） */
+    persistence?: FileServicePersistenceConfig;
+    /** 启用的处理器 */
+    processors?: ProcessorType[];
+    /** 数据库连接（可选） @deprecated 使用 persistence.repository 代替 */
+    db?: any;
+    /** 最大文件大小（字节） */
+    maxFileSize?: number;
+    /** 允许的文件类型 */
+    allowedMimeTypes?: string[];
+    /** 是否启用监控 */
+    enableMonitoring?: boolean;
+    /** 存储提供者映射（内部使用） */
+    storageProviders?: Map<StorageType, IStorageProvider>;
+    /** 默认存储类型 */
+    defaultStorage?: StorageType;
+    /** 默认CDN类型 */
+    defaultCDN?: CDNType;
+}
+/** 存储结果 */
+/** 存储操作结果 */
+interface StorageResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 存储路径 */
+    path?: string;
+    /** 访问URL */
+    url?: string;
+    /** 文件大小 */
+    size?: number;
+    /** 错误信息 */
+    error?: string;
+    /** 额外数据 */
+    data?: Record<string, any>;
+}
+/** 存储元数据 */
+interface StorageMetadata {
+    /** 文件大小 */
+    size: number;
+    /** MIME 类型 */
+    mimeType: string;
+    /** 最后修改时间 */
+    lastModified: Date;
+    /** 自定义元数据 */
+    metadata?: Record<string, any>;
+}
+/** CDN 结果 */
+/** CDN操作结果 */
+interface CDNResult {
+    /** 是否成功 */
+    success: boolean;
+    /** CDN URL */
+    url?: string;
+    /** 错误信息 */
+    error?: string;
+    /** 额外数据 */
+    data?: Record<string, any>;
+}
+/** CDN 统计信息 */
+interface CDNStats {
+    /** 带宽（字节/秒） */
+    bandwidth: number;
+    /** 请求数 */
+    requests: number;
+    /** 流量（字节） */
+    traffic: number;
+    /** 统计时间范围 */
+    timeRange: {
+        start: Date;
+        end: Date;
+    };
+}
+/** 处理结果 */
+interface ProcessingResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 处理后的文件路径 */
+    processedPath?: string;
+    /** 处理后的文件大小 */
+    processedSize?: number;
+    /** 缩略图路径 */
+    thumbnailPath?: string;
+    /** 错误信息 */
+    error?: string;
+    /** 处理耗时(毫秒) */
+    processingTime?: number;
+    /** 额外数据 */
+    data?: Record<string, any>;
+}
+/** 处理器信息 */
+interface ProcessorInfo {
+    /** 处理器名称 */
+    name: string;
+    /** 处理器版本 */
+    version: string;
+    /** 支持的格式 */
+    supportedFormats: string[];
+    /** 支持的操作 */
+    supportedOperations: string[];
+}
+/** 文件数据库记录 */
+interface FileRecord extends FileMetadata {
+    /** 创建时间 */
+    createdAt: Date | string;
+    /** 更新时间 */
+    updatedAt: Date | string;
+}
+/** 文件查询选项 */
+interface FileQueryOptions {
+    /** 模块 ID */
+    moduleId?: string;
+    /** 业务 ID */
+    businessId?: string;
+    /** 上传者 ID */
+    uploaderId?: string;
+    /** 文件类型 */
+    mimeType?: string;
+    /** 访问权限 */
+    permission?: AccessPermission;
+    /** 状态 */
+    status?: UploadStatus;
+    /** 分页 */
+    page?: number;
+    pageSize?: number;
+    /** 排序 */
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+}
+/** 分页结果 */
+interface PaginatedResult<T> {
+    /** 数据列表 */
+    items: T[];
+    /** 总数 */
+    total: number;
+    /** 当前页 */
+    page: number;
+    /** 每页大小 */
+    pageSize: number;
+    /** 总页数 */
+    totalPages: number;
+}
+/** 文件事件类型 */
+type FileEventType = 'upload:start' | 'upload:progress' | 'upload:complete' | 'upload:error' | 'download:start' | 'download:complete' | 'download:error' | 'delete:complete' | 'delete:error' | 'process:start' | 'process:complete' | 'process:error';
+/** 文件事件 */
+interface FileEvent {
+    /** 事件类型 */
+    type: FileEventType;
+    /** 文件 ID */
+    fileId: string;
+    /** 事件数据 */
+    data?: any;
+    /** 时间戳 */
+    timestamp: Date;
+}
+/** 事件监听器 */
+type FileEventListener = (event: FileEvent) => void | Promise<void>;
+/**
+ * 文件元数据数据库持久化接口
+ *
+ * 实现此接口以提供自定义的数据库持久化支持
+ *
+ * @example
+ * ```typescript
+ * // Drizzle ORM 实现
+ * class DrizzleFileRepository implements IFileMetadataRepository {
+ *   async save(metadata: FileMetadata): Promise<void> {
+ *     await db.insert(fileMetadata).values(metadata);
+ *   }
+ *   // ... 其他方法
+ * }
+ * ```
+ */
+interface IFileMetadataRepository {
+    /**
+     * 保存文件元数据到数据库
+     */
+    save(metadata: FileMetadata): Promise<void>;
+    /**
+     * 从数据库获取文件元数据
+     */
+    get(fileId: string): Promise<FileMetadata | null>;
+    /**
+     * 查询文件列表
+     */
+    query(options: FileQueryOptions): Promise<PaginatedResult<FileMetadata>>;
+    /**
+     * 从数据库删除文件元数据
+     */
+    delete(fileId: string): Promise<void>;
+    /**
+     * 批量删除文件元数据
+     */
+    batchDelete(fileIds: string[]): Promise<void>;
+}
+/**
+ * 数据库持久化配置
+ */
+interface FileServicePersistenceConfig {
+    /**
+     * 是否启用持久化
+     */
+    enabled: boolean;
+    /**
+     * 持久化仓储实现
+     */
+    repository: IFileMetadataRepository;
+    /**
+     * 是否自动持久化（默认 true）
+     * 如果为 true，文件上传完成后自动保存到数据库
+     */
+    autoPersist?: boolean;
+    /**
+     * 是否优先使用缓存（默认 false）
+     * 如果为 true，查询时优先从缓存获取
+     */
+    cacheFirst?: boolean;
+}
+/** 文件服务异常基类 */
+declare class FileServiceError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, code: string, details?: Record<string, any> | undefined);
+}
+/** 文件上传异常 */
+declare class FileUploadError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 文件处理异常 */
+declare class FileProcessingError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 存储提供者异常 */
+declare class StorageProviderError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** CDN提供者异常 */
+declare class CDNProviderError extends FileServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+
+/**
+ * UniversalFile Service 工厂函数
+ * 提供简化的服务初始化方式
+ */
+
+/**
+ * 创建文件服务配置（带智能默认值）
+ */
+declare function createFileServiceConfig(options: Partial<UniversalFileServiceConfig> & {
+    storage: StorageConfig | 'local';
+}): UniversalFileServiceConfig;
+/**
+ * 创建文件服务实例（简化版）
+ *
+ * @example
+ * ```typescript
+ * // 最简配置 - 使用本地存储
+ * const service = createUniversalFileService({ storage: 'local' });
+ *
+ * // 标准配置 - 使用阿里云 OSS
+ * const service = createUniversalFileService({
+ *   storage: {
+ *     type: 'aliyun-oss',
+ *     config: {
+ *       accessKeyId: process.env.OSS_KEY!,
+ *       accessKeySecret: process.env.OSS_SECRET!,
+ *       bucket: process.env.OSS_BUCKET!,
+ *       region: process.env.OSS_REGION!,
+ *     },
+ *   },
+ *   db: drizzleDb,
+ * });
+ * ```
+ */
+declare function createUniversalFileService(options: Partial<UniversalFileServiceConfig> & {
+    storage: StorageConfig | 'local';
+}): {
+    config: UniversalFileServiceConfig;
+    upload(): Promise<never>;
+    download(): Promise<never>;
+};
+/**
+ * 从环境变量创建配置（便利函数）
+ *
+ * @example
+ * ```typescript
+ * // .env
+ * // STORAGE_TYPE=aliyun-oss
+ * // OSS_ACCESS_KEY_ID=xxx
+ * // OSS_ACCESS_KEY_SECRET=xxx
+ * // OSS_BUCKET=my-bucket
+ * // OSS_REGION=oss-cn-hangzhou
+ *
+ * const service = createFileServiceFromEnv();
+ * ```
+ */
+declare function createFileServiceFromEnv(db?: any): {
+    config: UniversalFileServiceConfig;
+    upload(): Promise<never>;
+    download(): Promise<never>;
+};
+
+/**
+ * UniversalFile 预设配置
+ * 提供常见场景的开箱即用配置
+ */
+
+/**
+ * 本地开发环境预设
+ */
+declare function createLocalDevPreset(baseUrl?: string): StorageConfig;
+/**
+ * 生产环境 OSS 预设
+ */
+declare function createAliyunOSSPreset(config: {
+    accessKeyId: string;
+    accessKeySecret: string;
+    bucket: string;
+    region?: string;
+}): StorageConfig;
+/**
+ * 智能预设：根据环境自动选择
+ */
+declare function createSmartPreset(): StorageConfig;
+/**
+ * 图片服务预设（针对图片处理优化）
+ */
+declare function createImageServicePreset(storage: StorageConfig): {
+    storage: StorageConfig;
+    maxFileSize: number;
+    allowedMimeTypes: string[];
+};
+/**
+ * 视频服务预设（针对大文件优化）
+ */
+declare function createVideoServicePreset(storage: StorageConfig): {
+    storage: StorageConfig;
+    maxFileSize: number;
+    allowedMimeTypes: string[];
+    enableStreaming: boolean;
+};
+/**
+ * 文档服务预设
+ */
+declare function createDocumentServicePreset(storage: StorageConfig): {
+    storage: StorageConfig;
+    maxFileSize: number;
+    allowedMimeTypes: string[];
+};
+
+/**
+ * UniversalFile 配置验证
+ */
+
+declare class ConfigValidationError extends Error {
+    field: string;
+    constructor(message: string, field: string);
+}
+/**
+ * 验证存储配置
+ */
+declare function validateStorageConfig(storage: StorageConfig): void;
+/**
+ * 验证完整的服务配置
+ */
+declare function validateServiceConfig(config: UniversalFileServiceConfig): void;
+/**
+ * 验证环境变量
+ */
+declare function validateEnvironment(requiredVars: string[]): void;
+/**
+ * 获取环境变量所需的变量列表（根据存储类型）
+ */
+declare function getRequiredEnvVars(storageType: string): string[];
+
+/**
+ * 本地存储提供者实现
+ */
+
+/**
+ * 本地文件系统存储提供者
+ */
+declare class LocalStorageProvider implements IStorageProvider {
+    readonly type: StorageType;
+    private config;
+    private isInitialized;
+    /**
+     * 初始化存储提供者
+     */
+    initialize(config: StorageConfig): Promise<void>;
+    /**
+     * 上传文件
+     */
+    upload(fileInfo: UploadFileInfo, filePath: string): Promise<StorageResult>;
+    /**
+     * 下载文件
+     */
+    download(path: string): Promise<Buffer>;
+    /**
+     * 删除文件
+     */
+    delete(path: string): Promise<StorageResult>;
+    /**
+     * 获取文件信息
+     */
+    getFileInfo(path: string): Promise<StorageResult>;
+    /**
+     * 生成访问URL
+     */
+    getAccessUrl(path: string, _expiresIn?: number): Promise<string>;
+    /**
+     * 生成预签名上传URL
+     */
+    getUploadUrl(path: string, _expiresIn?: number): Promise<string>;
+    /**
+     * 检查文件是否存在
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * 列出文件
+     */
+    list(prefix: string, maxKeys?: number): Promise<string[]>;
+    /**
+     * 确保已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 获取完整文件路径
+     */
+    private getFullPath;
+    /**
+     * 生成访问URL
+     */
+    private generateAccessUrl;
+    /**
+     * 确保目录存在
+     */
+    private ensureDirectoryExists;
+    /**
+     * 验证目录访问权限
+     */
+    private validateDirectoryAccess;
+    /**
+     * 流式上传大文件（可选实现）
+     */
+    uploadStream(readableStream: NodeJS.ReadableStream, filePath: string): Promise<StorageResult>;
+    /**
+     * 流式下载大文件（可选实现）
+     */
+    createDownloadStream(path: string): NodeJS.ReadableStream;
+}
+
+/**
+ * 阿里云OSS存储提供者实现
+ */
+
+/**
+ * 阿里云OSS存储提供者
+ */
+declare class AliyunOSSProvider implements IStorageProvider {
+    readonly type: StorageType;
+    private config;
+    private client;
+    private isInitialized;
+    /**
+     * 初始化存储提供者
+     */
+    initialize(config: StorageConfig): Promise<void>;
+    /**
+     * 重新初始化存储提供者（支持配置热更新）
+     */
+    reinitialize(config: StorageConfig): Promise<void>;
+    /**
+     * 上传文件
+     */
+    upload(fileInfo: UploadFileInfo, filePath: string): Promise<StorageResult>;
+    /**
+     * 下载文件
+     */
+    download(filePath: string): Promise<Buffer>;
+    /**
+     * 删除文件
+     */
+    delete(filePath: string): Promise<StorageResult>;
+    /**
+     * 获取文件信息
+     */
+    getFileInfo(filePath: string): Promise<StorageResult>;
+    /**
+     * 生成访问URL
+     */
+    getAccessUrl(filePath: string, expiresIn?: number): Promise<string>;
+    /**
+     * 生成预签名上传URL
+     */
+    getUploadUrl(filePath: string, expiresIn?: number): Promise<string>;
+    /**
+     * 检查文件是否存在
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * 列出文件
+     */
+    list(prefix: string, maxKeys?: number): Promise<string[]>;
+    /**
+     * 确保已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 验证配置
+     */
+    private validateConfig;
+    /**
+     * 测试连接
+     */
+    private testConnection;
+    /**
+     * 分片上传大文件
+     */
+    private multipartUpload;
+    /**
+     * 生成公开访问URL
+     */
+    private generateAccessUrl;
+    /**
+     * 判断是否为OSS错误
+     */
+    private isOSSError;
+    /**
+     * 格式化OSS错误信息
+     */
+    private formatOSSError;
+    /**
+     * 流式上传（可选实现）
+     */
+    uploadStream(readableStream: NodeJS.ReadableStream, filePath: string, contentType?: string, contentLength?: number): Promise<StorageResult>;
+    /**
+     * 批量删除文件
+     */
+    batchDelete(filePaths: string[]): Promise<StorageResult>;
+    /**
+     * 复制文件
+     */
+    copy(sourcePath: string, targetPath: string): Promise<StorageResult>;
+    /**
+     * 编码元数据，避免中文字符在HTTP头部中的问题
+     */
+    private encodeMetadata;
+}
+
+/**
+ * 阿里云CDN提供者实现
+ */
+
+/**
+ * 阿里云CDN提供者
+ */
+declare class AliyunCDNProvider implements ICDNProvider {
+    readonly type: CDNType;
+    private config;
+    private client;
+    private isInitialized;
+    /**
+     * 初始化CDN提供者
+     */
+    initialize(config: CDNConfig): Promise<void>;
+    /**
+     * 生成CDN URL
+     */
+    generateUrl(originalUrl: string): Promise<string>;
+    /**
+     * 刷新缓存
+     */
+    refreshCache(urls: string[]): Promise<CDNResult>;
+    /**
+     * 预热缓存
+     */
+    preheatCache(urls: string[]): Promise<CDNResult>;
+    /**
+     * 获取访问统计
+     */
+    getAccessStats(startTime: Date, endTime: Date): Promise<CDNResult>;
+    /**
+     * 生成防盗链签名URL
+     */
+    generateSignedUrl(originalUrl: string, expiresIn?: number, authKey?: string): Promise<string>;
+    /**
+     * 查询刷新任务状态
+     */
+    getRefreshTaskStatus(taskId: string): Promise<CDNResult>;
+    /**
+     * 查询预热任务状态
+     */
+    getPreheatTaskStatus(taskId: string): Promise<CDNResult>;
+    /**
+     * 获取域名配置
+     */
+    getDomainConfig(): Promise<CDNResult>;
+    /**
+     * 优化URL (添加图像处理参数等)
+     */
+    optimizeUrl(originalUrl: string, options?: {
+        imageQuality?: number;
+        imageFormat?: 'webp' | 'jpg' | 'png';
+        imageResize?: {
+            width?: number;
+            height?: number;
+        };
+        enableGzip?: boolean;
+    }): Promise<string>;
+    /**
+     * 确保已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 验证配置
+     */
+    private validateConfig;
+    /**
+     * 验证域名格式
+     */
+    private isValidDomain;
+    /**
+     * 测试连接
+     */
+    private testConnection;
+    /**
+     * 创建模拟客户端（用于开发测试）
+     */
+    private createMockClient;
+    /**
+     * 批量刷新缓存（带进度回调）
+     */
+    batchRefreshCache(urls: string[], batchSize?: number, onProgress?: (completed: number, total: number) => void): Promise<CDNResult>;
+}
+
+/**
+ * CDN缓存策略管理
+ * 优化静态资源缓存策略和预热机制
+ */
+/**
+ * 缓存策略类型
+ */
+declare enum CacheStrategyType$1 {
+    /** 图片资源 */
+    IMAGE = "image",
+    /** 视频资源 */
+    VIDEO = "video",
+    /** 音频资源 */
+    AUDIO = "audio",
+    /** 文档资源 */
+    DOCUMENT = "document",
+    /** 压缩包 */
+    ARCHIVE = "archive",
+    /** 静态资源 */
+    STATIC = "static",
+    /** 其他 */
+    OTHER = "other"
+}
+/**
+ * 缓存策略配置
+ */
+interface CacheStrategyConfig$1 {
+    /** 缓存策略类型 */
+    type: CacheStrategyType$1;
+    /** 缓存时间（秒） */
+    ttl: number;
+    /** 是否启用浏览器缓存 */
+    browserCache: boolean;
+    /** 浏览器缓存时间（秒） */
+    browserCacheTtl: number;
+    /** 是否启用CDN缓存 */
+    cdnCache: boolean;
+    /** CDN缓存时间（秒） */
+    cdnCacheTtl: number;
+    /** 是否启用预热 */
+    enableWarmup: boolean;
+    /** 缓存控制头 */
+    cacheControl: string;
+    /** 允许的文件类型 */
+    allowedMimeTypes: string[];
+    /** 文件大小限制（字节） */
+    maxFileSize?: number;
+}
+/**
+ * 缓存统计信息
+ */
+interface CacheStats$2 {
+    /** 命中次数 */
+    hits: number;
+    /** 未命中次数 */
+    misses: number;
+    /** 命中率 */
+    hitRate: number;
+    /** 总请求数 */
+    totalRequests: number;
+    /** 缓存大小估算 */
+    estimatedSize: number;
+    /** 节省的带宽（字节） */
+    bandwidthSaved: number;
+}
+/**
+ * CDN缓存策略管理器
+ */
+declare class CdnCacheStrategy$1 {
+    private strategies;
+    private stats;
+    constructor();
+    /**
+     * 初始化默认缓存策略
+     */
+    private initializeDefaultStrategies;
+    /**
+     * 根据MIME类型获取缓存策略
+     */
+    getStrategyByMimeType(mimeType: string): CacheStrategyConfig$1;
+    /**
+     * 生成缓存控制头
+     */
+    generateCacheHeaders(mimeType: string, fileSize?: number): Record<string, string>;
+    /**
+     * 检查是否需要缓存预热
+     */
+    shouldWarmupCache(mimeType: string): boolean;
+    /**
+     * 记录缓存命中
+     */
+    recordCacheHit(mimeType: string, fileSize?: number): void;
+    /**
+     * 记录缓存未命中
+     */
+    recordCacheMiss(mimeType: string, fileSize?: number): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getCacheStats(): Map<CacheStrategyType$1, CacheStats$2>;
+    /**
+     * 获取总体缓存统计
+     */
+    getOverallStats(): CacheStats$2;
+    /**
+     * 生成缓存优化建议
+     */
+    generateOptimizationSuggestions(): Array<{
+        type: CacheStrategyType$1;
+        issue: string;
+        suggestion: string;
+        severity: 'low' | 'medium' | 'high';
+    }>;
+    /**
+     * 更新缓存策略
+     */
+    updateStrategy(type: CacheStrategyType$1, config: Partial<CacheStrategyConfig$1>): void;
+    /**
+     * 重置统计信息
+     */
+    resetStats(): void;
+}
+/**
+ * 单例CDN缓存策略管理器
+ */
+declare const cdnCacheStrategy: CdnCacheStrategy$1;
+
+/**
+ * 图片处理器实现
+ * 支持压缩、裁剪、水印、格式转换等功能
+ */
+
+/**
+ * 图片处理器
+ * 使用Sharp库进行高性能图片处理
+ */
+declare class ImageProcessor implements IFileProcessor {
+    readonly type: ProcessorType;
+    private sharp;
+    private isInitialized;
+    /**
+     * 初始化图片处理器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 处理图片文件
+     */
+    process(inputPath: string, outputPath: string, options: ProcessingOptions): Promise<ProcessingResult>;
+    /**
+     * 检查文件是否支持处理
+     */
+    supports(mimeType: string): boolean;
+    /**
+     * 获取图片文件信息
+     */
+    getFileInfo(filePath: string): Promise<Record<string, any>>;
+    /**
+     * 确保处理器已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 获取图片元数据
+     */
+    private getImageMetadata;
+    /**
+     * 应用图片处理操作
+     */
+    private applyImageOperations;
+    /**
+     * 应用水印
+     */
+    private applyWatermark;
+    /**
+     * 创建文字水印SVG
+     */
+    private createTextWatermarkSvg;
+    /**
+     * 获取水印位置对应的gravity值
+     */
+    private getWatermarkGravity;
+    /**
+     * 确定输出格式
+     */
+    private determineOutputFormat;
+    /**
+     * 应用输出设置
+     */
+    private applyOutputSettings;
+    /**
+     * 是否需要生成缩略图
+     */
+    private shouldGenerateThumbnail;
+    /**
+     * 生成缩略图
+     */
+    private generateThumbnail;
+    /**
+     * 获取缩略图路径
+     */
+    private getThumbnailPath;
+    /**
+     * 创建模拟Sharp对象（开发测试用）
+     */
+    private createMockSharp;
+    /**
+     * 批量图片处理
+     */
+    batchProcess(inputPaths: string[], outputDir: string, options: ImageProcessingOptions, onProgress?: (completed: number, total: number) => void): Promise<ProcessingResult[]>;
+}
+
+/**
+ * 音频处理器实现
+ * 支持格式转换、压缩、音质调整等功能
+ */
+
+/**
+ * 音频处理器
+ * 使用FFmpeg进行音频处理
+ */
+declare class AudioProcessor implements IFileProcessor {
+    readonly type: ProcessorType;
+    private ffmpeg;
+    private isInitialized;
+    /**
+     * 初始化音频处理器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 处理音频文件
+     */
+    process(inputPath: string, outputPath: string, options: ProcessingOptions): Promise<ProcessingResult>;
+    /**
+     * 检查文件是否支持处理
+     */
+    supports(mimeType: string): boolean;
+    /**
+     * 获取音频文件信息
+     */
+    getFileInfo(filePath: string): Promise<Record<string, any>>;
+    /**
+     * 确保处理器已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 获取音频元数据
+     */
+    private getAudioMetadata;
+    /**
+     * 执行音频处理
+     */
+    private processAudio;
+    /**
+     * 设置音频编解码器
+     */
+    private setAudioCodec;
+    /**
+     * 确定输出格式
+     */
+    private determineOutputFormat;
+    /**
+     * 格式化时长显示
+     */
+    private formatDuration;
+    /**
+     * 获取声道描述
+     */
+    private getChannelsDescription;
+    /**
+     * 获取音质描述
+     */
+    private getQualityDescription;
+    /**
+     * 创建模拟FFmpeg对象（开发测试用）
+     */
+    private createMockFFmpeg;
+    /**
+     * 批量音频处理
+     */
+    batchProcess(inputPaths: string[], outputDir: string, options: AudioProcessingOptions, onProgress?: (completed: number, total: number) => void): Promise<ProcessingResult[]>;
+    /**
+     * 提取音频封面
+     */
+    extractCover(inputPath: string, outputPath: string): Promise<boolean>;
+    /**
+     * 音频降噪处理
+     */
+    denoise(inputPath: string, outputPath: string): Promise<ProcessingResult>;
+}
+
+/**
+ * 视频处理器实现
+ * 支持缩略图生成、格式转换、压缩等功能
+ */
+
+/**
+ * 视频处理器
+ * 使用FFmpeg进行视频处理
+ */
+declare class VideoProcessor implements IFileProcessor {
+    readonly type: ProcessorType;
+    private ffmpeg;
+    private isInitialized;
+    /**
+     * 初始化视频处理器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 处理视频文件
+     */
+    process(inputPath: string, outputPath: string, options: ProcessingOptions): Promise<ProcessingResult>;
+    /**
+     * 检查文件是否支持处理
+     */
+    supports(mimeType: string): boolean;
+    /**
+     * 获取视频文件信息
+     */
+    getFileInfo(filePath: string): Promise<Record<string, any>>;
+    /**
+     * 确保处理器已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 获取视频元数据
+     */
+    private getVideoMetadata;
+    /**
+     * 解析帧率
+     */
+    private parseFPS;
+    /**
+     * 执行视频处理
+     */
+    private processVideo;
+    /**
+     * 设置视频编解码器
+     */
+    private setVideoCodec;
+    /**
+     * 设置视频质量
+     */
+    private setVideoQuality;
+    /**
+     * 确定输出格式
+     */
+    private determineOutputFormat;
+    /**
+     * 生成缩略图
+     */
+    private generateThumbnail;
+    /**
+     * 获取缩略图路径
+     */
+    private getThumbnailPath;
+    /**
+     * 格式化时长显示
+     */
+    private formatDuration;
+    /**
+     * 获取分辨率描述
+     */
+    private getResolutionDescription;
+    /**
+     * 获取视频质量描述
+     */
+    private getQualityDescription;
+    /**
+     * 创建模拟FFmpeg对象（开发测试用）
+     */
+    private createMockFFmpeg;
+    /**
+     * 批量视频处理
+     */
+    batchProcess(inputPaths: string[], outputDir: string, options: VideoProcessingOptions, onProgress?: (completed: number, total: number) => void): Promise<ProcessingResult[]>;
+    /**
+     * 提取视频帧
+     */
+    extractFrames(inputPath: string, outputDir: string, options?: {
+        count?: number;
+        interval?: number;
+        format?: 'jpg' | 'png';
+    }): Promise<string[]>;
+    /**
+     * 视频压缩
+     */
+    compress(inputPath: string, outputPath: string, compressionLevel?: 'low' | 'medium' | 'high'): Promise<ProcessingResult>;
+    /**
+     * 获取压缩质量
+     */
+    private getCompressionQuality;
+}
+
+/**
+ * 文件处理队列管理系统
+ * 支持异步任务调度、优先级排序、并发控制等功能
+ */
+
+interface QueueTask {
+    id: string;
+    inputPath: string;
+    outputPath: string;
+    options: ProcessingOptions;
+    priority: TaskPriority;
+    status: TaskStatus;
+    processor?: IFileProcessor;
+    startTime?: number;
+    endTime?: number;
+    result?: ProcessingResult;
+    error?: string;
+    retries: number;
+    maxRetries: number;
+    onProgress?: (task: QueueTask, progress: number) => void;
+    onComplete?: (task: QueueTask, result: ProcessingResult) => void;
+    onError?: (task: QueueTask, error: string) => void;
+}
+type TaskPriority = 'low' | 'normal' | 'high' | 'urgent';
+type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+interface QueueOptions {
+    maxConcurrentTasks?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+    taskTimeout?: number;
+    autoStart?: boolean;
+}
+interface QueueStats {
+    totalTasks: number;
+    pendingTasks: number;
+    runningTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    cancelledTasks: number;
+    averageProcessingTime: number;
+    successRate: number;
+}
+/**
+ * 文件处理队列管理器
+ */
+declare class ProcessingQueue extends EventEmitter {
+    private tasks;
+    private runningTasks;
+    private processors;
+    private options;
+    private isStarted;
+    private processInterval;
+    constructor(options?: QueueOptions);
+    /**
+     * 注册文件处理器
+     */
+    registerProcessor(processor: IFileProcessor): void;
+    /**
+     * 添加任务到队列
+     */
+    addTask(inputPath: string, outputPath: string, options: ProcessingOptions, taskOptions?: Partial<Pick<QueueTask, 'priority' | 'maxRetries' | 'onProgress' | 'onComplete' | 'onError'>>): string;
+    /**
+     * 启动队列处理
+     */
+    start(): void;
+    /**
+     * 停止队列处理
+     */
+    stop(): void;
+    /**
+     * 暂停任务
+     */
+    pauseTask(taskId: string): boolean;
+    /**
+     * 取消任务
+     */
+    cancelTask(taskId: string): boolean;
+    /**
+     * 获取任务状态
+     */
+    getTask(taskId: string): QueueTask | undefined;
+    /**
+     * 获取所有任务
+     */
+    getAllTasks(): QueueTask[];
+    /**
+     * 获取待处理任务
+     */
+    getPendingTasks(): QueueTask[];
+    /**
+     * 获取正在运行的任务
+     */
+    getRunningTasks(): QueueTask[];
+    /**
+     * 获取队列统计信息
+     */
+    getStats(): QueueStats;
+    /**
+     * 清理已完成的任务
+     */
+    cleanup(): void;
+    /**
+     * 处理下一个任务
+     */
+    private processNext;
+    /**
+     * 获取下一个待处理任务（按优先级排序）
+     */
+    private getNextTask;
+    /**
+     * 处理单个任务
+     */
+    private processTask;
+    /**
+     * 完成任务
+     */
+    private completeTask;
+    /**
+     * 重试或失败任务
+     */
+    private retryOrFailTask;
+    /**
+     * 失败任务
+     */
+    private failTask;
+    /**
+     * 生成唯一任务ID
+     */
+    private generateTaskId;
+    /**
+     * 批量添加任务
+     */
+    addBatchTasks(tasks: Array<{
+        inputPath: string;
+        outputPath: string;
+        options: ProcessingOptions;
+        priority?: TaskPriority;
+    }>, onBatchProgress?: (completed: number, total: number) => void, onBatchComplete?: (results: Map<string, ProcessingResult>) => void): string[];
+    /**
+     * 获取队列健康状态
+     */
+    getHealthStatus(): {
+        isHealthy: boolean;
+        issues: string[];
+        recommendations: string[];
+    };
+}
+
+/**
+ * MIME 类型工具函数
+ */
+/**
+ * 根据文件名获取 MIME 类型
+ *
+ * @param filename 文件名
+ * @returns MIME 类型
+ *
+ * @example
+ * ```typescript
+ * getMimeType('photo.jpg')    // 'image/jpeg'
+ * getMimeType('video.mp4')    // 'video/mp4'
+ * getMimeType('unknown.xyz')  // 'application/octet-stream'
+ * ```
+ */
+declare function getMimeType(filename: string): string;
+
+/**
+ * 通用文件服务核心实现
+ *
+ * 提供统一的文件上传、下载、管理接口
+ */
+
+/**
+ * 通用文件服务类
+ */
+declare class UniversalFileService extends EventEmitter {
+    private config;
+    private storageProviders;
+    private cdnProviders;
+    private fileProcessors;
+    private uploadProgressMap;
+    private metadataCache;
+    private urlCache;
+    private processingQueue;
+    private isProcessingQueueRunning;
+    constructor(config: UniversalFileServiceConfig);
+    /**
+     * 设置数据库持久化监听器
+     *
+     * 当文件上传完成或删除时，自动触发数据库操作
+     */
+    private setupPersistenceListeners;
+    /**
+     * 初始化文件服务
+     */
+    initialize(): Promise<void>;
+    /**
+     * 重新初始化存储提供者（支持配置热更新）
+     */
+    reinitializeStorageProviders(): Promise<void>;
+    /**
+     * 注册存储提供者
+     */
+    registerStorageProvider(provider: IStorageProvider): void;
+    /**
+     * 注册CDN提供者
+     */
+    registerCDNProvider(provider: ICDNProvider): void;
+    /**
+     * 注册文件处理器
+     */
+    registerFileProcessor(processor: IFileProcessor): void;
+    /**
+     * 上传文件
+     */
+    uploadFile(fileInfo: UploadFileInfo$1, storageType?: StorageType$1, onProgress?: (progress: UploadProgress) => void): Promise<FileMetadata>;
+    /**
+     * 获取上传进度
+     */
+    getUploadProgress(fileId: string): UploadProgress | undefined;
+    /**
+     * 监听文件事件
+     */
+    onFileEvent(eventType: string, listener: FileEventListener$1): void;
+    /**
+     * 移除文件事件监听器
+     */
+    offFileEvent(eventType: string, listener: FileEventListener$1): void;
+    private initializeStorageProviders;
+    private registerDefaultStorageProviders;
+    private initializeCDNProviders;
+    private initializeFileProcessors;
+    private validateFile;
+    private generateFileMetadata;
+    private generateStoragePath;
+    private generateFileHash;
+    private queueFileProcessing;
+    private generateProcessedPath;
+    private processFileQueue;
+    private cacheMetadata;
+    private _clearMetadataCache2;
+    private emitFileEvent;
+}
+
+/**
+ * 通用文件服务缓存管理器
+ * 支持多层缓存策略：内存缓存 + Redis缓存
+ */
+/**
+ * 缓存项接口
+ */
+interface CacheItem<T = any> {
+    /** 缓存数据 */
+    data: T;
+    /** 创建时间 */
+    createdAt: number;
+    /** 过期时间 */
+    expiresAt: number;
+    /** 访问次数 */
+    accessCount: number;
+    /** 最后访问时间 */
+    lastAccessAt: number;
+}
+/**
+ * 缓存统计信息
+ */
+interface CacheStats$1 {
+    /** 总请求次数 */
+    totalRequests: number;
+    /** 命中次数 */
+    hits: number;
+    /** 未命中次数 */
+    misses: number;
+    /** 命中率 */
+    hitRate: number;
+    /** 内存缓存大小 */
+    memorySize: number;
+    /** Redis缓存状态 */
+    redisConnected: boolean;
+}
+/**
+ * 缓存配置选项
+ */
+interface CacheOptions {
+    /** 默认过期时间（秒） */
+    defaultTTL?: number;
+    /** 内存缓存最大条目数 */
+    maxMemoryItems?: number;
+    /** 是否启用Redis缓存 */
+    enableRedis?: boolean;
+    /** Redis连接配置 */
+    redisConfig?: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+    };
+    /** 缓存键前缀 */
+    keyPrefix?: string;
+}
+/**
+ * 缓存管理器
+ */
+declare class CacheManager {
+    private memoryCache;
+    private redisClient;
+    private stats;
+    private options;
+    constructor(options?: CacheOptions);
+    /**
+     * 初始化Redis连接
+     */
+    private initRedis;
+    /**
+     * 生成缓存键
+     */
+    private generateKey;
+    /**
+     * 获取缓存数据
+     */
+    get<T = any>(key: string): Promise<T | null>;
+    /**
+     * 设置缓存数据
+     */
+    set<T = any>(key: string, data: T, ttl?: number): Promise<void>;
+    /**
+     * 删除缓存数据
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 批量删除缓存（支持模式匹配）
+     */
+    deletePattern(pattern: string): Promise<void>;
+    /**
+     * 清空所有缓存
+     */
+    clear(): Promise<void>;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): CacheStats$1;
+    /**
+     * 获取缓存项详情（用于调试）
+     */
+    getCacheItem(key: string): CacheItem | null;
+    /**
+     * 预热缓存
+     */
+    warmup<T>(items: Array<{
+        key: string;
+        data: T;
+        ttl?: number;
+    }>): Promise<void>;
+    /**
+     * 更新命中率
+     */
+    private updateHitRate;
+    /**
+     * 更新内存使用量
+     */
+    private updateMemorySize;
+    /**
+     * 模式匹配函数
+     */
+    private matchPattern;
+    /**
+     * 获取或设置缓存（如果不存在则调用生成函数）
+     */
+    getOrSet<T>(key: string, generator: () => Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * 关闭缓存管理器
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * 通用文件服务性能监控器
+ * 监控API响应时间、数据库查询性能、缓存命中率等指标
+ */
+/**
+ * 性能指标类型
+ */
+interface PerformanceMetric {
+    /** 指标名称 */
+    name: string;
+    /** 指标值 */
+    value: number;
+    /** 单位 */
+    unit: string;
+    /** 时间戳 */
+    timestamp: number;
+    /** 标签 */
+    labels?: Record<string, string>;
+}
+/**
+ * 性能统计信息
+ */
+interface PerformanceStats {
+    /** API响应时间统计 */
+    apiResponseTimes: {
+        /** 平均响应时间（毫秒） */
+        average: number;
+        /** 最小响应时间 */
+        min: number;
+        /** 最大响应时间 */
+        max: number;
+        /** P95响应时间 */
+        p95: number;
+        /** P99响应时间 */
+        p99: number;
+        /** 总请求数 */
+        totalRequests: number;
+    };
+    /** 数据库查询性能 */
+    databasePerformance: {
+        /** 平均查询时间（毫秒） */
+        averageQueryTime: number;
+        /** 慢查询数量 */
+        slowQueries: number;
+        /** 总查询数 */
+        totalQueries: number;
+        /** 查询错误数 */
+        queryErrors: number;
+    };
+    /** 文件操作性能 */
+    fileOperations: {
+        /** 文件上传统计 */
+        uploads: {
+            /** 总上传数 */
+            total: number;
+            /** 成功上传数 */
+            successful: number;
+            /** 失败上传数 */
+            failed: number;
+            /** 平均上传时间 */
+            averageTime: number;
+            /** 平均文件大小 */
+            averageSize: number;
+        };
+        /** 文件下载统计 */
+        downloads: {
+            /** 总下载数 */
+            total: number;
+            /** 成功下载数 */
+            successful: number;
+            /** 失败下载数 */
+            failed: number;
+            /** 平均下载时间 */
+            averageTime: number;
+        };
+    };
+    /** 系统资源使用 */
+    systemResources: {
+        /** 内存使用量（MB） */
+        memoryUsage: number;
+        /** CPU使用率（%） */
+        cpuUsage: number;
+        /** 磁盘使用量（MB） */
+        diskUsage: number;
+    };
+}
+/**
+ * 请求跟踪信息
+ */
+interface RequestTrace {
+    /** 请求ID */
+    requestId: string;
+    /** 请求路径 */
+    path: string;
+    /** HTTP方法 */
+    method: string;
+    /** 开始时间 */
+    startTime: number;
+    /** 结束时间 */
+    endTime?: number;
+    /** 响应时间（毫秒） */
+    duration?: number;
+    /** 状态码 */
+    statusCode?: number;
+    /** 错误信息 */
+    error?: string;
+    /** 用户ID */
+    userId?: string;
+    /** 文件大小（字节） */
+    fileSize?: number;
+}
+/**
+ * 性能监控器
+ */
+declare class PerformanceMonitor {
+    private metrics;
+    private requestTraces;
+    private stats;
+    private readonly maxMetrics;
+    private readonly maxTraces;
+    constructor();
+    /**
+     * 初始化统计信息
+     */
+    private initializeStats;
+    /**
+     * 开始请求跟踪
+     */
+    startRequest(requestId: string, path: string, method: string, userId?: string): void;
+    /**
+     * 结束请求跟踪
+     */
+    endRequest(requestId: string, statusCode: number, error?: string, fileSize?: number): void;
+    /**
+     * 记录数据库查询性能
+     */
+    recordDatabaseQuery(queryTime: number, isError?: boolean): void;
+    /**
+     * 记录系统资源使用情况
+     */
+    recordSystemResources(): void;
+    /**
+     * 记录自定义指标
+     */
+    recordMetric(name: string, value: number, unit: string, labels?: Record<string, string>): void;
+    /**
+     * 获取性能统计信息
+     */
+    getStats(): PerformanceStats;
+    /**
+     * 获取指定时间范围内的指标
+     */
+    getMetrics(name?: string, startTime?: number, endTime?: number): PerformanceMetric[];
+    /**
+     * 获取请求跟踪信息
+     */
+    getRequestTraces(limit?: number): RequestTrace[];
+    /**
+     * 获取慢请求列表
+     */
+    getSlowRequests(threshold?: number): RequestTrace[];
+    /**
+     * 获取错误请求列表
+     */
+    getErrorRequests(): RequestTrace[];
+    /**
+     * 生成性能报告
+     */
+    generateReport(): {
+        summary: any;
+        topSlowRequests: RequestTrace[];
+        recentErrors: RequestTrace[];
+        systemHealth: any;
+    };
+    /**
+     * 更新API统计信息
+     */
+    private updateApiStats;
+    /**
+     * 更新上传统计信息
+     */
+    private updateUploadStats;
+    /**
+     * 更新下载统计信息
+     */
+    private updateDownloadStats;
+    /**
+     * 清理过期数据
+     */
+    private cleanupOldData;
+    /**
+     * 重置统计信息
+     */
+    reset(): void;
+}
+
+/**
+ * CDN缓存策略管理
+ * 优化静态资源缓存策略和预热机制
+ */
+/**
+ * 缓存策略类型
+ */
+declare enum CacheStrategyType {
+    /** 图片资源 */
+    IMAGE = "image",
+    /** 视频资源 */
+    VIDEO = "video",
+    /** 音频资源 */
+    AUDIO = "audio",
+    /** 文档资源 */
+    DOCUMENT = "document",
+    /** 压缩包 */
+    ARCHIVE = "archive",
+    /** 静态资源 */
+    STATIC = "static",
+    /** 其他 */
+    OTHER = "other"
+}
+/**
+ * 缓存策略配置
+ */
+interface CacheStrategyConfig {
+    /** 缓存策略类型 */
+    type: CacheStrategyType;
+    /** 缓存时间（秒） */
+    ttl: number;
+    /** 是否启用浏览器缓存 */
+    browserCache: boolean;
+    /** 浏览器缓存时间（秒） */
+    browserCacheTtl: number;
+    /** 是否启用CDN缓存 */
+    cdnCache: boolean;
+    /** CDN缓存时间（秒） */
+    cdnCacheTtl: number;
+    /** 是否启用预热 */
+    enableWarmup: boolean;
+    /** 缓存控制头 */
+    cacheControl: string;
+    /** 允许的文件类型 */
+    allowedMimeTypes: string[];
+    /** 文件大小限制（字节） */
+    maxFileSize?: number;
+}
+/**
+ * 缓存统计信息
+ */
+interface CacheStats {
+    /** 命中次数 */
+    hits: number;
+    /** 未命中次数 */
+    misses: number;
+    /** 命中率 */
+    hitRate: number;
+    /** 总请求数 */
+    totalRequests: number;
+    /** 缓存大小估算 */
+    estimatedSize: number;
+    /** 节省的带宽（字节） */
+    bandwidthSaved: number;
+}
+/**
+ * CDN缓存策略管理器
+ */
+declare class CdnCacheStrategy {
+    private strategies;
+    private stats;
+    constructor();
+    /**
+     * 初始化默认缓存策略
+     */
+    private initializeDefaultStrategies;
+    /**
+     * 根据MIME类型获取缓存策略
+     */
+    getStrategyByMimeType(mimeType: string): CacheStrategyConfig;
+    /**
+     * 生成缓存控制头
+     */
+    generateCacheHeaders(mimeType: string, fileSize?: number): Record<string, string>;
+    /**
+     * 检查是否需要缓存预热
+     */
+    shouldWarmupCache(mimeType: string): boolean;
+    /**
+     * 记录缓存命中
+     */
+    recordCacheHit(mimeType: string, fileSize?: number): void;
+    /**
+     * 记录缓存未命中
+     */
+    recordCacheMiss(mimeType: string, fileSize?: number): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getCacheStats(): Map<CacheStrategyType, CacheStats>;
+    /**
+     * 获取总体缓存统计
+     */
+    getOverallStats(): CacheStats;
+    /**
+     * 生成缓存优化建议
+     */
+    generateOptimizationSuggestions(): Array<{
+        type: CacheStrategyType;
+        issue: string;
+        suggestion: string;
+        severity: 'low' | 'medium' | 'high';
+    }>;
+    /**
+     * 更新缓存策略
+     */
+    updateStrategy(type: CacheStrategyType, config: Partial<CacheStrategyConfig>): void;
+    /**
+     * 重置统计信息
+     */
+    resetStats(): void;
+}
+
+/**
+ * 通用文件服务 API 类型定义
+ * 定义所有API接口的请求和响应格式
+ */
+/**
+ * API响应的基础接口
+ */
+interface ApiResponse<T = any> {
+    /** 是否成功 */
+    success: boolean;
+    /** 响应数据 */
+    data?: T;
+    /** 错误信息 */
+    error?: {
+        /** 错误代码 */
+        code: string;
+        /** 错误消息 */
+        message: string;
+        /** 详细错误信息 */
+        details?: any;
+    };
+    /** 元数据 */
+    meta?: {
+        /** 总记录数 */
+        total?: number;
+        /** 当前页码 */
+        page?: number;
+        /** 每页大小 */
+        pageSize?: number;
+        /** 总页数 */
+        totalPages?: number;
+        /** 请求ID */
+        requestId?: string;
+        /** 时间戳 */
+        timestamp?: string;
+    };
+}
+/**
+ * 分页查询参数
+ */
+interface PaginationParams {
+    /** 页码，从1开始 */
+    page?: number;
+    /** 每页大小 */
+    pageSize?: number;
+    /** 排序字段 */
+    orderBy?: string;
+    /** 排序方向 */
+    orderDirection?: 'asc' | 'desc';
+}
+/**
+ * 文件上传响应
+ */
+interface UploadResponse {
+    /** 文件ID */
+    fileId: string;
+    /** 原始文件名 */
+    originalName: string;
+    /** 文件大小 */
+    size: number;
+    /** MIME类型 */
+    mimeType: string;
+    /** 访问URL */
+    url: string;
+    /** CDN URL */
+    cdnUrl?: string;
+    /** MD5哈希 */
+    md5Hash: string;
+    /** 上传时间 */
+    uploadTime: string;
+}
+/**
+ * 文件上传请求参数
+ */
+interface FileUploadParams {
+    /** 目标文件夹ID */
+    folderId?: string;
+    /** 模块ID */
+    moduleId?: string;
+    /** 业务ID */
+    businessId?: string;
+    /** 文件标签 */
+    tags?: string[];
+    /** 是否为临时文件 */
+    isTemporary?: boolean;
+    /** 过期时间 */
+    expiresAt?: string;
+    /** 自定义元数据 */
+    metadata?: Record<string, any>;
+}
+/**
+ * 文件查询参数
+ */
+interface FileQueryParams extends PaginationParams {
+    /** 模块ID */
+    moduleId?: string;
+    /** 业务ID */
+    businessId?: string;
+    /** 文件夹ID */
+    folderId?: string;
+    /** MIME类型过滤 */
+    mimeType?: string;
+    /** 文件名搜索 */
+    search?: string;
+    /** 标签过滤 */
+    tags?: string[];
+    /** 文件大小范围 */
+    sizeMin?: number;
+    sizeMax?: number;
+    /** 上传时间范围 */
+    uploadTimeStart?: string;
+    uploadTimeEnd?: string;
+    /** 是否已删除 */
+    isDeleted?: boolean;
+    /** 是否临时文件 */
+    isTemporary?: boolean;
+    /** 上传者ID */
+    uploaderId?: string;
+}
+/**
+ * 文件信息响应
+ */
+interface FileInfo {
+    /** 文件ID */
+    id: string;
+    /** 原始文件名 */
+    originalName: string;
+    /** 存储文件名 */
+    storedName: string;
+    /** 文件扩展名 */
+    extension?: string;
+    /** MIME类型 */
+    mimeType: string;
+    /** 文件大小 */
+    size: number;
+    /** MD5哈希 */
+    md5Hash: string;
+    /** SHA256哈希 */
+    sha256Hash?: string;
+    /** 存储路径 */
+    storagePath: string;
+    /** CDN访问URL */
+    cdnUrl?: string;
+    /** 所属文件夹ID */
+    folderId?: string;
+    /** 模块ID */
+    moduleId?: string;
+    /** 业务ID */
+    businessId?: string;
+    /** 文件标签 */
+    tags?: string[];
+    /** 文件元信息 */
+    metadata?: Record<string, any>;
+    /** 是否为临时文件 */
+    isTemporary: boolean;
+    /** 是否已删除 */
+    isDeleted: boolean;
+    /** 访问次数 */
+    accessCount: number;
+    /** 下载次数 */
+    downloadCount: number;
+    /** 上传者ID */
+    uploaderId: string;
+    /** 上传时间 */
+    uploadTime: string;
+    /** 最后访问时间 */
+    lastAccessTime?: string;
+    /** 过期时间 */
+    expiresAt?: string;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+}
+/**
+ * 文件列表响应
+ */
+interface FileListResponse {
+    /** 文件列表 */
+    files: FileInfo[];
+    /** 分页信息 */
+    pagination: {
+        /** 总记录数 */
+        total: number;
+        /** 当前页码 */
+        page: number;
+        /** 每页大小 */
+        pageSize: number;
+        /** 总页数 */
+        totalPages: number;
+    };
+}
+/**
+ * 文件更新参数
+ */
+interface FileUpdateParams {
+    /** 新的文件名 */
+    originalName?: string;
+    /** 文件夹ID */
+    folderId?: string;
+    /** 文件标签 */
+    tags?: string[];
+    /** 自定义元数据 */
+    metadata?: Record<string, any>;
+    /** 过期时间 */
+    expiresAt?: string;
+}
+/**
+ * 文件夹创建参数
+ */
+interface FolderCreateParams {
+    /** 文件夹名称 */
+    name: string;
+    /** 父文件夹ID */
+    parentId?: string;
+    /** 模块ID */
+    moduleId?: string;
+    /** 业务ID */
+    businessId?: string;
+    /** 文件夹描述 */
+    description?: string;
+    /** 显示顺序 */
+    sortOrder?: number;
+}
+/**
+ * 文件夹信息响应
+ */
+interface FolderInfo {
+    /** 文件夹ID */
+    id: string;
+    /** 文件夹名称 */
+    name: string;
+    /** 父文件夹ID */
+    parentId?: string;
+    /** 模块ID */
+    moduleId?: string;
+    /** 业务ID */
+    businessId?: string;
+    /** 文件夹路径 */
+    path: string;
+    /** 层级深度 */
+    depth: number;
+    /** 显示顺序 */
+    sortOrder: number;
+    /** 文件夹描述 */
+    description?: string;
+    /** 是否为系统文件夹 */
+    isSystem: boolean;
+    /** 创建者ID */
+    createdBy: string;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+    /** 子文件夹列表 */
+    children?: FolderInfo[];
+    /** 文件数量 */
+    fileCount?: number;
+}
+/**
+ * 文件夹更新参数
+ */
+interface FolderUpdateParams {
+    /** 文件夹名称 */
+    name?: string;
+    /** 父文件夹ID */
+    parentId?: string;
+    /** 文件夹描述 */
+    description?: string;
+    /** 显示顺序 */
+    sortOrder?: number;
+}
+/**
+ * 文件处理请求参数
+ */
+interface FileProcessParams {
+    /** 处理类型 */
+    type: 'compress' | 'resize' | 'convert' | 'thumbnail' | 'watermark';
+    /** 处理参数 */
+    parameters: Record<string, any>;
+    /** 优先级 */
+    priority?: number;
+}
+/**
+ * 文件处理状态响应
+ */
+interface ProcessingStatus {
+    /** 处理记录ID */
+    id: string;
+    /** 文件ID */
+    fileId: string;
+    /** 处理类型 */
+    type: string;
+    /** 处理状态 */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** 处理进度 */
+    progress?: number;
+    /** 处理参数 */
+    parameters?: Record<string, any>;
+    /** 处理结果 */
+    result?: Record<string, any>;
+    /** 输出文件路径 */
+    outputPath?: string;
+    /** 错误信息 */
+    errorMessage?: string;
+    /** 开始时间 */
+    startedAt?: string;
+    /** 完成时间 */
+    completedAt?: string;
+    /** 创建时间 */
+    createdAt: string;
+}
+/**
+ * 文件分享创建参数
+ */
+interface ShareCreateParams {
+    /** 分享的文件ID列表 */
+    fileIds: string[];
+    /** 分享标题 */
+    title?: string;
+    /** 分享描述 */
+    description?: string;
+    /** 访问密码 */
+    password?: string;
+    /** 访问权限 */
+    permission?: 'view' | 'download';
+    /** 最大下载次数 */
+    maxDownloads?: number;
+    /** 最大访问次数 */
+    maxAccess?: number;
+    /** 过期时间 */
+    expiresAt?: string;
+}
+/**
+ * 文件分享信息响应
+ */
+interface ShareInfo {
+    /** 分享ID */
+    id: string;
+    /** 分享代码 */
+    shareCode: string;
+    /** 分享的文件ID列表 */
+    fileIds: string[];
+    /** 分享标题 */
+    title?: string;
+    /** 分享描述 */
+    description?: string;
+    /** 是否有密码保护 */
+    hasPassword: boolean;
+    /** 访问权限 */
+    permission: 'view' | 'download';
+    /** 最大下载次数 */
+    maxDownloads?: number;
+    /** 当前下载次数 */
+    downloadCount: number;
+    /** 最大访问次数 */
+    maxAccess?: number;
+    /** 当前访问次数 */
+    accessCount: number;
+    /** 是否启用 */
+    isActive: boolean;
+    /** 过期时间 */
+    expiresAt?: string;
+    /** 创建者ID */
+    createdBy: string;
+    /** 创建时间 */
+    createdAt: string;
+    /** 分享链接 */
+    shareUrl: string;
+}
+/**
+ * 分享访问验证参数
+ */
+interface ShareAccessParams {
+    /** 分享代码 */
+    shareCode: string;
+    /** 访问密码 */
+    password?: string;
+}
+/**
+ * 文件统计信息响应
+ */
+interface FileStats {
+    /** 总文件数 */
+    totalFiles: number;
+    /** 总文件大小 */
+    totalSize: number;
+    /** 按类型统计 */
+    byType: Array<{
+        /** MIME类型 */
+        mimeType: string;
+        /** 文件数量 */
+        count: number;
+        /** 总大小 */
+        totalSize: number;
+    }>;
+    /** 按日期统计（最近30天） */
+    byDate: Array<{
+        /** 日期 */
+        date: string;
+        /** 上传数量 */
+        count: number;
+        /** 总大小 */
+        totalSize: number;
+    }>;
+    /** 按模块统计 */
+    byModule: Array<{
+        /** 模块ID */
+        moduleId: string;
+        /** 文件数量 */
+        count: number;
+        /** 总大小 */
+        totalSize: number;
+    }>;
+}
+/**
+ * API错误代码枚举
+ */
+declare enum ApiErrorCode {
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    AUTHENTICATION_ERROR = "AUTHENTICATION_ERROR",
+    AUTHORIZATION_ERROR = "AUTHORIZATION_ERROR",
+    NOT_FOUND = "NOT_FOUND",
+    CONFLICT = "CONFLICT",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    FILE_NOT_FOUND = "FILE_NOT_FOUND",
+    FILE_TOO_LARGE = "FILE_TOO_LARGE",
+    FILE_TYPE_NOT_SUPPORTED = "FILE_TYPE_NOT_SUPPORTED",
+    FILE_UPLOAD_FAILED = "FILE_UPLOAD_FAILED",
+    FILE_PROCESSING_FAILED = "FILE_PROCESSING_FAILED",
+    FILE_ALREADY_EXISTS = "FILE_ALREADY_EXISTS",
+    FILE_CORRUPTED = "FILE_CORRUPTED",
+    FOLDER_NOT_FOUND = "FOLDER_NOT_FOUND",
+    FOLDER_NOT_EMPTY = "FOLDER_NOT_EMPTY",
+    FOLDER_NAME_CONFLICT = "FOLDER_NAME_CONFLICT",
+    FOLDER_DEPTH_EXCEEDED = "FOLDER_DEPTH_EXCEEDED",
+    STORAGE_PROVIDER_ERROR = "STORAGE_PROVIDER_ERROR",
+    STORAGE_QUOTA_EXCEEDED = "STORAGE_QUOTA_EXCEEDED",
+    STORAGE_UNAVAILABLE = "STORAGE_UNAVAILABLE",
+    SHARE_NOT_FOUND = "SHARE_NOT_FOUND",
+    SHARE_EXPIRED = "SHARE_EXPIRED",
+    SHARE_PASSWORD_INCORRECT = "SHARE_PASSWORD_INCORRECT",
+    SHARE_ACCESS_DENIED = "SHARE_ACCESS_DENIED",
+    SHARE_DOWNLOAD_LIMIT_EXCEEDED = "SHARE_DOWNLOAD_LIMIT_EXCEEDED"
+}
+/**
+ * 错误消息映射
+ */
+declare const ErrorMessages: Record<ApiErrorCode, string>;
+/**
+ * 错误代码到HTTP状态码的映射
+ */
+declare const ErrorHttpStatusMap: Record<ApiErrorCode, number>;
+
+/**
+ * API错误处理工具类
+ * 提供标准化的错误处理和响应格式
+ */
+
+/**
+ * API错误类
+ * 继承自Error，添加错误代码和详细信息
+ */
+declare class ApiError extends Error {
+    readonly code: ApiErrorCode;
+    readonly statusCode: number;
+    readonly details?: any;
+    constructor(code: ApiErrorCode, message?: string, details?: any, statusCode?: number);
+    /**
+     * 转换为API响应格式
+     */
+    toApiResponse(): ApiResponse;
+    /**
+     * 转换为NextResponse
+     */
+    toNextResponse(): NextResponse;
+}
+
+/**
+ * Drizzle ORM 文件元数据持久化适配器
+ *
+ * 提供基于 Drizzle ORM 的数据库持久化实现
+ */
+
+/**
+ * Drizzle 表定义类型（兼容多种 Drizzle 表结构）
+ */
+type DrizzleTable = any;
+/**
+ * Drizzle 数据库连接类型
+ */
+type DrizzleDb = any;
+/**
+ * 字段映射配置
+ *
+ * 将 FileMetadata 的字段映射到数据库表的列名
+ */
+interface FieldMapping {
+    id?: string;
+    filename?: string;
+    originalName?: string;
+    mimeType?: string;
+    size?: string;
+    hash?: string;
+    storageType?: string;
+    storagePath?: string;
+    url?: string;
+    cdnUrl?: string;
+    moduleId?: string;
+    businessId?: string;
+    userId?: string;
+    uploadedAt?: string;
+    expiresAt?: string;
+    metadata?: string;
+    status?: string;
+    processingStatus?: string;
+    versions?: string;
+    tags?: string;
+}
+/**
+ * Drizzle 仓储配置
+ */
+interface DrizzleRepositoryConfig {
+    /** Drizzle 数据库实例 */
+    db: DrizzleDb;
+    /** 文件元数据表 */
+    table: DrizzleTable;
+    /** 字段映射（如果数据库列名与 FileMetadata 字段不同） */
+    fieldMapping?: FieldMapping;
+}
+/**
+ * 创建 Drizzle ORM 文件仓储
+ *
+ * @example
+ * ```typescript
+ * import { createDrizzleRepository } from '@qhr123/sa2kit/universalFile/server';
+ * import { db } from './db';
+ * import { fileMetadata } from './schema';
+ *
+ * const repository = createDrizzleRepository({
+ *   db,
+ *   table: fileMetadata,
+ *   fieldMapping: {
+ *     // 如果列名与 FileMetadata 字段不同，可以在这里映射
+ *     originalName: 'original_filename',
+ *   }
+ * });
+ * ```
+ */
+declare function createDrizzleRepository(config: DrizzleRepositoryConfig): IFileMetadataRepository;
+
+export { type AliyunCDNConfig, AliyunCDNProvider, type AliyunOSSConfig, AliyunOSSProvider, ApiError, ApiErrorCode, type ApiResponse, AudioProcessor, type CDNConfig, CDNProviderError, type CDNResult, type CDNStats, type CDNType, type CacheConfig, CacheManager, CacheStrategyType$1 as CacheStrategyType, CdnCacheStrategy, ConfigValidationError, type DrizzleDb, type DrizzleRepositoryConfig, type DrizzleTable, ErrorHttpStatusMap, ErrorMessages, type FieldMapping, type FileEvent, type FileEventListener, type FileEventType, type FileInfo, type FileListResponse, type FileProcessParams, FileProcessingError, type FileQueryOptions, type FileQueryParams, type FileRecord, FileServiceError, type FileServicePersistenceConfig, type FileStats, type FileUpdateParams, FileUploadError, type FileUploadParams, type FolderCreateParams, type FolderInfo, type FolderUpdateParams, type ICDNProvider, type IFileMetadataRepository, type IFileProcessor, type IStorageProvider, ImageProcessor, type LocalStorageConfig, LocalStorageProvider, type PaginatedResult, type PaginationParams, PerformanceMonitor, type ProcessingOptions, ProcessingQueue, type ProcessingResult, type ProcessingStatus, type ProcessorInfo, type ProcessorType, type ShareAccessParams, type ShareCreateParams, type ShareInfo, type StorageConfig, type StorageMetadata, StorageProviderError, type StorageResult, type StorageType, UniversalFileService, type UniversalFileServiceConfig, type UploadFileInfo, type UploadResponse, VideoProcessor, cdnCacheStrategy, createAliyunOSSPreset, createDocumentServicePreset, createDrizzleRepository, createFileServiceConfig, createFileServiceFromEnv, createImageServicePreset, createLocalDevPreset, createSmartPreset, createUniversalFileService, createVideoServicePreset, getMimeType, getRequiredEnvVars, validateEnvironment, validateServiceConfig, validateStorageConfig };