切换主题
📁 业务文件夹配置
🎯 功能概述
业务文件夹配置允许您为不同的业务类型设置独立的文件存储路径，实现文件存储的隔离和管理。通过配置业务文件夹，您可以：
- ✅ 实现业务隔离：不同业务类型的文件存储在不同的文件夹中，互不干扰
- ✅ 便于文件管理：按业务类型组织文件，便于查找、备份和恢复
- ✅ 支持权限控制：可以为不同业务文件夹设置不同的访问权限
- ✅ 优化存储结构：合理组织文件存储结构，提升管理效率
- ✅ 支持所有存储类型：本地存储、OSS、COS、OBS、S3、HTTP转发均支持
⚙️ 配置说明
配置项
| 配置项 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
business-folder | String | 否 | 业务文件夹名称，上传文件路径会拼接此文件夹。如果为空，文件将直接存储在根目录下 | demo-files |
配置说明
- 业务文件夹名称会自动去除末尾的斜杠
/ - 支持使用小写字母、数字、连字符和下划线
- 建议使用有意义的名称，便于识别和管理
- 配置后，所有上传的文件（包括普通上传和分片上传）都会使用此文件夹
配置示例
基础配置
yaml
files:
- business-type: demo
file-type: local
root-path: /srv/file/data
business-folder: demo-files # 业务文件夹配置
http-access-path: https://www.wueasy.com
allowed-upload-suffix: jpg,png,gif,bmp,pdf,doc
max-size: 100MB1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
不配置业务文件夹
yaml
files:
- business-type: demo
file-type: local
root-path: /srv/file/data
# business-folder: # 不配置，文件直接存储在根目录
http-access-path: https://www.wueasy.com
allowed-upload-suffix: jpg,png,gif,bmp,pdf,doc
max-size: 100MB1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
路径对比
- 配置业务文件夹:
demo-files/2024/08/25/23/uuid.jpg - 不配置业务文件夹:
2024/08/25/23/uuid.jpg
📂 路径生成规则
文件路径结构
当配置了业务文件夹后，上传的文件路径将按以下规则生成：
{业务文件夹}/{年}/{月}/{日}/{小时}/{UUID}.{扩展名}1
如果不配置业务文件夹，路径格式为：
{年}/{月}/{日}/{小时}/{UUID}.{扩展名}1
路径生成逻辑
- 时间目录：自动按上传时间生成
年/月/日/小时格式的目录 - 文件名：使用 UUID 作为文件名，保留原始文件扩展名
- 业务文件夹：如果配置了
business-folder，则拼接在路径最前面
示例
假设配置了 business-folder: demo-files，上传时间为 2024-08-25 23:30:45，文件名为 example.jpg：
生成的相对路径: demo-files/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.jpg
完整存储路径
不同存储类型的完整路径：
本地存储:
/srv/file/data/demo-files/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.jpg1OSS存储:
demo-files/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.jpg1（存储在OSS Bucket中）
COS存储:
demo-files/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.jpg1（存储在COS Bucket中）
OBS存储:
demo-files/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.jpg1（存储在OBS Bucket中）
S3存储:
demo-files/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.jpg1（存储在S3 Bucket中）
HTTP访问路径
如果配置了 http-access-path: https://www.wueasy.com，文件的访问URL为：
https://www.wueasy.com/demo-files/2024/08/25/23/891dc10b-9b8f-4d1a-bdcd-a298bcc6dc0b.jpg1
🔄 多业务类型配置
配置示例
yaml
files:
# 用户头像业务
- business-type: avatar
file-type: local
root-path: /srv/file/data
business-folder: user-avatars
http-access-path: https://www.wueasy.com
allowed-upload-suffix: jpg,png,gif
max-size: 5MB
# 文档业务
- business-type: document
file-type: oss
business-folder: documents
bucket: file-bucket
endpoint: oss-cn-hangzhou.aliyuncs.com
access-key-id: your-access-key-id
access-key-secret: your-access-key-secret
allowed-upload-suffix: pdf,doc,docx,xls,xlsx
max-size: 50MB
# 图片业务
- business-type: image
file-type: cos
business-folder: images
bucket: image-bucket
endpoint: ap-beijing
access-key-id: your-access-key-id
access-key-secret: your-access-key-secret
allowed-upload-suffix: jpg,png,gif,bmp,webp
max-size: 10MB1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
路径隔离效果
不同业务类型的文件将存储在不同的文件夹中：
- 用户头像:
user-avatars/2024/08/25/23/xxx.jpg - 文档:
documents/2024/08/25/23/xxx.pdf - 图片:
images/2024/08/25/23/xxx.png
💡 使用建议
1. 命名规范
✅ 推荐使用：
- 小写字母和连字符：
user-avatars,product-images,documents - 有意义的名称：
order-attachments,contract-files,temp-uploads - 简洁明了：
images,docs,videos
- 小写字母和连字符：
❌ 不推荐使用：
- 包含空格：
User Avatars,Product Images - 包含特殊字符：
user@avatars,product#images - 使用下划线（虽然支持，但连字符更规范）：
user_avatars - 过长的名称：
very-long-business-folder-name-that-is-hard-to-read
- 包含空格：
2. 业务隔离
- 独立文件夹：为不同业务类型设置独立的文件夹，实现完全隔离
- 权限控制：可以为不同业务文件夹设置不同的访问权限和策略
- 备份恢复：支持按业务类型进行独立的备份和恢复操作
- 统计分析：便于按业务类型统计文件数量和存储空间
3. 存储优化
存储类型选择：
- 高频访问文件：使用CDN加速的对象存储（OSS、COS、OBS）
- 低频访问文件：使用本地存储或S3
- 临时文件：使用本地存储，便于清理
文件大小限制：根据业务特点合理设置
max-size定期清理：建立文件清理机制，定期清理无用文件
存储监控：监控各业务文件夹的存储使用情况
4. 路径管理
- 路径一致性：同一业务类型的所有文件使用相同的业务文件夹
- 避免频繁变更：业务文件夹配置后，建议不要频繁修改
- 迁移考虑：如需修改业务文件夹，需要考虑已有文件的迁移
5. 多环境配置
yaml
# 开发环境
files:
- business-type: demo
business-folder: dev-demo-files
# 生产环境
files:
- business-type: demo
business-folder: prod-demo-files1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
通过不同环境使用不同的业务文件夹，实现环境隔离。
🔧 配置验证
验证步骤
检查配置文件
bash# 验证YAML语法 yamllint config.yaml # 或使用Python验证 python -c "import yaml; yaml.safe_load(open('config.yaml'))"1
2
3
4
5测试文件上传
bash# 上传测试文件 curl -X POST -F "file=@test.jpg" http://localhost:9830/upload/demo # 查看响应，确认文件路径包含业务文件夹 # 响应示例： # { # "code": 0, # "data": { # "filePath": "https://www.wueasy.com/demo-files/2024/08/25/23/uuid.jpg", # "originalPath": "demo-files/2024/08/25/23/uuid.jpg", # ... # } # }1
2
3
4
5
6
7
8
9
10
11
12
13验证文件路径
bash# 本地存储：检查生成的文件路径 ls -la /srv/file/data/demo-files/ # 对象存储：使用对应云服务的控制台或CLI工具查看 # OSS: ossutil ls oss://bucket-name/demo-files/ # COS: coscli ls cos://bucket-name/demo-files/1
2
3
4
5
6验证下载路径
bash# 使用返回的路径测试下载 curl "http://localhost:9830/download/demo/demo-files/2024/08/25/23/uuid.jpg"1
2
📋 使用场景
场景1: 多业务系统
yaml
files:
# 用户系统
- business-type: user
business-folder: user-files
file-type: oss
# ...
# 订单系统
- business-type: order
business-folder: order-files
file-type: cos
# ...
# 内容管理系统
- business-type: cms
business-folder: cms-files
file-type: local
# ...1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
场景2: 文件类型分类
yaml
files:
# 图片业务
- business-type: image
business-folder: images
allowed-upload-suffix: jpg,png,gif,webp
max-size: 10MB
# 文档业务
- business-type: document
business-folder: documents
allowed-upload-suffix: pdf,doc,docx,xls,xlsx
max-size: 50MB
# 视频业务
- business-type: video
business-folder: videos
allowed-upload-suffix: mp4,avi,mov
max-size: 500MB1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
场景3: 环境隔离
yaml
# 开发环境
files:
- business-type: demo
business-folder: dev-files
# ...
# 测试环境
files:
- business-type: demo
business-folder: test-files
# ...
# 生产环境
files:
- business-type: demo
business-folder: prod-files
# ...1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
❓ 常见问题
Q: 不配置业务文件夹会怎样？
A: 文件将直接存储在根目录下，路径格式为 {年}/{月}/{日}/{小时}/{UUID}.{扩展名}
示例：
- 配置业务文件夹：
demo-files/2024/08/25/23/uuid.jpg - 不配置业务文件夹：
2024/08/25/23/uuid.jpg
适用场景：
- 单一业务系统
- 不需要业务隔离的场景
- 临时测试环境
Q: 业务文件夹名称可以包含路径分隔符吗？
A: 建议不要使用路径分隔符（/ 或 \），系统会自动处理路径拼接。
说明：
- 系统会自动去除业务文件夹名称末尾的斜杠
- 如果配置了
business-folder: demo/files/，实际会使用demo/files - 建议使用单层文件夹名称，如
demo-files而不是demo/files
推荐：
yaml
business-folder: demo-files # ✅ 推荐1
不推荐：
yaml
business-folder: demo/files # ❌ 不推荐，虽然支持但不规范1
Q: 如何修改已配置的业务文件夹？
A: 修改配置文件后重启服务，新上传的文件将使用新的文件夹路径。
注意事项：
- 已有文件不受影响：已上传的文件仍使用旧的路径
- 需要迁移：如需统一路径，需要手动迁移已有文件
- 下载兼容：旧路径的文件仍可通过旧路径下载
- 建议方案：
- 方案1：保留旧配置，新增业务类型使用新文件夹
- 方案2：迁移所有文件到新路径（需要额外开发迁移脚本）
示例：
yaml
# 旧配置
business-folder: old-files
# 新配置
business-folder: new-files
# 重启服务后，新上传的文件使用 new-files1
2
3
4
5
6
2
3
4
5
6
Q: 业务文件夹是否支持中文？
A: 支持，但建议使用英文和数字，原因如下：
- 兼容性更好：避免不同系统编码问题
- URL友好：中文路径在URL中需要编码
- 跨平台兼容：某些存储系统对中文支持有限
推荐：
yaml
business-folder: user-avatars # ✅ 推荐1
不推荐：
yaml
business-folder: 用户头像 # ❌ 不推荐1
Q: 分片上传是否也使用业务文件夹？
A: 是的，分片上传和普通上传都使用相同的业务文件夹配置。
说明：
- 分片上传初始化时，会根据业务文件夹生成最终文件路径
- 合并后的文件路径格式与普通上传一致
- 都遵循
{业务文件夹}/{年}/{月}/{日}/{小时}/{UUID}.{扩展名}格式
Q: 如何查看某个业务文件夹下的所有文件？
A: 根据存储类型使用不同的方法：
本地存储：
bash
# 列出所有文件
find /srv/file/data/demo-files -type f
# 统计文件数量
find /srv/file/data/demo-files -type f | wc -l1
2
3
4
5
2
3
4
5
OSS存储：
bash
# 使用ossutil
ossutil ls oss://bucket-name/demo-files/ --recursive
# 使用SDK
# 参考OSS SDK文档1
2
3
4
5
2
3
4
5
COS存储：
bash
# 使用coscli
coscli ls cos://bucket-name/demo-files/ -r
# 使用SDK
# 参考COS SDK文档1
2
3
4
5
2
3
4
5
注意：文件服务本身不提供文件列表接口，需要通过存储系统直接查询。
Q: 业务文件夹配置错误会导致什么问题？
A: 配置错误可能导致以下问题：
- 路径错误：文件存储路径不符合预期
- 访问失败：无法通过预期路径访问文件
- 存储混乱：文件存储位置不清晰
常见错误：
- 配置了不存在的业务文件夹（实际不会报错，会正常创建）
- 使用了特殊字符导致路径问题
- 配置了多层路径（虽然支持，但不推荐）
建议：
- 配置前仔细检查业务文件夹名称
- 使用测试环境验证配置
- 遵循命名规范