fastify-file-manager

描述

用于管理静态文件上传查看等

安装

npm i --save @kne/fastify-file-manager

概述

项目概述

Fastify File Manager 是一个基于 Fastify 框架构建的高性能文件管理服务，提供文件上传、存储、检索和管理功能。该项目采用模块化设计，支持多种存储后端，包括本地文件系统和云存储服务（如阿里云OSS、AWS S3等）。

核心特性

• 🚀 高性能文件处理：基于 Fastify 的轻量级架构
• 🔒 安全认证：集成 JWT 认证和权限控制
• 📁 多存储支持：可配置本地存储或云存储
• 🏷️ 文件分类：通过命名空间(namespace)组织文件
• 📊 元数据管理：记录文件大小、类型、上传时间等信息
• 🔍 文件检索：支持按命名空间查询文件列表

示例

示例代码

API

| 参数 | 类型 | 默认值 | 必填 | 描述 | |-----------------------------|----------|--------------------------------------|----|---------------------------------------------------------------------| | 基础配置 | | | | | | root | string | path.join(process.cwd(), 'static') | 否 | 文件存储根目录路径 | | namespace | string | 'default' | 否 | 默认文件分类命名空间 | | prefix | string | /api/v${majorVersion}/static | 否 | API路由前缀，自动从package.json提取主版本号 | | dbTableNamePrefix | string | 't_file_manager_' | 否 | 数据库表名前缀 | | 文件上传 | | | | | | multipart.limits.fileSize | number | 524288000 (500MB) | 否 | 单个文件最大上传大小 | | 静态文件服务 | | | | | | static | object | {} | 否 | 透传@fastify/static的所有配置 | | 适配器配置 | | | | | | ossAdapter | function | () => {} | 否 | OSS适配器工厂函数，需返回OSS配置对象 | | createAuthenticate | function | () => [] | 否 | 认证中间件工厂函数 |

配置示例

const options = {
    root: '/data/uploads',  // 自定义存储目录
    namespace: 'user_files', // 业务隔离命名空间
    multipart: {
        limits: {
            fileSize: 100 * 1024 * 1024 // 调整为100MB
        }
    },
    ossAdapter: () => {
        /** 需要注册 '@kne/fastify-aliyun' 插件
         * fastify.register(require('@kne/fastify-aliyun'), {
         prefix: `${apiPrefix}/aliyun`,
         oss: {
         baseDir: 'leapin-setting',
         region: fastify.config.OSS_REGION,
         accessKeyId: fastify.config.OSS_ACCESS_KEY_ID,
         accessKeySecret: fastify.config.OSS_ACCESS_KEY_SECRET,
         bucket: fastify.config.OSS_BUCKET
         }
         });
         * */
        return fastify.aliyun.services.oss;
    },
    createAuthenticate: (requiredPermission) => [
        fastify.jwtVerify,
        checkPermission(requiredPermission)
    ]
}

配置说明

1. 版本兼容性
   prefix 自动从 package.json 提取主版本号（如 1.2.3 → /api/v1/static）

2. 存储目录

   • 默认会在项目根目录创建 static 文件夹
   • 生产环境建议设置为绝对路径（如 /var/www/uploads）

3. 权限控制
   createAuthenticate 应返回 Fastify 钩子数组，典型实现：

   createAuthenticate: (perm) => [
     fastify.authenticate,
     (req, reply, done) => {
       if(!req.user.permissions.includes(perm)) {
         return reply.code(403).send()
       }
       done()
     }
   ]

文件上传接口

POST /api/v1/static/upload

上传文件到服务器或配置的存储服务

认证要求

• 需要 file:write 权限
• 通过 JWT 认证

请求参数

| 参数 | 位置 | 类型 | 必填 | 描述 | 示例 | |-----------|-------|--------|----|----------|----------------| | namespace | query | string | 否 | 文件分类命名空间 | user-avatars | | file | body | file | 是 | 要上传的文件 | - |

请求示例

