HDFS 个人分布式网盘

基于 Hadoop HDFS 2.7.4 的分布式个人网盘，后端使用 Spring Boot，前端使用 Vue 3 + Element Plus。

用户注册后会自动分配独立的 HDFS 存储目录，支持文件上传、下载、文件夹管理、重命名与删除。

功能特性

• 用户注册 / 登录，JWT 无状态鉴权，BCrypt 密码加密
• 用户存储空间隔离，每个用户对应独立的 HDFS 目录
• 文件列表、目录切换、面包屑导航
• 拖拽多文件上传（流式写入 HDFS，带进度条）
• 文件下载（流式读取，支持中文文件名）
• 新建文件夹、重命名、递归删除
• 路径穿越（..）拦截，未登录请求统一返回 401
• 响应式界面，适配桌面与移动端

技术栈

层	技术
后端	Java 8、Spring Boot 2.7.18、Spring Data JPA、H2、JJWT 0.11.5
HDFS 客户端	Hadoop 2.7.4（hadoop-common、hadoop-hdfs）
前端	Vue 3、Vite 5、Vue Router 4、Element Plus、Axios
存储	HDFS（NameNode RPC hdfs://hadoop01:9000）
用户数据	H2 文件数据库（backend/data/netdisk.mv.db）

项目结构

Netdisk/
├── backend/                          # Spring Boot 后端
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/netdisk/
│       │   ├── NetdiskApplication.java
│       │   ├── common/               # 统一响应、异常处理
│       │   ├── config/               # HDFS / JWT 配置、CORS、拦截器注册
│       │   ├── controller/           # AuthController、FileController
│       │   ├── dto/                  # 请求与响应对象
│       │   ├── entity/               # 用户实体
│       │   ├── repository/           # JPA 仓库
│       │   ├── security/             # JWT、登录拦截器、用户上下文
│       │   └── service/              # AuthService、HdfsService
│       └── resources/application.yml
├── frontend/                         # Vue 3 前端
│   ├── package.json
│   ├── vite.config.js                # 开发代理 /api -> localhost:8080
│   └── src/
│       ├── api/                      # 请求封装与接口
│       ├── router/
│       ├── utils/format.js           # 文件大小、时间、图标
│       └── views/                    # Login、Register、Drive
└── .gitignore

环境要求

• JDK 8（Hadoop 2.7.4 客户端建议使用 Java 8；更高版本可能因模块访问限制出现问题）
• Maven 3.6+
• Node.js 18+、npm 9+
• Hadoop 2.7.4 集群，NameNode RPC 端口可访问（默认 9000）

配置

后端配置文件：backend/src/main/resources/application.yml

netdisk:
  hdfs:
    uri: hdfs://hadoop01:9000   # NameNode RPC 地址，不是 50070
    user: root                  # 访问 HDFS 的身份，需要具备写权限
    base-path: /netdisk         # 所有用户数据根目录
    use-datanode-hostname: false
  jwt:
    secret: netdisk-hdfs-jwt-secret-key-please-change-in-production-2026
    expire-hours: 72

说明：

• 50070 是 NameNode Web UI 端口，不能作为 Java 客户端连接地址；客户端使用 9000（或实际 RPC 端口）。
• /netdisk 目录属主为 root、权限 755，因此默认使用 root 身份访问；如需换用户，请确保该用户在 HDFS 上有写权限。
• 若 DataNode 返回主机名且客户端无法解析，可将 use-datanode-hostname 改为 true。
• 生产环境请务必修改 JWT 密钥。

启动

1. 启动后端

cd backend
mvn spring-boot:run

或先打包再运行：

mvn clean package -DskipTests
java -jar target/hdfs-netdisk-1.0.0.jar

后端默认监听 http://localhost:8080。

注意：mvn -version 显示的 Java 版本需为 1.8。若系统默认 java 为 11+，可通过 JAVA_HOME 切换到 JDK 8。

2. 启动前端

cd frontend
npm install
npm run dev

访问 http://localhost:5173，注册账号后即可使用。开发服务器已将 /api 代理到 http://localhost:8080。

3. 生产构建

cd frontend
npm run build

产物位于 frontend/dist，可交由 Nginx 等静态服务器托管，并将 /api 反向代理到后端 8080 端口。

HDFS 存储设计

• 用户根目录：/netdisk/u_{userId}，首次访问时自动创建
• 文件按 HDFS 块大小切分（默认 128 MB），副本数默认为 3
• 例如 836 MB 的文件会被切成 7 个块（6 × 128 MB + 1 × 71 MB），每块在 3 台 DataNode 上各存一份

查看文件副本情况：

hdfs fsck /netdisk/u_2/example.zip -files -blocks -locations

查看 HDFS 根目录：

hdfs dfs -ls /netdisk

接口说明

所有接口以 /api 开头，除登录、注册外均需请求头：

Authorization: Bearer <token>

响应格式：

{ "code": 0, "message": "ok", "data": {} }

方法	路径	说明
POST	/api/auth/register	注册，body：{ "username": "...", "password": "..." }
POST	/api/auth/login	登录，返回 token、userId、username
GET	/api/auth/me	获取当前用户信息
GET	/api/files?path=/	列出目录内容
POST	/api/files/upload?path=/	上传文件，multipart 字段名 file
GET	/api/files/download?path=/a.txt	下载文件
POST	/api/files/mkdir	新建文件夹，body：{ "path": "/", "name": "docs" }
POST	/api/files/rename	重命名，body：{ "path": "/a.txt", "newName": "b.txt" }
DELETE	/api/files?path=/a.txt	删除文件或目录（递归）

常见问题

Q：后端启动报无法连接 HDFS？

检查 NameNode RPC 地址、端口连通性以及 netdisk.hdfs.user 是否有写权限；确认 hdfs://hadoop01:9000 可从运行后端的机器访问。

Q：上传成功但副本数不足，下载仍可用吗？

只要至少有一个 DataNode 持有该块即可下载。NameNode 会持续调度复制，待其他 DataNode 恢复后自动补齐副本。使用 hdfs fsck 可查看副本分布。

Q：中文文件名乱码？

后端下载响应使用 RFC 5987 编码文件名，前端从 Content-Disposition 解析；确保数据库与 HDFS 均使用 UTF-8。

Q：数据库文件在哪里？

backend/data/netdisk.mv.db。该目录已在 .gitignore 中排除，删除后用户数据会重置。

注意事项

• 本项目定位为教学 / 演示用途，用户信息存储于 H2 文件数据库，未接入外部数据库与对象存储。
• JWT 密钥与 HDFS 访问身份均为明文配置，生产部署前请调整。
• 文件上传大小上限为 2 GB，可在 application.yml 的 spring.servlet.multipart 中修改。
• HDFS 的 NameNode 是单点，若部署 NameNode 的机器宕机，整个网盘将不可用；生产环境建议配置 HDFS HA。