# fileuploaddownload

**Repository Path**: Mr_laogui/fileuploaddownload

## Basic Information

- **Project Name**: fileuploaddownload
- **Description**: 一个简单的文件上传下载查询删除项目
支持批量上传并发处理
nodejs实现
- **Primary Language**: JavaScript
- **License**: AFL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-12-28
- **Last Updated**: 2025-12-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文件上传下载API

基于Node.js和Express的自适应文件上传下载服务，支持多种上传方式和格式。

## 开源许可

本项目采用 [AFL-3.0 许可证](LICENSE) 开源。

### 版权声明

© 2025 laogui <1156346325@QQ.com>

### 使用条件

- ✅ 商业使用
- ✅ 修改
- ✅ 分发
- ✅ 私人使用
- ✅ 专利授权

### 限制

- ⚠️ 需要包含版权声明和许可证信息
- ⚠️ 作者不承担任何责任
- ⚠️ 不提供任何担保

### 贡献指南

欢迎提交Issue和Pull Request来帮助改进项目。

### 代码引用

如果您在项目中使用了本代码，请在代码或文档中添加以下引用：

```
文件上传下载API - 自适应多格式文件处理服务
Copyright (c) 2025 laogui <1156346325@QQ.com>
https://gitee.com/Mr_laogui/fileuploaddownload
```

## 安装依赖

```bash
npm install
```

## 启动服务

```bash
# 生产环境
npm start

# 开发环境（自动重启）
npm run dev
```

## 宝塔面板部署指南

### 1. 准备工作

1. 登录宝塔面板
2. 在"软件商店"中安装以下应用：
   - Node.js环境管理器（安装Node.js 16+版本）
   - PM2管理器（推荐用于进程管理）
   - Nginx Web服务器（如已安装可跳过）

### 2. 上传项目文件

1. 打开宝塔"文件"管理器
2. 进入网站根目录（通常为`/www/wwwroot/`）
3. 点击"上传"按钮，选择本地项目文件夹并上传
4. 上传完成后解压（如上传的是压缩包）

### 3. 安装依赖

1. 进入文件管理器，找到项目文件夹
2. 右键点击项目文件夹，选择"终端"
3. 在打开的终端窗口中输入：
```
npm install --production
```
4. 等待安装完成（如失败，请检查Node.js版本是否兼容）

### 4. 使用PM2图形界面启动项目

1. 在宝塔面板中点击"软件商店"，找到已安装的PM2
2. 点击"设置"进入PM2管理界面
3. 点击"添加项目"按钮
4. 填写以下信息：
   - 项目名称：file-uploader（可自定义）
   - 启动文件：选择项目文件夹中的`server.js`
   - 项目目录：选择项目文件夹
   - 启动方式：选择`node server.js`
   - 端口：3000（或根据需要修改）
5. 点击"提交"保存设置
6. 在项目列表中点击"启动"按钮启动项目

### 5. 配置网站访问

1. 在宝塔面板中点击"网站"
2. 点击"添加站点"，填写域名信息
3. 创建站点后，进入站点设置
4. 点击"反向代理"选项卡
5. 添加新的反向代理：
   - 代理名称：file-uploader
   - 目标URL：`http://127.0.0.1:3000`
   - 发送域名：`$host`
   - 点击"保存"
6. 等待Nginx重载配置

### 6. 安全设置

1. 在站点设置中，点击"SSL"
2. 如需要HTTPS，可申请免费Let's Encrypt证书
3. 在"安全"页面配置防火墙规则
4. 在文件管理器中设置uploads目录权限为755：
   - 右键点击uploads文件夹
   - 选择"权限"
   - 设置为755并保存

### 7. 监控与日志

1. 在PM2管理器中查看项目状态
2. 点击项目名称可查看实时日志
3. 在"网站"设置中可查看访问日志和错误日志
4. 设置定时任务定期备份uploads目录

### 8. 常见问题解决

1. **项目无法启动**：
   - 检查PM2中的错误日志
   - 确认Node.js版本是否正确
   - 检查端口是否被占用

2. **上传失败**：
   - 在网站设置中检查"修改限制"选项
   - 调整"上传文件大小限制"为所需大小
   - 检查uploads目录权限

3. **无法访问**：
   - 检查反向代理配置是否正确
   - 确认防火墙是否放行80/443端口
   - 重启Nginx服务

### 9. 性能优化

1. 在网站设置中开启"缓存"
2. 配置"静态文件加速"
3. 设置"定时任务"定期清理旧文件
4. 在PM2中设置项目重启策略（如内存占用过高时自动重启）

## 接口请求参数与响应

### 1. 自适应文件上传

**请求方法**: POST

**请求参数**:
- 文件上传 (multipart/form-data):
  - 多文件上传: 使用不同字段名 (file1, file2, file3...)
  - 文件夹参数: 查询参数 `?folder=相对路径` 或 表单字段 `folder=相对路径`
