diff --git a/README.md b/README.md index 1a81db2..6c30a10 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,6 @@ [MinIO-Plus](https://gitee.com/lxp135/minio-plus/) 是一个 [MinIO](https://github.com/minio/minio) 的二次封装与增强工具，在 MinIO 的基础上只做增强，不侵入 MinIO 代码，只为简化开发、提高效率而生。成为 MinIO 在项目中落地的润滑剂。 -/TODO 演示地址 - # 1 特性 | Feature * **无侵入** ：只做增强不做改变，引入它不会对现有工程产生影响，如丝般顺滑。 @@ -107,7 +105,7 @@ MinIO 的基础上只做增强，不侵入 MinIO 代码，只为简化开发、 * 增加传输的可靠性：可以避免由于网络波动或其他原因导致整个文件需要重新传输的情况。再也不怕意外断网。在大文件传输时，尤其有用。 * 随时暂停和恢复：用户可以在传输过程中暂停传输或者中断传输，断点续传可以方便地恢复传输任务。 -## 2.3 前端直连 +## 2.3 客户端直连 当用户进行文件流的上传和下载时，直接访问MinIO服务器（可配置Nginx代理）。 @@ -153,163 +151,53 @@ PS：原图尺寸小于缩略图压缩尺寸时，储存原图。 其他规则：文件在桶中存储时，按照 /年/月 划分路径。用以规避Linux ext3文件系统下单个目录最多创建32000个目录的问题，参考了阿里云OSS的处理办法。 -# 3 接口设计 | Interface Design +# 3 项目文档 | Document -## 3.1 Service 层接口 +* [首页](https://minioplus.liuxp.me/guide/intro) +* [更新日志](https://minioplus.liuxp.me/guide/released.md) +* 用户手册 + - [快速开始](https://minioplus.liuxp.me/guide/user/quick-start) + - [API接口](https://minioplus.liuxp.me/guide/user/api) + - [文件元数据](https://minioplus.liuxp.me/guide/user/db) + - [配置文件](https://minioplus.liuxp.me/guide/user/config) + - [非官方S3实现](https://minioplus.liuxp.me/guide/user/custom) +* 开发者手册 + - [开发计划](https://minioplus.liuxp.me/guide/developers/plan) + - [构建与运行](https://minioplus.liuxp.me/guide/developers/building) + - [代码结构](https://minioplus.liuxp.me/guide/developers/framework) + - [提交代码](https://minioplus.liuxp.me/guide/developers/writing-code) + - [编写文档](https://minioplus.liuxp.me/guide/developers/writing-documents) + - [贡献者列表](https://minioplus.liuxp.me/guide/developers/contributors) +* 核心机制 + - [上传](https://minioplus.liuxp.me/guide/core/upload) + - [下载](https://minioplus.liuxp.me/guide/core/download) + - [客户端直连](https://minioplus.liuxp.me/guide/core/direct) + - [缩略图](https://minioplus.liuxp.me/guide/core/preview) + - [桶策略](https://minioplus.liuxp.me/guide/core/bucket) + - [权限控制](https://minioplus.liuxp.me/guide/core/auth) +* 参考资料 + - [FAQ](https://minioplus.liuxp.me/guide/references/faq) + - [MinIO S3 接口](https://minioplus.liuxp.me/guide/references/minio-s3-api) +* MinIO 研究 + - [MinIO 分片 ETAG 生成机制](https://minioplus.liuxp.me/guide/study/etag) + - [Nginx 代理](https://minioplus.liuxp.me/guide/study/proxy) -提供文件上传、下载、删除等接口。 - -### 3.1.1 文件上传任务初始化 - -### 3.1.2 上传完成 - -### 3.1.3 取得文件下载地址 - -### 3.1.4 取得原图地址 - -### 3.1.5 取得缩略图地址 - -### 3.1.6 查询文件元数据 - -### 3.1.7 列表查询文件元数据 - -### 3.1.8 从字节数组创建文件 - -### 3.1.9 从输入流创建文件 - -### 3.1.10 从外部url创建文件 - -### 3.1.11 读取文件 - -### 3.1.12 删除文件 - -### 3.1.13 文件上传（MinIO原生接口） - -### 3.1.14 文件下载（MinIO原生接口） - -## 3.2 Controller 层接口 - -如没有特殊需求，也可以不写 Controller 层接口，minio-plus-extension 中提供了 Controller 层接口定义。 - -### 3.2.1 文件上传任务初始化 - -### 3.2.2 上传完成 - -### 3.2.3 文件下载 - -调用 3.1.3 取得文件下载地址后，返回前端时进行302跳转。 - -### 3.2.4 图片预览 - 原图 - -调用 3.1.3 取得原图地址后，返回前端时进行302跳转。 - -### 3.2.5 图片预览 - 缩略图 - -调用 3.1.3 取得缩略图地址后，返回前端时进行302跳转。 - -## 3.3 引用 MinIO 接口 - -这里给出本项目引用的 MinIO 接口列表。 - -### 3.3.1 bucketExists 检查文件桶是否存在 - -### 3.3.2 makeBucket 创建文件桶 - -### 3.3.3 createMultipartUpload 创建分片上传 - -### 3.3.4 completeMultipartUpload 合并文件 - -### 3.3.5 listParts 查询已上传的分片列表 - -### 3.3.6 getPresignedObjectUrl 获取上传、下载、预览图链接 - -### 3.3.7 putObject 上传 - -### 3.3.8 getObject 下载 - -### 3.3.9 removeObject 删除 - -# 4 数据库设计 | Database Design - -## 4.1 文件元数据信息表 | file_metadata_info - -| Name | Type | Length | Not Null | Virtual | Key | Comment | -|----------------|----------|--------|----------|---------|------|----------------| -| id | bigint | 20 | True | False | True | 自增ID | -| file_key | varchar | 50 | True | False | | 文件KEY | -| file_md5 | varchar | 50 | False | False | | 文件MD5值 | -| file_name | varchar | 255 | True | False | | 文件名 | -| file_mime_type | varchar | 128 | False | False | | MIME类型 | -| file_suffix | varchar | 20 | False | False | | 文件后缀 | -| file_size | bigint | 20 | False | False | | 文件大小 | -| is_preview | tinyint | 1 | False | False | | 预览图 0:无 1:有 | -| is_private | tinyint | 1 | False | False | | 是否私有 0:否 1:是 | -| bucket | varchar | 20 | True | False | | 存储桶 | -| bucket_path | varchar | 20 | True | False | | 存储桶路径 | -| upload_id | varchar | 255 | False | False | | 上传任务id | -| is_finished | tinyint | 1 | True | False | | 状态 0:未完成 1:已完成 | -| is_part | tinyint | 1 | False | False | | 是否分块 0:否 1:是 | -| part_number | int | 4 | False | False | | 分块数量 | -| create_time | datetime | | True | False | | 创建时间 | -| create_user | varchar | 255 | True | False | | 创建用户 | -| update_time | datetime | | True | False | | 更新时间 | -| update_user | varchar | 255 | True | False | | 更新用户 | - -``` -CREATE TABLE `file_metadata_info` ( - `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键', - `file_key` varchar(50) NOT NULL COMMENT '文件KEY', - `file_md5` varchar(50) DEFAULT NULL COMMENT '文件md5', - `file_name` varchar(255) NOT NULL COMMENT '文件名', - `file_mime_type` varchar(128) DEFAULT NULL COMMENT 'MIME类型', - `file_suffix` varchar(20) DEFAULT NULL COMMENT '文件后缀', - `file_size` bigint(20) DEFAULT NULL COMMENT '文件大小', - `is_preview` tinyint(1) DEFAULT '0' COMMENT '预览图 0:无 1:有', - `is_private` tinyint(1) DEFAULT '0' COMMENT '是否私有 0:否 1:是', - `bucket` varchar(20) NOT NULL COMMENT '存储桶', - `bucket_path` varchar(20) NOT NULL COMMENT '存储桶路径', - `upload_id` varchar(255) DEFAULT NULL COMMENT '上传任务id', - `is_finished` tinyint(1) NOT NULL DEFAULT '0' COMMENT '状态 0:未完成 1:已完成', - `is_part` tinyint(1) DEFAULT NULL COMMENT '是否分块 0:否 1:是', - `part_number` int(4) DEFAULT NULL COMMENT '分块数量', - `create_time` datetime NOT NULL COMMENT '创建时间', - `create_user` varchar(255) NOT NULL COMMENT '创建用户', - `update_time` datetime NOT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', - `update_user` varchar(255) NOT NULL COMMENT '更新用户', - PRIMARY KEY (`id`) USING BTREE, - KEY `INDEX_KEY` (`file_key`), - KEY `INDEX_MD5` (`file_md5`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文件元数据信息表'; -``` - -# 5 开发计划 | Plan - -简单画了一个要实现内容的看板 - -![开发计划](docs/src/public/image/开发计划.png) - -# 6 使用 | Getting Started - -## 6.1 使用 minio-plus-all-spring-boot-starter - -## 6.2 使用 minio-plus-core-spring-boot-starter - -# 7 代码托管 | Managed Code +# 4 代码托管 | Managed Code * [https://gitee.com/lxp135/minio-plus](https://gitee.com/lxp135/minio-plus/) * [https://github.com/lxp135/minio-plus](https://github.com/lxp135/minio-plus/) 以上仓库中代码完全一致，各位同学可根据网络状况自行选择。 -# 8 版权 | License +# 5 版权 | License 本项目基于 Apache License Version 2.0 开源协议，可用于商业项目。 协议内容：[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) -# 9 参与贡献 | Credits +# 6 参与贡献 | Credits -## 9.1 编写代码 +## 6.1 编写代码 * 在 Gitee Fork 项目到自己的仓库 * 把 fork 过去的项目也就是你的项目 pull 到你的本地 @@ -318,23 +206,15 @@ CREATE TABLE `file_metadata_info` ( * 登录 Gitee 在你首页可以看到一个 pull request 按钮，点击它，填写一些说明信息，然后提交 * 等待维护者合并或者关闭 -## 9.2 反馈问题 +## 6.2 反馈问题 欢迎提交**ISSUE**，请写清楚问题的具体原因，重现步骤和环境。 * Gitee Issue 地址 [https://gitee.com/lxp135/minio-plus/issues](https://gitee.com/lxp135/minio-plus/issues) * GitHub Issue 地址 [https://github.com/lxp135/minio-plus/issues](https://github.com/lxp135/minio-plus/issues) -## 9.3 微信群 +## 6.3 微信群 ![开发计划](docs/src/public/image/wechat_group.jpg) 如果二维码失效，可以加我的微信*movedisk_1*，我会手动拉您入群。 - -# 10 参考资料 | Reference - -* [MinIO S3 APIs](docs/src/guide/references/minio-s3-api.md) - - - - diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index ef76ccc..8ca05f1 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -113,9 +113,13 @@ export default defineConfig({ link: '/guide/user/quick-start' }, { - text: 'API 使用', + text: 'API接口', link: '/guide/user/api' }, + { + text: '文件元数据', + link: '/guide/user/db' + }, { text: '配置文件', link: '/guide/user/config' diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 1ca683c..0000000 --- a/docs/README.md +++ /dev/null @@ -1,36 +0,0 @@ -## 安装yarn -``` -npm install -g yarn -``` -## 安装vitepress -``` -yarn add --dev vitepress -``` -## 启动 -``` -yarn dev -``` - -## 常见问题 - -### 安装 vitepress 提示 node 版本错误，如何切换 node 版本 - -访问 nvm-windows 的 [GitHub](https://github.com/coreybutler/nvm-windows) 页面。 -下载并安装nvm-windows。 -安装完成后，打开命令行（例如PowerShell或CMD）。 -查看所有可用的Node.js版本： -``` -nvm list available -``` -安装你想要的Node.js版本，例如： -``` -nvm install 18.18.0 -``` -使用你刚刚安装的版本： -``` -nvm use 18.18.0 -``` -验证是否成功切换到新版本： -``` -node -v -``` \ No newline at end of file diff --git a/docs/src/guide/core/auth.md b/docs/src/guide/core/auth.md index e69de29..6f51202 100644 --- a/docs/src/guide/core/auth.md +++ b/docs/src/guide/core/auth.md @@ -0,0 +1 @@ +# 权限 \ No newline at end of file diff --git a/docs/src/guide/core/bucket.md b/docs/src/guide/core/bucket.md index e69de29..6a45b54 100644 --- a/docs/src/guide/core/bucket.md +++ b/docs/src/guide/core/bucket.md @@ -0,0 +1,11 @@ +# 桶策略 + +* 文档（document）：txt、rtf、ofd、doc、docx、xls、xlsx、ppt、pptx、pdf +* 压缩包（package）：zip、rar、7z、tar、wim、gz、bz2 +* 音频（ audio ）：mp3、wav、flac、acc、ogg、aiff、m4a、wma、midi +* 视频（ video ）：mp4、avi、mov、wmv、flv、mkv、mpeg、mpg 、rmvb +* 图片 – 原始（ image ）：jpeg、jpg、png、bmp、webp、gif +* 图片 – 缩略图（ image-preview ）：默认按照宽度 300 像素压缩缩 +* 其他（ other ） ：未在上述格式中的文件 + +其他规则：文件在桶中存储时，按照 /年/月 划分路径。用以规避Linux ext3文件系统下单个目录最多创建32000个目录的问题，参考了阿里云OSS的处理办法。 \ No newline at end of file diff --git a/docs/src/guide/core/direct.md b/docs/src/guide/core/direct.md index e69de29..52f9b61 100644 --- a/docs/src/guide/core/direct.md +++ b/docs/src/guide/core/direct.md @@ -0,0 +1,23 @@ +# 客户端直连 + +当用户进行文件流的上传和下载时，直接访问MinIO服务器（可配置Nginx代理）。 + +使用minioclient的GetPresignedObjectUrlArgs方法，入参是一个GetPresignedObjectUrlArgs对象，该对象包含了以下属性： + +* bucketName：要访问的桶名。 +* objectName：要访问的对象名。 +* expires：URL的过期时间，单位为秒。 + +该方法的返回值是一个字符串类型的URL，可以用于访问指定的对象，示例： + +``` +http://127.0.0.1:9000/test/test123 +?response-content-type=application%2Fmsword%22&response-content-disposition=attachment%3Bfilename%3D%22xxx.doc%22 +&X-Amz-Algorithm=AWS4-HMAC-SHA256 +&X-Amz-Credential=minioadmin%2F20230620%2Fus-east-1%2Fs3%2Faws4_request +&X-Amz-Date=20230620T071735Z +&X-Amz-Expires=60&X-Amz-SignedHeaders=host +&X-Amz-Signature=5be3535042ffe72fedee8a283e7a5afbc2b068c595c16800cf57f089ed891cc5 +``` + +每次前端请求文件时，都会生成预签名文件地址，文件地址中，有日期、时效、签名。MinIO会进行验签，保证安全性。 \ No newline at end of file diff --git a/docs/src/guide/core/download.md b/docs/src/guide/core/download.md index e69de29..2a31076 100644 --- a/docs/src/guide/core/download.md +++ b/docs/src/guide/core/download.md @@ -0,0 +1,10 @@ +# 下载 + +![文件下载逻辑时序图](../../public/image/文件下载时序图.png) + +浏览器向服务端发起文件读取请求，服务端会根据fileKey入参取得文件的元数据信息。获取文件元数据信息后，根据元数据信息中的是否私有字段和所有者字段判断是否具备文件读取权限。 + +* 当用户具备读取权限时，服务端请求MinIO服务器获取经过预签名的文件访问地址返回给浏览器。 +* 当用户不具备读取权限时，返回给浏览器无访问权限提示信息。 + +浏览器拿到真实文件地址后，读取文件并显示或下载。 \ No newline at end of file diff --git a/docs/src/guide/core/preview.md b/docs/src/guide/core/preview.md index e69de29..5aaf098 100644 --- a/docs/src/guide/core/preview.md +++ b/docs/src/guide/core/preview.md @@ -0,0 +1,9 @@ +# 缩略图 + +![缩略图生成序图](../../public/image/缩略图.png) + +在用户第一次访问图片预览接口时自动生成缩略图，压缩时比例按照图片原始比例不做变化，使用相同的md5名称存入缩略图桶中。 + +* 缩略图：默认按照宽度300像素进行等比例压缩 + +PS：原图尺寸小于缩略图压缩尺寸时，储存原图。 \ No newline at end of file diff --git a/docs/src/guide/core/upload.md b/docs/src/guide/core/upload.md index e69de29..64690f9 100644 --- a/docs/src/guide/core/upload.md +++ b/docs/src/guide/core/upload.md @@ -0,0 +1,31 @@ +# 上传 + +/TODO 上传流程活动图 + +## 秒传 + +![秒传时序图](../../public/image/秒传时序图.png) + +当用户重复上传相同的文件时，每次都需要执行一次完整的文件上传操作，这造成了文件上传过程的冗余，即浪费了用户的时间和服务器的网络IO，重复文件又占用了不必要的服务器磁盘空间。 +针对以上两个问题，minio-plus支持文件秒传特性，解决了传统文件上传中重复文件上传时的问题，提高了文件传输的效率和用户体验，同时减少了文件服务器的存储空间占用。 +实现文件秒传的技术问题主要涉及文件唯一标识的生成和文件重复性检测。 + +* 文件唯一标识生成：在浏览器端，使用MD5哈希算法对待传输文件进行哈希值编码。编码结果为一字符串，作为文件的唯一标识。 +* 文件重复性检测：在服务器端，根据接收到的文件唯一标识在数据库中进行搜索。如果在数据库中找到相同的文件唯一标识，那么判断该文件存在且无需再进行文件传输。 + +## 分片上传 + +分片上传是一种将大文件划分为多个片段并发或按序上传的技术。它有以下几个好处： + +* 提高传输速度：当上传的文件比较大时，将大文件进行分块，同时并发上传多个小块，而不是一整个大文件按顺序上传。这样可以最大限度地利用带宽，从而加快上传速度。 +* 支持断点续传：分块上传是断点续传技术的前置条件，要想实现断点续传，必须先支持分块。 + +![文件上传时序图](../../public/image/文件上传时序图.png) + +## 断点续传 + +断点续传依赖于分片技术，是提高可用性的重要手段，优点如下： + +* 节省时间、减少网络IO、减少磁盘IO：在文件传输过程中遇到问题导致传输失败时，只需重新传输未完成的分片，而不需要重新开始整个传输任务。 +* 增加传输的可靠性：可以避免由于网络波动或其他原因导致整个文件需要重新传输的情况。再也不怕意外断网。在大文件传输时，尤其有用。 +* 随时暂停和恢复：用户可以在传输过程中暂停传输或者中断传输，断点续传可以方便地恢复传输任务。 \ No newline at end of file diff --git a/docs/src/guide/developers/building.md b/docs/src/guide/developers/building.md index e69de29..83c6735 100644 --- a/docs/src/guide/developers/building.md +++ b/docs/src/guide/developers/building.md @@ -0,0 +1 @@ +# 构建与运行 \ No newline at end of file diff --git a/docs/src/guide/developers/contributors.md b/docs/src/guide/developers/contributors.md index e69de29..651c873 100644 --- a/docs/src/guide/developers/contributors.md +++ b/docs/src/guide/developers/contributors.md @@ -0,0 +1,4 @@ +# 贡献者列表 + +* contact@liuxp.me +* tianxiang.deng@foxmail.com \ No newline at end of file diff --git a/docs/src/guide/developers/framework.md b/docs/src/guide/developers/framework.md index e69de29..7123461 100644 --- a/docs/src/guide/developers/framework.md +++ b/docs/src/guide/developers/framework.md @@ -0,0 +1,25 @@ +# 代码结构 + +项目定位为一个MinIO的Java语言SDK，非独立部署服务，并支持spring-boot自动装配。 +用户自行实现数据存储部分，项目仅提供MySQL默认实现。 + +## 模块划分 +![模块划分](../../public/image/模块划分.png) + +* minio-plus-api：MinIO Plus 对外提供的能力接口定义，可以理解为 Service 层接口定义 +* minio-plus-core：核心业务逻辑包，可以理解为 minio-plus-api 包的接口实现 +* minio-plus-extension：扩展包，该包封装了Controller相关接口，可以理解为 minio-plus-api 包的接口的 Controller + 层封装，帮助项目使用时开箱即用 +* minio-plus-common：工具类、配置类包 +* minio-s3-api + * minio-s3-api-definition：MinIO Plus 使用的S3规范接口定义 + * minio-s3-api-official：原生SDK实现 + * minio-s3-api-custom：自主实现 +* minio-plus-spring-boot-starter + * minio-plus-all-spring-boot-starter：包含core、extension、common、api + * minio-plus-core-spring-boot-starter：包含core、common、api +* minio-plus-application + * minio-plus-application-official：使用原生MinIO SDK与元数据使用MySQL数据库的示例工程 + * minio-plus-application-custom：使用自主实现S3规范与数据使用MySQL数据库的示例工程 + +## 包的划分 diff --git a/docs/src/guide/developers/plan.md b/docs/src/guide/developers/plan.md index e69de29..08bc389 100644 --- a/docs/src/guide/developers/plan.md +++ b/docs/src/guide/developers/plan.md @@ -0,0 +1,3 @@ +# 开发计划 + +![开发计划](../../public/image/开发计划.png) \ No newline at end of file diff --git a/docs/src/guide/developers/writing-code.md b/docs/src/guide/developers/writing-code.md index e69de29..1fae8ba 100644 --- a/docs/src/guide/developers/writing-code.md +++ b/docs/src/guide/developers/writing-code.md @@ -0,0 +1,21 @@ +# 提交代码 + +## 推送代码 + +* 在 Gitee Fork 项目到自己的仓库 +* 把 fork 过去的项目也就是你的项目 pull 到你的本地 +* 修改代码 +* commit 代码，push 到自己的库 +* 登录 Gitee 在你首页可以看到一个 pull request 按钮，点击它，填写一些说明信息，然后提交 +* 等待维护者合并或者关闭 + +## 反馈问题 + +欢迎提交**ISSUE**，请写清楚问题的具体原因，重现步骤和环境。 + +* Gitee Issue 地址 [https://gitee.com/lxp135/minio-plus/issues](https://gitee.com/lxp135/minio-plus/issues) +* GitHub Issue 地址 [https://github.com/lxp135/minio-plus/issues](https://github.com/lxp135/minio-plus/issues) + +## 加入我们 + +也欢迎各位朋友直接加入项目，进行长期开发。 \ No newline at end of file diff --git a/docs/src/guide/developers/writing-documents.md b/docs/src/guide/developers/writing-documents.md index e69de29..5d63abf 100644 --- a/docs/src/guide/developers/writing-documents.md +++ b/docs/src/guide/developers/writing-documents.md @@ -0,0 +1,42 @@ +# 编写文档 + +本项目使用 vitepress 进行文档编写，文档保存在项目仓库的/docs路径下。 + +## 编译文档工程 + +### 安装yarn +``` +npm install -g yarn +``` +### 安装vitepress +``` +yarn add --dev vitepress +``` +### 启动 +``` +yarn dev +``` + +### 常见问题 + +#### 安装 vitepress 提示 node 版本错误，如何切换 node 版本 + +访问 nvm-windows 的 [GitHub](https://github.com/coreybutler/nvm-windows) 页面。 +下载并安装nvm-windows。 +安装完成后，打开命令行（例如PowerShell或CMD）。 +查看所有可用的Node.js版本： +``` +nvm list available +``` +安装你想要的Node.js版本，例如： +``` +nvm install 18.18.0 +``` +使用你刚刚安装的版本： +``` +nvm use 18.18.0 +``` +验证是否成功切换到新版本： +``` +node -v +``` \ No newline at end of file diff --git a/docs/src/guide/intro.md b/docs/src/guide/intro.md index 9eda488..f2fde25 100644 --- a/docs/src/guide/intro.md +++ b/docs/src/guide/intro.md @@ -47,7 +47,8 @@ MinIO 的基础上只做增强，不侵入 MinIO 代码，只为简化开发、 * [更新日志](released.md) * 用户手册 - [快速开始](user/quick-start) - - [API 使用](user/api) + - [API接口](user/api) + - [文件元数据](user/db) - [配置文件](user/config) - [非官方S3实现](user/custom) * 开发者手册 diff --git a/docs/src/guide/references/faq.md b/docs/src/guide/references/faq.md index 32914fe..307d253 100644 --- a/docs/src/guide/references/faq.md +++ b/docs/src/guide/references/faq.md @@ -1 +1 @@ -FAQ \ No newline at end of file +# 常见问题 \ No newline at end of file diff --git a/docs/src/guide/released.md b/docs/src/guide/released.md index e69de29..a8635ce 100644 --- a/docs/src/guide/released.md +++ b/docs/src/guide/released.md @@ -0,0 +1,2 @@ +# 更新日志 + diff --git a/docs/src/guide/study/etag.md b/docs/src/guide/study/etag.md index e1ebc17..69f34e0 100644 --- a/docs/src/guide/study/etag.md +++ b/docs/src/guide/study/etag.md @@ -1,3 +1,5 @@ +# MinIO 分片 ETAG 生成机制 + 在 MinIO 中，分片上传和普通上传时，文件一致性校验是不一样的，我们分开说。 ## 普通上传 diff --git a/docs/src/guide/study/proxy.md b/docs/src/guide/study/proxy.md index e69de29..232bde1 100644 --- a/docs/src/guide/study/proxy.md +++ b/docs/src/guide/study/proxy.md @@ -0,0 +1 @@ +# Nginx 代理 \ No newline at end of file diff --git a/docs/src/guide/user/api.md b/docs/src/guide/user/api.md index e69de29..215fea8 100644 --- a/docs/src/guide/user/api.md +++ b/docs/src/guide/user/api.md @@ -0,0 +1,75 @@ +# API接口 + +## 3.1 Service 层接口 + +提供文件上传、下载、删除等接口。 + +### 3.1.1 文件上传任务初始化 + +### 3.1.2 上传完成 + +### 3.1.3 取得文件下载地址 + +### 3.1.4 取得原图地址 + +### 3.1.5 取得缩略图地址 + +### 3.1.6 查询文件元数据 + +### 3.1.7 列表查询文件元数据 + +### 3.1.8 从字节数组创建文件 + +### 3.1.9 从输入流创建文件 + +### 3.1.10 从外部url创建文件 + +### 3.1.11 读取文件 + +### 3.1.12 删除文件 + +### 3.1.13 文件上传（MinIO原生接口） + +### 3.1.14 文件下载（MinIO原生接口） + +## 3.2 Controller 层接口 + +如没有特殊需求，也可以不写 Controller 层接口，minio-plus-extension 中提供了 Controller 层接口定义。 + +### 3.2.1 文件上传任务初始化 + +### 3.2.2 上传完成 + +### 3.2.3 文件下载 + +调用 3.1.3 取得文件下载地址后，返回前端时进行302跳转。 + +### 3.2.4 图片预览 - 原图 + +调用 3.1.3 取得原图地址后，返回前端时进行302跳转。 + +### 3.2.5 图片预览 - 缩略图 + +调用 3.1.3 取得缩略图地址后，返回前端时进行302跳转。 + +## 3.3 引用 MinIO 接口 + +这里给出本项目引用的 MinIO 接口列表。 + +### 3.3.1 bucketExists 检查文件桶是否存在 + +### 3.3.2 makeBucket 创建文件桶 + +### 3.3.3 createMultipartUpload 创建分片上传 + +### 3.3.4 completeMultipartUpload 合并文件 + +### 3.3.5 listParts 查询已上传的分片列表 + +### 3.3.6 getPresignedObjectUrl 获取上传、下载、预览图链接 + +### 3.3.7 putObject 上传 + +### 3.3.8 getObject 下载 + +### 3.3.9 removeObject 删除 \ No newline at end of file diff --git a/docs/src/guide/user/config.md b/docs/src/guide/user/config.md index e69de29..050731a 100644 --- a/docs/src/guide/user/config.md +++ b/docs/src/guide/user/config.md @@ -0,0 +1 @@ +# 配置文件 \ No newline at end of file diff --git a/docs/src/guide/user/custom.md b/docs/src/guide/user/custom.md index e69de29..0c5d0b0 100644 --- a/docs/src/guide/user/custom.md +++ b/docs/src/guide/user/custom.md @@ -0,0 +1 @@ +# 非官方S3实现 \ No newline at end of file diff --git a/docs/src/guide/user/db.md b/docs/src/guide/user/db.md new file mode 100644 index 0000000..3975f01 --- /dev/null +++ b/docs/src/guide/user/db.md @@ -0,0 +1,55 @@ +# 文件元数据 + +文件元数据的数据结构设计，项目使用时，可自行扩展。 + +## 表设计 + +| Name | Type | Length | Not Null | Virtual | Key | Comment | +|----------------|----------|--------|----------|---------|------|----------------| +| id | bigint | 20 | True | False | True | 自增ID | +| file_key | varchar | 50 | True | False | | 文件KEY | +| file_md5 | varchar | 50 | False | False | | 文件MD5值 | +| file_name | varchar | 255 | True | False | | 文件名 | +| file_mime_type | varchar | 128 | False | False | | MIME类型 | +| file_suffix | varchar | 20 | False | False | | 文件后缀 | +| file_size | bigint | 20 | False | False | | 文件大小 | +| is_preview | tinyint | 1 | False | False | | 预览图 0:无 1:有 | +| is_private | tinyint | 1 | False | False | | 是否私有 0:否 1:是 | +| bucket | varchar | 20 | True | False | | 存储桶 | +| bucket_path | varchar | 20 | True | False | | 存储桶路径 | +| upload_id | varchar | 255 | False | False | | 上传任务id | +| is_finished | tinyint | 1 | True | False | | 状态 0:未完成 1:已完成 | +| is_part | tinyint | 1 | False | False | | 是否分块 0:否 1:是 | +| part_number | int | 4 | False | False | | 分块数量 | +| create_time | datetime | | True | False | | 创建时间 | +| create_user | varchar | 255 | True | False | | 创建用户 | +| update_time | datetime | | True | False | | 更新时间 | +| update_user | varchar | 255 | True | False | | 更新用户 | + +## MySQL脚本 +``` +CREATE TABLE `file_metadata_info` ( + `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键', + `file_key` varchar(50) NOT NULL COMMENT '文件KEY', + `file_md5` varchar(50) DEFAULT NULL COMMENT '文件md5', + `file_name` varchar(255) NOT NULL COMMENT '文件名', + `file_mime_type` varchar(128) DEFAULT NULL COMMENT 'MIME类型', + `file_suffix` varchar(20) DEFAULT NULL COMMENT '文件后缀', + `file_size` bigint(20) DEFAULT NULL COMMENT '文件大小', + `is_preview` tinyint(1) DEFAULT '0' COMMENT '预览图 0:无 1:有', + `is_private` tinyint(1) DEFAULT '0' COMMENT '是否私有 0:否 1:是', + `bucket` varchar(20) NOT NULL COMMENT '存储桶', + `bucket_path` varchar(20) NOT NULL COMMENT '存储桶路径', + `upload_id` varchar(255) DEFAULT NULL COMMENT '上传任务id', + `is_finished` tinyint(1) NOT NULL DEFAULT '0' COMMENT '状态 0:未完成 1:已完成', + `is_part` tinyint(1) DEFAULT NULL COMMENT '是否分块 0:否 1:是', + `part_number` int(4) DEFAULT NULL COMMENT '分块数量', + `create_time` datetime NOT NULL COMMENT '创建时间', + `create_user` varchar(255) NOT NULL COMMENT '创建用户', + `update_time` datetime NOT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `update_user` varchar(255) NOT NULL COMMENT '更新用户', + PRIMARY KEY (`id`) USING BTREE, + KEY `INDEX_KEY` (`file_key`), + KEY `INDEX_MD5` (`file_md5`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文件元数据信息表'; +``` \ No newline at end of file diff --git a/docs/src/guide/user/quick-start.md b/docs/src/guide/user/quick-start.md index 6169108..c97d7d9 100644 --- a/docs/src/guide/user/quick-start.md +++ b/docs/src/guide/user/quick-start.md @@ -1,2 +1,5 @@ # 快速开始 +## 使用 minio-plus-all-spring-boot-starter + +## 使用 minio-plus-core-spring-boot-starter \ No newline at end of file