curl -X POST \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -F "[email protected]" \
  "http://localhost:3000/api/v1/static/upload?namespace=user-avatars"

响应状态码

| 状态码 | 描述 | |-----|-----------| | 200 | 文件上传成功 | | 400 | 无效请求或缺少文件 | | 401 | 未授权访问 | | 413 | 文件大小超过限制 | | 500 | 服务器错误 |

文件列表查询

POST /api/v1/static/file-list

查询指定条件下的文件列表（支持分页和筛选）

认证要求

• 需要 file:mange 权限
• 通过 JWT 认证

请求参数

Body 参数 (application/json)

| 参数 | 类型 | 必填 | 描述 | 默认值 | 示例 | |--------------------|----------|----|---------------------|-----|-------------------| | perPage | number | 否 | 每页显示数量 | 20 | 10 | | currentPage | number | 否 | 当前页码 | 1 | 2 | | filter | object | 否 | 筛选条件 | - | - | | filter.namespace | string | 否 | 文件分类命名空间 | - | "user-docs" | | filter.size | number[] | 否 | 文件大小范围[min,max]（字节） | - | [1024, 1048576] | | filter.filename | string | 否 | 文件名模糊匹配 | - | "report.pdf" |

请求示例

curl -X POST \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "perPage": 10,
    "currentPage": 2,
    "filter": {
      "namespace": "project-files",
      "size": [1024, 1048576],
      "filename": "report"
    }
  }' \
  "http://localhost:3000/api/v1/static/file-list"

响应状态码

| 状态码 | 描述 | |-----|---------| | 200 | 查询成功 | | 400 | 参数验证失败 | | 401 | 未授权访问 | | 500 | 服务器内部错误 |

筛选逻辑说明

1. 命名空间筛选：精确匹配传入的 namespace 值
2. 文件大小筛选：
   • 数组第一个元素为最小值
   • 数组第二个元素为最大值
3. 文件名筛选：使用 LIKE %value% 模糊匹配

分页说明

• 分页计算：offset = (currentPage - 1) * perPage
• 建议每页数量不超过 100 条
• 页码从 1 开始计数

文件删除接口

DELETE /api/v1/static/:fileId

删除指定文件

认证要求

• 需要 file:write 权限

请求参数

| 参数 | 位置 | 类型 | 必填 | 描述 | 示例 | |--------|------|--------|----|----------|----------| | fileId | path | string | 是 | 要删除的文件ID | abc123 |

请求示例

curl -X DELETE \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  "http://localhost:3000/api/v1/static/abc123"

响应状态码

| 状态码 | 描述 | |-----|--------| | 204 | 文件删除成功 | | 404 | 文件不存在 | | 500 | 服务器错误 |

文件信息接口

GET /api/v1/static/:fileId

获取文件详细信息

认证要求

• 需要 file:read 权限

请求参数

| 参数 | 位置 | 类型 | 必填 | 描述 | 示例 | |--------|------|--------|----|----------|----------| | fileId | path | string | 是 | 要查询的文件ID | abc123 |

请求示例

curl -X GET \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  "http://localhost:3000/api/v1/static/abc123"

响应示例

{
  "id": "abc123",
  "name": "document.pdf",
  "size": 102400,
  "mimeType": "application/pdf",
  "createdAt": "2023-01-01T00:00:00Z",
  "url": "/api/v1/static/file/documents/abc123.pdf"
}

接口使用说明

1. 认证方式：

   • 所有接口都需要在 Header 中添加 Authorization: Bearer <JWT_TOKEN>
   • JWT 需要包含相应的权限声明

2. 命名空间规则：

   • 命名空间支持字母、数字和下划线组合
   • 未指定时使用默认命名空间

3. 文件大小限制：

   • 默认最大 500MB
   • 可在服务端配置中调整

4. 错误处理：

   • 所有错误响应都包含标准格式的 error 字段
   • 客户端应检查状态码而非仅依赖响应体

注意：实际 API 路径前缀会根据配置的 prefix 参数变化