@builder6/files 3.2.1 → 3.2.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,15 +1,240 @@
|
|
|
1
1
|
# Builder6 Files Module
|
|
2
2
|
|
|
3
|
+
Builder6 Files 模块为 Builder6 平台提供完整的文件管理功能，包括文件上传、下载、存储管理以及邮件队列处理。该模块支持多种存储后端，提供灵活的文件访问控制和自动化邮件发送功能。
|
|
3
4
|
|
|
4
|
-
##
|
|
5
|
+
## 功能特性
|
|
5
6
|
|
|
6
|
-
|
|
7
|
-
|
|
7
|
+
- **文件上传/下载**: 支持文件的上传和下载操作
|
|
8
|
+
- **存储管理**: 灵活的文件存储抽象层，支持多种存储后端
|
|
9
|
+
- **访问控制**: 可配置的文件访问权限，支持公开和私有文件
|
|
10
|
+
- **集合管理**: 基于集合（collections）的文件组织方式
|
|
11
|
+
- **匿名下载**: 支持特定集合的匿名文件下载
|
|
12
|
+
- **邮件集成**: 内置邮件发送功能，支持附件处理
|
|
13
|
+
- **邮件队列**: 定时邮件发送队列，支持批量邮件处理
|
|
14
|
+
- **文件元数据**: 自动管理文件元数据信息
|
|
15
|
+
|
|
16
|
+
## 安装
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @builder6/files
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
或
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
yarn add @builder6/files
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## 环境变量
|
|
29
|
+
|
|
30
|
+
### 文件访问控制
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# 允许匿名下载的 collections（逗号分隔）
|
|
34
|
+
STEEDOS_CFS_DOWNLOAD_PUBLIC=avatars,public-assets,logos
|
|
35
|
+
|
|
36
|
+
# 示例：只允许 avatars 匿名下载
|
|
8
37
|
STEEDOS_CFS_DOWNLOAD_PUBLIC=avatars
|
|
9
38
|
```
|
|
10
39
|
|
|
11
|
-
|
|
40
|
+
### 邮件队列配置
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# 邮件定时器间隔，单位：毫秒（默认 3000ms = 3秒）
|
|
44
|
+
STEEDOS_CRON_MAILQUEUE_INTERVAL=3000
|
|
45
|
+
|
|
46
|
+
# 批量发送邮件数量
|
|
47
|
+
STEEDOS_CRON_MAILQUEUE_BATCH_SIZE=10
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### 文件存储配置
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
# 文件存储路径
|
|
54
|
+
STEEDOS_STORAGE_DIR=/app/storage/files
|
|
55
|
+
|
|
56
|
+
# 最大文件大小（字节）
|
|
57
|
+
STEEDOS_CFS_FILE_MAX_SIZE=10485760
|
|
58
|
+
|
|
59
|
+
# 允许的文件类型（逗号分隔）
|
|
60
|
+
STEEDOS_CFS_FILE_ALLOWED_TYPES=image/*,application/pdf,text/*
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## 使用示例
|
|
64
|
+
|
|
65
|
+
### 在 NestJS 应用中集成
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
import { Module } from '@nestjs/common';
|
|
69
|
+
import { FilesModule } from '@builder6/files';
|
|
70
|
+
|
|
71
|
+
@Module({
|
|
72
|
+
imports: [FilesModule],
|
|
73
|
+
})
|
|
74
|
+
export class AppModule {}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### 使用 FilesService
|
|
78
|
+
|
|
79
|
+
```typescript
|
|
80
|
+
import { FilesService } from '@builder6/files';
|
|
81
|
+
|
|
82
|
+
constructor(private filesService: FilesService) {}
|
|
83
|
+
|
|
84
|
+
// 上传文件
|
|
85
|
+
async uploadFile(file: Express.Multer.File, collection: string) {
|
|
86
|
+
const fileRecord = await this.filesService.upload(file, {
|
|
87
|
+
collection,
|
|
88
|
+
metadata: {
|
|
89
|
+
uploadedBy: 'userId',
|
|
90
|
+
description: 'Sample file'
|
|
91
|
+
}
|
|
92
|
+
});
|
|
93
|
+
return fileRecord;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// 下载文件
|
|
97
|
+
async downloadFile(fileId: string) {
|
|
98
|
+
const fileStream = await this.filesService.download(fileId);
|
|
99
|
+
return fileStream;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// 删除文件
|
|
103
|
+
async deleteFile(fileId: string) {
|
|
104
|
+
await this.filesService.delete(fileId);
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// 获取文件元数据
|
|
108
|
+
async getFileMetadata(fileId: string) {
|
|
109
|
+
const metadata = await this.filesService.getMetadata(fileId);
|
|
110
|
+
return metadata;
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### 邮件队列使用
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
import { MailQueueService } from '@builder6/files';
|
|
118
|
+
|
|
119
|
+
constructor(private mailQueueService: MailQueueService) {}
|
|
120
|
+
|
|
121
|
+
// 添加邮件到队列
|
|
122
|
+
async queueEmail(emailData: any) {
|
|
123
|
+
await this.mailQueueService.addToQueue({
|
|
124
|
+
to: 'user@example.com',
|
|
125
|
+
subject: 'Welcome',
|
|
126
|
+
html: '<h1>Welcome to Builder6</h1>',
|
|
127
|
+
attachments: [
|
|
128
|
+
{
|
|
129
|
+
filename: 'document.pdf',
|
|
130
|
+
path: '/path/to/file.pdf'
|
|
131
|
+
}
|
|
132
|
+
]
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## 文件集合（Collections）
|
|
12
138
|
|
|
139
|
+
文件集合是组织和管理文件的逻辑单元。每个集合可以有不同的访问权限和存储策略。
|
|
140
|
+
|
|
141
|
+
### 常用集合
|
|
142
|
+
|
|
143
|
+
- `avatars`: 用户头像（通常设为公开）
|
|
144
|
+
- `attachments`: 附件文件（通常需要认证）
|
|
145
|
+
- `images`: 图片资源
|
|
146
|
+
- `documents`: 文档文件
|
|
147
|
+
- `public-assets`: 公共资源文件
|
|
148
|
+
|
|
149
|
+
### 配置匿名访问
|
|
150
|
+
|
|
151
|
+
只有在 `STEEDOS_CFS_DOWNLOAD_PUBLIC` 中列出的集合才允许匿名下载：
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
STEEDOS_CFS_DOWNLOAD_PUBLIC=avatars,public-assets
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## 邮件队列定时器
|
|
158
|
+
|
|
159
|
+
邮件队列定时器会定期检查待发送的邮件并进行发送。可以通过环境变量调整检查间隔：
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
# 每 5 秒检查一次邮件队列
|
|
163
|
+
STEEDOS_CRON_MAILQUEUE_INTERVAL=5000
|
|
164
|
+
|
|
165
|
+
# 每次处理 20 封邮件
|
|
166
|
+
STEEDOS_CRON_MAILQUEUE_BATCH_SIZE=20
|
|
13
167
|
```
|
|
14
|
-
|
|
15
|
-
|
|
168
|
+
|
|
169
|
+
## API 端点
|
|
170
|
+
|
|
171
|
+
模块提供以下主要 API 端点（具体路径根据配置可能不同）：
|
|
172
|
+
|
|
173
|
+
- **POST `/api/files/upload`**: 上传文件
|
|
174
|
+
- **GET `/api/files/download/:fileId`**: 下载文件
|
|
175
|
+
- **GET `/api/files/:fileId/metadata`**: 获取文件元数据
|
|
176
|
+
- **DELETE `/api/files/:fileId`**: 删除文件
|
|
177
|
+
- **GET `/api/files/collections/:collection`**: 列出集合中的文件
|
|
178
|
+
|
|
179
|
+
## 存储后端
|
|
180
|
+
|
|
181
|
+
模块支持多种存储后端：
|
|
182
|
+
|
|
183
|
+
- **本地文件系统**: 默认存储方式
|
|
184
|
+
- **GridFS**: MongoDB GridFS 存储
|
|
185
|
+
- **S3**: Amazon S3 或兼容的对象存储
|
|
186
|
+
- **自定义存储**: 可扩展的存储适配器接口
|
|
187
|
+
|
|
188
|
+
## 依赖项
|
|
189
|
+
|
|
190
|
+
### 主要依赖
|
|
191
|
+
|
|
192
|
+
- `nodemailer`: ^7.0.11 - 邮件发送功能
|
|
193
|
+
|
|
194
|
+
### Peer Dependencies
|
|
195
|
+
|
|
196
|
+
- `@builder6/core`: ^3.0.10 - 核心功能模块
|
|
197
|
+
- `@builder6/moleculer`: ^3.0.10 - 微服务框架
|
|
198
|
+
- `@nestjs/common`: ^11.0.0 - NestJS 核心
|
|
199
|
+
- `@nestjs/core`: ^11.0.0 - NestJS 核心
|
|
200
|
+
- `@nestjs/swagger`: ^11.0.7 - API 文档
|
|
201
|
+
|
|
202
|
+
## 开发
|
|
203
|
+
|
|
204
|
+
### 构建
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
npm run build
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### 监听模式
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
npm run build:watch
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### 格式化代码
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
npm run format
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## 使用场景
|
|
223
|
+
|
|
224
|
+
- **用户头像管理**: 存储和管理用户头像文件
|
|
225
|
+
- **附件处理**: 处理表单、邮件等的附件文件
|
|
226
|
+
- **文档管理**: 管理各类文档和资料
|
|
227
|
+
- **邮件发送**: 批量邮件发送和队列管理
|
|
228
|
+
- **公共资源**: 存储和分发公共静态资源
|
|
229
|
+
|
|
230
|
+
## 安全注意事项
|
|
231
|
+
|
|
232
|
+
1. **访问控制**: 谨慎配置 `STEEDOS_CFS_DOWNLOAD_PUBLIC`，避免敏感文件公开
|
|
233
|
+
2. **文件大小限制**: 设置合理的 `STEEDOS_CFS_FILE_MAX_SIZE` 防止滥用
|
|
234
|
+
3. **文件类型验证**: 使用 `STEEDOS_CFS_FILE_ALLOWED_TYPES` 限制文件类型
|
|
235
|
+
4. **路径遍历**: 模块内部已防护路径遍历攻击
|
|
236
|
+
5. **病毒扫描**: 建议在生产环境集成病毒扫描
|
|
237
|
+
|
|
238
|
+
## License
|
|
239
|
+
|
|
240
|
+
MIT
|
|
@@ -27,7 +27,6 @@ let CMSFilesController = class CMSFilesController {
|
|
|
27
27
|
this.mongodbService = mongodbService;
|
|
28
28
|
}
|
|
29
29
|
async uploadCMSFile(file, object_name, record_id, parent, description, req) {
|
|
30
|
-
console.log('cms file upload...');
|
|
31
30
|
const newParentId = (0, uuid_1.v4)();
|
|
32
31
|
const user = req['user'];
|
|
33
32
|
if (!file) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cms_files.controller.js","sourceRoot":"","sources":["../../src/files/cms_files.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAcwB;AACxB,+DAA2D;AAC3D,mDAA+C;AAE/C,6CAMyB;AACzB,yCAAwE;AACxE,+BAAoC;AAEpC,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAIvC,IAAM,kBAAkB,GAAxB,MAAM,kBAAkB;IAC7B,YACmB,YAA0B,EAC1B,WAAwB,EACjC,cAA8B;QAFrB,iBAAY,GAAZ,YAAY,CAAc;QAC1B,gBAAW,GAAX,WAAW,CAAa;QACjC,mBAAc,GAAd,cAAc,CAAgB;IACrC,CAAC;IAuCE,AAAN,KAAK,CAAC,aAAa,CACD,IAAyB,EACpB,WAAmB,EACrB,SAAiB,EACpB,MAAc,EACT,WAAmB,EACjC,GAAY;
|
|
1
|
+
{"version":3,"file":"cms_files.controller.js","sourceRoot":"","sources":["../../src/files/cms_files.controller.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@builder6/files",
|
|
3
|
-
"version": "3.2.
|
|
3
|
+
"version": "3.2.12",
|
|
4
4
|
"main": "dist/index.js",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"files": [
|
|
@@ -24,5 +24,5 @@
|
|
|
24
24
|
"publishConfig": {
|
|
25
25
|
"access": "public"
|
|
26
26
|
},
|
|
27
|
-
"gitHead": "
|
|
27
|
+
"gitHead": "6d6e13fed8d4b3c6de14f84dcb6287c5661ea6f6"
|
|
28
28
|
}
|