# personal-Pan

**Repository Path**: varyu-program/personal-pan

## Basic Information

- **Project Name**: personal-Pan
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Personal-Pan 网盘系统

基于 **Spring Cloud + MinIO** 的网盘系统，支持文件上传/下载、文件管理、远程管理。

## 架构

```
                ┌─────────────┐
   客户端 ──────▶│   Gateway   │ :8080  统一入口 / JWT 鉴权 / 用户透传
                └──────┬──────┘
          ┌────────────┼────────────┐
          ▼            ▼            ▼
   ┌────────────┐ ┌──────────┐ ┌──────────────┐
   │user-service│ │file-svc  │ │  (可扩展)    │
   │  :8201     │ │ :8202    │ │              │
   └────────────┘ └────┬─────┘ └──────────────┘
                       │ SDK
                  ┌────▼─────┐
                  │  MinIO   │ :9000 (console :9301)
                  └──────────┘
```

| 模块 | 端口 | 职责 |
|------|------|------|
| gateway | 8080 | 路由、鉴权、CORS |
| user-service | 8201 | 用户、登录、JWT 签发 |
| file-service | 8202 | 文件上传/下载/管理（MinIO） |
| common | - | 统一返回、异常、用户上下文 |

## 环境要求
- JDK 17
- Maven 3.8+
- MySQL 8（库名 `pan`）
- 本地 MinIO `RELEASE.2025-09-07T16-13-09Z`（已就绪：endpoint `:9000`，console `:9301`，bucket `pan-files` 自动创建）

## 运行步骤
1. 执行 `sql/init.sql` 建库建表。
2. 启动 MinIO：`minio-pan/minio/minio.bat`（已配置账号 `gavin/gavinzyy`）。
3. 依次启动：`user-service` → `file-service` → `gateway`。
   ```bash
   mvn -q -pl user-service -am spring-boot:run
   mvn -q -pl file-service -am spring-boot:run
   mvn -q -pl gateway -am spring-boot:run
   ```

## 接口示例（统一前缀 /api）

### 登录
```bash
curl -X POST http://localhost:8080/api/user/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"123456"}'
# 返回 { "data": { "token": "eyJ..." } }
```

### 上传文件
```bash
curl -X POST http://localhost:8080/api/files/upload?parentId=0 \
  -H 'Authorization: Bearer <token>' \
  -F 'file=@/path/to/demo.txt'
```

### 文件列表
```bash
curl 'http://localhost:8080/api/files/list?parentId=0' \
  -H 'Authorization: Bearer <token>'
```

### 新建文件夹
```bash
curl -X POST 'http://localhost:8080/api/files/mkdir?parentId=0&name=docs' \
  -H 'Authorization: Bearer <token>'
```

### 重命名 / 移动 / 删除
```bash
curl -X POST 'http://localhost:8080/api/files/rename?fileId=xxx&newName=new.txt' \
  -H 'Authorization: Bearer <token>'
curl -X POST 'http://localhost:8080/api/files/move?fileId=xxx&targetParentId=yyy' \
  -H 'Authorization: Bearer <token>'
curl -X POST 'http://localhost:8080/api/files/delete?fileId=xxx' \
  -H 'Authorization: Bearer <token>'
```

### 下载
```bash
# 方式一：直接流式下载（走网关）
curl -O -J 'http://localhost:8080/api/files/download?fileId=xxx' \
  -H 'Authorization: Bearer <token>'

# 方式二：获取 MinIO 预签名直链（适合大文件，前端直连）
curl 'http://localhost:8080/api/files/download-url?fileId=xxx' \
  -H 'Authorization: Bearer <token>'
```

### 目录树 / 远程检索
```bash
curl http://localhost:8080/api/files/tree -H 'Authorization: Bearer <token>'
curl 'http://localhost:8080/api/files/page?keyword=report&current=1&size=10' \
  -H 'Authorization: Bearer <token>'
```

## 远程管理
- 所有接口通过网关 `:8080` 统一暴露，支持跨网络访问（远程管理）。
- 提供预签名直链（`download-url`），前端可直接从 MinIO 拉取大文件，降低网关带宽压力。
- 文件元数据存于 MySQL，对象存于 MinIO，天然支持水平扩展与多节点部署。

## 已实现特性
- 多用户隔离（按 `userId` 隔离文件空间）
- 文件夹树、重命名、移动、递归删除
- 普通上传（MD5 秒传）、流式下载、预签名直链下载
- 网关统一鉴权（JWT）+ 用户上下文透传
- 分页检索，便于远程文件管理
- **分片上传 + 断点续传**（前端 5MB 分片、并发 3、失败/续传自动跳过已传分片）
- **文件分享链接**（带有效期、可选提取码、访问计数，支持匿名访问下载）

## 前端页面
`frontend/index.html` 是一个零构建的单页网盘（原生 HTML/JS）：
- 登录 / 退出
- 文件夹导航（面包屑）、列表、新建文件夹、重命名、移动、删除
- 上传：小文件普通上传，大于 50MB 自动走分片上传（进度条、断点续传）
- 分享：生成链接与提取码，查看我的分享
- 使用方式：直接用浏览器打开 `frontend/index.html`，API 默认指向 `http://localhost:8080/api`（如需修改见脚本顶部 `const API`）。

## 新增接口

### 分片上传（断点续传）
```
POST /api/files/chunk/init           ?parentId=&fileName=&contentType=&fileSize=&chunkCount=
     -> { uploadId, chunkCount }
POST /api/files/chunk/uploadPart     ?uploadId=&partNumber=   (multipart file)
     -> { partNumber, received }
GET  /api/files/chunk/uploaded       ?uploadId=               (已上传分片编号，用于断点续传)
POST /api/files/chunk/complete       ?uploadId=&fileName=     -> { fileId, name }
POST /api/files/chunk/abort          ?uploadId=
```
实现说明：每个分片以临时对象 `temp/{uploadId}/{part}` 存入 MinIO，`complete` 时按序合并并清理临时分片。该方案不依赖 MinIO 特定多版本分片 API，跨版本稳定。

### 文件分享
```
POST /api/files/share/create                       ?fileId=&code=&expireHours=  -> { shareId, code, expireAt, link }
GET  /api/share/detail/{shareId}                   (匿名) -> 分享信息
POST /api/share/access/{shareId}                   ?code=  (匿名) -> { url, name }  预签名下载直链
GET  /api/files/share/my                           -> 我的分享列表
```
> 注意：`/api/share/**` 匿名可访问，`/api/files/**` 仍需登录（网关 AuthFilter 鉴权）。

## 可扩展方向
- 缩略图 / 文档预览
- 注册与权限体系（RBAC）
- 分享链接的访问密码增强、批量分享
- 分片上传会话持久化到 Redis（当前为内存，重启丢失）