- JSON列表 (application/json):
  ```json
  {"file1":"name1","file2":"name2","folder":"可选文件夹路径"}
  ```
  或
  ```json
  ["file1","file2","file3"]
  ```
  配合查询参数 `?folder=相对路径` 使用
- 表单提交 (application/x-www-form-urlencoded):
  - file1=name1&file2=name2&folder=文件夹路径 格式

**文件夹参数说明**:
- 路径是相对于 uploads 目录的相对路径
- 支持多级目录，如 `images/photos`、`documents/2024/12`
- 如果指定的文件夹不存在，系统会自动创建
- 不指定则使用默认 uploads 目录

**响应**:
```json
{
  "message": "成功上传 3 个文件 (总大小: 2.5 MB)",
  "files": [
    {
      "originalname": "原始文件名.jpg",
      "filename": "唯一文件名-时间戳.jpg",
      "size": 文件大小,
      "sizeText": "2.5 MB",
      "mimetype": "文件MIME类型",
      "fieldname": "file1"
    }
  ],
  "uploadType": "multiple-any",
  "folder": "指定的文件夹路径或默认uploads目录",
  "totalSize": 总文件大小
}
```

### 2. 文件下载

**请求方法**: GET

**请求参数**:
- URL路径: `/download/:filename`
- 参数: 
  - filename (上传时返回的唯一文件名)
  - 可选查询参数 `?folder=相对路径` (指定文件所在的文件夹)

**响应**: 文件流下载

**示例**:
```
GET /download/image-1640995200000-123456789.jpg?folder=images/photos
```

### 3. 获取文件列表

**请求方法**: GET

**请求参数**:
- 基础请求: `/files` (不指定参数，遍历所有文件夹)
- 文件夹过滤: `/files?folder=相对路径` (只列出指定文件夹下的文件)

**参数说明**:
- 不指定 folder 参数：递归遍历 uploads 目录及其所有子文件夹中的文件
- 指定 folder 参数：仅列出指定文件夹中的文件，不包括子文件夹

**响应**:
```json
{
  "message": "共 5 个文件",
  "totalSize": "15.2 MB",
  "files": [
    {
      "filename": "文件名-时间戳.jpg",
      "folder": "文件所在文件夹路径",
      "size": 文件大小,
      "sizeText": "3.1 MB",
      "createdAt": "创建时间",
      "modifiedAt": "修改时间"
    }
  ]
}
```

**示例**:
```
GET /files                    # 获取所有文件夹中的文件
GET /files?folder=images      # 只获取 images 文件夹中的文件
GET /files?folder=docs/2024   # 只获取 docs/2024 文件夹中的文件
```

### 4. 删除文件

**请求方法**: DELETE

**请求参数**:
- URL路径: `/files/:filename`
- 参数: 
  - filename (文件名)
  - 可选查询参数 `?folder=相对路径` (指定文件所在的文件夹)

**响应**:
```json
{
  "message": "文件删除成功",
  "deletedFile": {
    "filename": "被删除的文件名",
    "folder": "文件所在的文件夹路径"
  }
}
```

**示例**:
```
DELETE /files/document-1640995200000-123456789.pdf?folder=documents
```

## 文件夹功能示例

### 上传文件到指定文件夹

```bash
# 使用查询参数指定文件夹
curl -X POST http://localhost:3000/upload?folder=images/photos \
  -F "file1=@photo1.jpg" \
  -F "file2=@photo2.jpg"

# 使用表单字段指定文件夹
curl -X POST http://localhost:3000/upload \
  -F "folder=documents/2024" \
  -F "file1=@report.pdf"
```

### 查看不同文件夹中的文件

```bash
# 查看所有文件夹中的文件
curl http://localhost:3000/files

# 只查看 images 文件夹中的文件
curl http://localhost:3000/files?folder=images

# 只查看 documents/2024 文件夹中的文件
curl http://localhost:3000/files?folder=documents/2024
```

### 下载和删除特定文件夹中的文件

```bash
# 下载 images 文件夹中的文件
curl -O http://localhost:3000/download/photo1-1640995200000-123456789.jpg?folder=images/photos

# 删除 documents/2024 文件夹中的文件
curl -X DELETE http://localhost:3000/files/report-1640995200000-123456789.pdf?folder=documents/2024
```

## 注意事项

1. 上传文件大小限制为100MB
2. 上传的文件保存在`uploads`目录下，支持多级文件夹组织
3. 文件夹参数是相对于 uploads 目录的相对路径，如 `images`、`documents/2024/12`
4. 指定的文件夹不存在时，系统会自动创建
5. 文件名会自动添加时间戳以避免冲突
6. 支持所有文件类型上传
7. 服务器使用标准HTTP状态码表示请求结果（200成功，400客户端错误，500服务器错误等）
8. 所有响应采用统一的错误格式，包含`error`字段描述错误原因
9. 文件夹路径会自动清理，移除开头的斜杠，确保路径正确拼接