当前位置：首页 > news >正文

flat-server云存储集成实战：阿里云OSS与文件管理全流程

news 2026/8/5 16:38:15

flat-server云存储集成实战：阿里云OSS与文件管理全流程

【免费下载链接】flat-serverA Node.js server for the Agora Flat open source classroom.项目地址: https://gitcode.com/gh_mirrors/fl/flat-server

flat-server是Agora Flat开源教室的Node.js服务端实现，提供了完整的云存储解决方案。本文将详细介绍如何在flat-server中集成阿里云OSS，实现文件上传、管理、转换的全流程操作，帮助开发者快速掌握云存储功能的配置与使用。

阿里云OSS集成核心架构

flat-server采用抽象化设计模式实现云存储功能，通过OSSAbstract接口定义标准操作，阿里云OSS作为具体实现提供服务。核心实现代码位于src/v2/services/oss/ali-oss.ts，主要包含以下功能模块：

文件操作：支持文件上传、删除、重命名等基础操作
目录管理：提供递归删除目录的能力
权限控制：基于Policy和Signature的安全上传机制
合规检查：集成文本内容合规性验证

OSS服务类结构

AliOSSService类实现了OSSAbstract接口，关键方法包括：

// 检查文件是否存在 public async exists(filePath: string): Promise<boolean> // 递归删除目录 public async recursionRemove(directory: string, marker?: string): Promise<void> // 生成上传策略 public policyTemplate( fileName: string, filePath: string, fileSize: number, expiration = 60 * 2 ): { policy: string; signature: string }

快速配置阿里云OSS

要启用阿里云OSS集成，需要在配置文件中设置相关参数。配置常量定义在src/constants/Config.ts，主要包括：

export const StorageService = { oss: { bucket: "your-bucket-name", endpoint: "oss-cn-beijing.aliyuncs.com", accessKeyId: "your-access-key-id", accessKeySecret: "your-access-key-secret" } }

配置完成后，系统会自动初始化OSS客户端，通过服务定位器模式提供全局访问。

文件上传全流程实现

flat-server的文件上传采用前端直传OSS的方式，服务端负责生成上传凭证和处理后续回调。完整流程实现位于src/v2/controllers/cloud-storage/upload/start.ts。

上传流程步骤

请求验证：验证文件名、大小和目录路径合法性
合规检查：通过complianceText服务检查文件名合规性
生成上传凭证：调用policyTemplate方法生成带签名的上传策略
返回上传参数：包括OSS上传地址、表单字段和文件元信息

核心代码实现

// 上传初始化处理 export const cloudStorageUploadStart = async ( req: FastifyRequestTypebox<typeof cloudStorageUploadStartSchema>, ): Promise<Response<Static<typeof uploadStartReturnSchema>>> => { // 合规性检查 const complianceText = useOnceService("complianceText", req.ids); await complianceText.assertTextNormal(req.body.fileName); // 初始化上传服务 const cloudStorageUploadSVC = new CloudStorageUploadService( req.ids, req.DBTransaction, req.userUUID, ); // 生成上传参数 const result = await cloudStorageUploadSVC.start({ fileName: req.body.fileName, fileSize: req.body.fileSize, targetDirectoryPath: req.body.targetDirectoryPath, convertType: req.body.convertType, }); return successJSON(result); };

文件管理功能详解

flat-server提供了完整的文件管理功能，包括文件列表、重命名、移动和删除等操作，相关实现位于src/v2/services/cloud-storage/目录。

文件列表与查询

文件列表功能通过src/v2/controllers/cloud-storage/list/index.ts实现，支持按目录路径、文件类型等条件筛选，并返回文件元信息和访问URL。

文件删除实现

文件删除功能支持单文件和批量删除，递归删除目录功能实现如下：

// 递归删除目录及其内容 public async recursionRemove(directory: string, marker?: string): Promise<void> { const files = await aliOSSClient.list({ prefix: directory, marker: marker, "max-keys": 500, }); if (files.objects && files.objects.length !== 0) { const names = files.objects.map(file => file.name); await aliOSSClient.deleteMulti(names); } if (files.isTruncated) { await this.recursionRemove(directory, files.nextMarker); } }