上传文件过多，本地存储目录拆分全方案-马育民老师

# 介绍

业务系统随着用户量增长，附件、图片、文档、报表上传量暴增。
很多项目初期图省事，把 **所有上传文件全部扔在同一个 upload 文件夹**。

随之带来一堆致命问题：

- 单目录文件过万，Windows/Linux 资源管理器打开卡死
- 文件遍历、删除、归档极慢，IO 负载飙升
- 备份、迁移、清理历史数据无从下手
- 后续想迁对象存储、NAS 完全没有规整路径

很多人只知道**按年月日、按哈希**两种方式，其实工业级常用一共有 **6 种本地目录拆分架构**，每种适配不同业务场景。本文一次性讲透原理、结构、优缺点、适用场景，可直接落地项目。

# 为什么不能把文件全放一个文件夹？

1. **文件系统限制**
Windows NTFS、Linux Ext4 单目录文件数量过高后，索引寻址急剧变慢。

2. **运维灾难**
无法按维度归档、无法批量清理、备份耗时爆炸。

3. **性能拖累业务**
接口查询文件、预览、下载时，文件查找耗时变长，接口响应变慢。

4. **后续扩容困难**
无分层结构，后期迁移 MinIO/OSS/NAS 要重构所有路径。

# 两个场景

### 文件管理器（点开文件夹）

以windows为例：**超过 1000 个**，打开就转圈、缩略图卡死、滚动卡顿
这是Windows 图形界面 BUG，不是程序 IO 卡

### 程序后端读写（Java/Python/Go/NGINX）

不走资源管理器，是系统内核级调用：

- 单目录 1 万以内：完全不卡，遍历、查找、删除、上传都正常
- 1 万～3 万：轻微变慢，日常业务感知不到
- 3 万～5 万：listdir、遍历、查找文件、备份明显变慢
- 5 万以上：接口响应变长、CPU/IO 升高、备份超时、清理任务卡死
- 10 万以上：必卡，属于生产事故级目录滥用

# 各个系统的最大文件数量

### Windows（NTFS）

- 理论：约 **42亿**（2³²−1）  
- 安全推荐：**≤ 10,000**  
- 性能警戒线：**> 50,000 明显变慢**，Explorer 打开卡顿

### macOS（APFS）

- 理论：64位，**近乎无上限**  
- 安全推荐：**≤ 10,000**  
- 性能警戒线：**> 100,000 开始明显降速**

### Linux（ext4）

- 理论上限：**约 3.2万～6.4万**（哈希桶限制）  
- 安全推荐：**≤ 5,000～10,000**  
- 警戒线：**接近 3万 就开始报错/性能骤降**

### Linux（XFS/Btrfs）

- 理论：**无硬上限，受 inode 数量限制**  
- 安全推荐：**≤ 10,000**  
- 警戒线：**> 100,000 后 ls/stat 变慢**

---

### 对比

| 系统 | 文件系统 | 理论上限 | 生产安全值（推荐） | 性能警戒线（别超） |
|---|---|---|---|---|
| Windows | NTFS | ~42亿 | ≤ 10,000 | 50,000 |
| macOS | APFS | 无实际上限 | ≤ 10,000 | 100,000 |
| Linux | ext4 | 3.2万～6.4万 | ≤ 5,000～10,000 | 30,000 |
| Linux | XFS/Btrfs | 受inode限制 | ≤ 10,000 | 100,000 |

---

### 一句话建议

**所有系统通用铁律**：单目录 **不要超过 1 万个文件**；超过就必须做**时间/哈希/ID分目录**拆分。

# 本地文件目录拆分

有 6 种方案：

- 时间层级拆分
- 业务/用户ID 取模拆分
- 文件类型后缀分类拆分
- 哈希两级分片拆分
- 自增ID区间分桶拆分
- 多物理盘符拆分

# 方案1：时间层级拆分

### 目录结构
```
uploads
├─2026
│  ├─05
│  │  ├─09
│  │  │  ├─xxx.jpg
│  │  │  └─xxx.pdf
```
### 规则
按上传时间自动生成 `年/月/日` 三级目录，也可加时分秒缩分。

### 优点
- 逻辑最简单，开发零难度
- **按时间归档、删除、清理过期文件极其方便**
- 天然流量打散，目录分布均匀

### 缺点
- 业务高峰期某天文件会扎堆，当日目录仍可能爆满
- 无法按用户、业务维度隔离

### 适用场景
绝大多数后台管理系统、普通网站、公文附件、日常业务上传。

---

# 方案2：业务/用户ID 取模拆分
### 目录结构
用户 ID 对固定值取模（如模100、模256）
```
uploads
├─03
│  ├─user_10003
├─27
│  ├─user_10027
```

### 规则
`目录 = 用户ID % 100`，再下挂用户独立文件夹。

