Builder6 Files Module

Builder6 Files 模块为 Builder6 平台提供完整的文件管理功能，包括文件上传、下载、存储管理以及邮件队列处理。该模块支持多种存储后端，提供灵活的文件访问控制和自动化邮件发送功能。

功能特性

• 文件上传/下载: 支持文件的上传和下载操作
• 存储管理: 灵活的文件存储抽象层，支持多种存储后端
• 访问控制: 可配置的文件访问权限，支持公开和私有文件
• 集合管理: 基于集合（collections）的文件组织方式
• 匿名下载: 支持特定集合的匿名文件下载
• 邮件集成: 内置邮件发送功能，支持附件处理
• 邮件队列: 定时邮件发送队列，支持批量邮件处理
• 文件元数据: 自动管理文件元数据信息

安装

npm install @builder6/files

或

yarn add @builder6/files

环境变量

文件访问控制

# 允许匿名下载的 collections（逗号分隔）
STEEDOS_CFS_DOWNLOAD_PUBLIC=avatars,public-assets,logos

# 示例：只允许 avatars 匿名下载
STEEDOS_CFS_DOWNLOAD_PUBLIC=avatars

邮件队列配置

# 邮件定时器间隔，单位：毫秒（默认 3000ms = 3秒）
STEEDOS_CRON_MAILQUEUE_INTERVAL=3000

# 批量发送邮件数量
STEEDOS_CRON_MAILQUEUE_BATCH_SIZE=10

文件存储配置

# 文件存储路径
STEEDOS_STORAGE_DIR=/app/storage/files

# 最大文件大小（字节）
STEEDOS_CFS_FILE_MAX_SIZE=10485760

# 允许的文件类型（逗号分隔）
STEEDOS_CFS_FILE_ALLOWED_TYPES=image/*,application/pdf,text/*

使用示例

在 NestJS 应用中集成

import { Module } from '@nestjs/common';
import { FilesModule } from '@builder6/files';

@Module({
  imports: [FilesModule],
})
export class AppModule {}

使用 FilesService

import { FilesService } from '@builder6/files';

constructor(private filesService: FilesService) {}

// 上传文件
async uploadFile(file: Express.Multer.File, collection: string) {
  const fileRecord = await this.filesService.upload(file, {
    collection,
    metadata: {
      uploadedBy: 'userId',
      description: 'Sample file'
    }
  });
  return fileRecord;
}

// 下载文件
async downloadFile(fileId: string) {
  const fileStream = await this.filesService.download(fileId);
  return fileStream;
}

// 删除文件
async deleteFile(fileId: string) {
  await this.filesService.delete(fileId);
}

// 获取文件元数据
async getFileMetadata(fileId: string) {
  const metadata = await this.filesService.getMetadata(fileId);
  return metadata;
}

邮件队列使用

import { MailQueueService } from '@builder6/files';

constructor(private mailQueueService: MailQueueService) {}

// 添加邮件到队列
async queueEmail(emailData: any) {
  await this.mailQueueService.addToQueue({
    to: '[email protected]',
    subject: 'Welcome',
    html: '<h1>Welcome to Builder6</h1>',
    attachments: [
      {
        filename: 'document.pdf',
        path: '/path/to/file.pdf'
      }
    ]
  });
}

文件集合（Collections）

文件集合是组织和管理文件的逻辑单元。每个集合可以有不同的访问权限和存储策略。

常用集合

• avatars: 用户头像（通常设为公开）
• attachments: 附件文件（通常需要认证）
• images: 图片资源
• documents: 文档文件
• public-assets: 公共资源文件

配置匿名访问

只有在 STEEDOS_CFS_DOWNLOAD_PUBLIC 中列出的集合才允许匿名下载：

STEEDOS_CFS_DOWNLOAD_PUBLIC=avatars,public-assets

邮件队列定时器

邮件队列定时器会定期检查待发送的邮件并进行发送。可以通过环境变量调整检查间隔：

# 每 5 秒检查一次邮件队列
STEEDOS_CRON_MAILQUEUE_INTERVAL=5000

# 每次处理 20 封邮件
STEEDOS_CRON_MAILQUEUE_BATCH_SIZE=20

API 端点

模块提供以下主要 API 端点（具体路径根据配置可能不同）：

• POST /api/files/upload: 上传文件
• GET /api/files/download/:fileId: 下载文件
• GET /api/files/:fileId/metadata: 获取文件元数据
• DELETE /api/files/:fileId: 删除文件
• GET /api/files/collections/:collection: 列出集合中的文件

存储后端

模块支持多种存储后端：

• 本地文件系统: 默认存储方式
• GridFS: MongoDB GridFS 存储
• S3: Amazon S3 或兼容的对象存储
• 自定义存储: 可扩展的存储适配器接口

依赖项

主要依赖

• nodemailer: ^7.0.11 - 邮件发送功能

Peer Dependencies

• @builder6/core: ^3.0.10 - 核心功能模块
• @builder6/moleculer: ^3.0.10 - 微服务框架
• @nestjs/common: ^11.0.0 - NestJS 核心
• @nestjs/core: ^11.0.0 - NestJS 核心
• @nestjs/swagger: ^11.0.7 - API 文档

开发

构建

npm run build

监听模式

npm run build:watch

格式化代码

npm run format

使用场景

• 用户头像管理: 存储和管理用户头像文件
• 附件处理: 处理表单、邮件等的附件文件
• 文档管理: 管理各类文档和资料
• 邮件发送: 批量邮件发送和队列管理
• 公共资源: 存储和分发公共静态资源

安全注意事项

1. 访问控制: 谨慎配置 STEEDOS_CFS_DOWNLOAD_PUBLIC，避免敏感文件公开
2. 文件大小限制: 设置合理的 STEEDOS_CFS_FILE_MAX_SIZE 防止滥用
3. 文件类型验证: 使用 STEEDOS_CFS_FILE_ALLOWED_TYPES 限制文件类型
4. 路径遍历: 模块内部已防护路径遍历攻击
5. 病毒扫描: 建议在生产环境集成病毒扫描

License

MIT