### 优点
- **完美防止单用户文件泛滥挤爆一个目录**
- 用户文件完全隔离，迁移、删除单个用户数据极方便
- 分布式均匀分布，不会集中扎堆

### 缺点
- 路径可读性差，运维肉眼看不出时间
- 比时间结构多一层开发逻辑

### 适用场景
多用户SaaS系统、会员上传、个人文档网盘类业务。

---

# 方案3：文件类型后缀分类拆分
### 目录结构
```
uploads
├─image
├─pdf
├─video
├─excel
├─word
└─other
```

### 规则
按文件 MIME 类型/后缀，归类到对应目录。

### 优点
- 按文件类型隔离，运维管理极度清晰
- 可以单独对视频、图片做不同磁盘存储策略
- 可单独限制某类文件容量、单独清理

### 缺点
- 单类型下仍会堆积大量文件，需再配合时间/哈希二次分层

### 适用场景
素材管理、媒体库、文档系统、多类型混合上传业务。

---

# 方案4：哈希两级分片拆分（推荐）

海量小文件终极方案

### 目录结构
取文件 MD5 哈希前两位、中间两位做两级目录
```
uploads
├─a8
│  ├─3f
│  │  └─a83fxxxxxx.pdf
```

### 规则
文件 MD5 值拆分固定两级目录，文件名用完整哈希。

### 最多文件数量

##### 先算目录总数

16进制字符：0-9、a-f → 共 **16 个**

- 第一层目录：`16×16 = 256` 个
- 两层总目录数：`16×16×16×16 = 65536` 个 子文件夹

##### 1. 按单目录放 5000 个算

```
65536 * 5000 = 327,680,000个
```
约 **3.27 亿 文件**

##### 2. 按单目录放 10000 个算

```
65536 * 10000 = 655,360,000个
```

约 **6.55 亿 文件**

### 优点
- **亿级文件也能平稳支撑，单目录数量永远可控**
- 天然文件去重，相同哈希只存一份
- 分布最均衡，无扎堆风险

### 缺点
- 完全无可读性，看不出时间、用户、业务
- 依赖 MD5 计算，略有微小性能消耗

### 适用场景
海量小文件、网盘、资源库、系统内部文件、长期持续暴涨的业务。

---

# 方案5：自增ID区间分桶拆分
### 目录结构
按文件自增ID区间分桶
```
uploads
├─0_100000
├─100000_200000
├─200000_300000
```

### 规则
按数据库文件主键 ID，每10万/5万分一个桶。

### 优点
- 归档、迁移、按批次清理极其简单
- 顺序存储，备份逻辑清晰

### 缺点
- 后期ID持续增大，需要人工新增桶目录
- 无时间、用户维度属性

### 适用场景
内部业务系统、工单附件、流程审批、自增主键文件管理。

---

# 方案6：多物理盘符拆分

容量不足兜底方案

### 结构逻辑
不做逻辑目录分层，从物理磁盘层面拆分：
- 热文件、近期文件 → D盘
- 历史归档文件 → E盘、F盘、挂载NAS盘
程序内部做**路径配置映射**，上层统一接口，底层多盘分散。

### 优点
- 直接解决单磁盘容量不足问题
- 不用改动现有目录规则

### 缺点
- 只是扩容，没解决单目录文件过多的性能问题
- 运维要管理多块磁盘

### 适用场景
存量文件已非常多、单盘爆满、临时紧急扩容不想改代码。

# 三、6种方案横向对比表

| 拆分方案 | 易开发 | 可读性 | 均衡防扎堆 | 适合海量文件 | 归档清理便利性 | 推荐指数 |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| 时间年月日 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 用户ID取模 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 按文件类型 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 哈希两级分片 | ⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| ID区间分桶 | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 多盘符物理拆分 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |

# 四、生产环境最佳组合方案

实际项目不要只用一种，**组合使用最稳**：

1. **时间 + 文件类型**
`uploads/年/月/日/文件类型/xxx.jpg`
适合绝大多数业务，好维护、好归档。

2. **用户ID取模 + 时间**
`uploads/模值/用户ID/年/月/日/xxx.png`
SaaS多用户系统最优解。

3. **哈希 + 多盘符**
海量文件，冷热分离，热盘放近期，冷盘归档历史。

# 五、总结

1. 永远不要把所有上传文件丢在同一个目录。
2. 中小型业务优先 **时间分层**，简单好维护。
3. 多用户SaaS必用 **用户ID取模**。
4. 海量小文件长期增长直接上 **哈希两级目录**。
5. 磁盘不够先做**逻辑分层**，再做多盘符/NAS扩容，不要只靠加盘硬扛。
6. 所有本地目录结构，要预留**未来迁移MinIO/OSS对象存储**的兼容设计。

原文出处：https://malaoshi.top/show_1GW3HUVmKvqT.html