第十五章. 文件管理（核心：ossTemplate 抽象与 MinIO 实战）

本章学习路径

我们将从“为什么需要它”出发，层层递进，从“配置”到“应用”，再到“避坑”：


15.1. [核心] 不只是“文件管理”，更是“OSS 抽象层”

我们点击 系统管理 -> 文件管理，会看到一个上传界面。如果仅仅把它当作一个“网盘”，那就太小看 RVP 的野心了。

在开发中，我们总会面临一个选择：文件存在哪？

• 方案 A：存 MinIO（私有化部署）。
• 方案 B：存阿里云 OSS。
• 方案 C：存腾讯云 COS。
• 方案 D：存七牛云 Kodo。

如果你的代码写死了 MinIO 的 API，那么半年后老板让你迁到阿里云，你将不得不重构所有上传和下载的业务代码。

15.1.1. 为什么需要“配置管理”？

为了解决这个“重构”的灾难，RVP 引入了一个强大的“抽象层”。

我们点击文件管理界面右上角的“配置管理”。

你会看到这里罗列了 MinIO、七牛云、阿里云、腾讯云等配置。这个界面，就是 RVP 的“OSS 配置中心”。它不是一个简单的“文件管理”，而是一个“对象存储（OSS）的统一管理平台”。

15.1.2. RVP 的 ossTemplate 抽象：一次编码，多渠道存储

RVP 的后端封装了一个 ossTemplate（OSS 模板）接口。

对于业务开发者来说，你不需要关心底层用的是 MinIO 还是阿里。你调用上传时，代码永远只有一行：
ossTemplate.upload(file);

而 RVP 框架会根据“配置管理”中的设置，动态地 决定这个 ossTemplate 究竟是去调用 MinIO 的 SDK，还是阿里云的 SDK。

这就是“面向接口编程”的经典实践：业务代码（ossTemplate.upload）与具体实现（MinIO, Aliyun）彻底解耦。

15.1.3. 多渠道并存：UI 的“默认”与后端的“按需调用”

“配置管理”列表里有这么多渠道，系统怎么知道用哪个？

1. UI 使用“默认”：在“文件管理”这个 UI 界面 上传文件时，系统会固定使用“配置 Key”为 default（或 minio，取决于你的版本配置）的那一条配置。

2. 后端“按需调用”：在我们的后端业务代码中，我们完全可以不使用“默认”配置。我们可以指定 Key 来获取特定的 ossTemplate：

   • OssTemplate aliyunTemplate = OssFactory.getTemplate("aliyun");
   • aliyunTemplate.upload(file); // 这就传到了阿里云

   这意味着，我们可以实现非常灵活的业务：比如“普通用户”上传的文件走 minio（默认，成本低），“VIP 用户”上传的文件走 aliyun（指定 Key，速度快）。

15.2. 启动与配置 MinIO 服务

现在我们明白了 RVP 的设计思想，我们来实战 RVP 默认集成 的对象存储——MinIO。

MinIO 是一个开源的、S3 兼容的对象存储服务，非常适合在开发环境和私有化部署中使用。

15.2.1. 启动 MinIO（9000 API / 9001 Console）

首先，我们需要在本地启动 MinIO 服务。我们可以将启动命令封装为一个 .bat 批处理文件，方便一键启动：

1
2
3
4
5

@echo off
rem 启动 MinIO 服务
rem ./data 指定数据存储目录
rem --console-address :9001 指定后台管理界面的端口
minio.exe server ./data --console-address :9001

双击运行此 .bat 文件，MinIO 启动成功。它会监听两个端口：

• API 端口（默认 9000）：给 RVP 后端程序 调用的端口。
• Console 端口（我们指定 9001）：给我们（管理员）访问的 Web 后台。

15.2.2. MinIO 控制台：获取 Access Key 与 Secret Key

我们打开浏览器，访问 MinIO 的后台：http://127.0.0.1:9001。默认的账号密码都是 minioadmin。

登录后，我们需要创建 RVP 访问 MinIO 所需的“身份凭证”：

15.2.3. RVP 配置管理：填写 MinIO 核心参数

现在我们拿到了 AK 和 SK，回到 RVP 的“配置管理”界面。

1. 找到 default (或 minio) 那条配置，点击“修改”。
2. 访问站点：http://127.0.0.1:9000 (注意是 9000 API 端口，不是 9001)
3. Access Key：NF64eLDrZP4sDW8Ey0Ql（复制你自己的）
4. Secret Key：bMZgzRTqmXZkZazxOZflKFyW8q9BdL0f2gjSRykg（复制你自己的）
5. 桶名称 (Bucket Name)：ruoyi (我们可以自定义一个，比如 prorise)
6. 是否 https：否 (我们本地启动的是 http)
7. 桶权限类型：public (保持默认)
8. 点击“确定”保存。

15.2.4. 首次上传：RVP 自动创建 Bucket

此时，我们回到 MinIO 的 9001 后台，查看 Buckets 菜单，会发现里面是 空 的。我们并没有手动创建 prorise 这个桶。

别担心，RVP 已经帮我们处理好了。

我们回到 RVP 的“文件管理”界面，点击“上传图片”，随便选择一张图片。

• 现象：上传成功！
• 验证：我们回到 MinIO 后台（9001），刷新 Buckets 页面。
• 结果：prorise 这个桶被 自动创建 出来了！

这就是 RVP ossTemplate 的强大之处：它在上传时，会自动检测 Bucket 是否存在，如果不存在，它会 自动帮我们创建。

15.2.5. “预览开关”的切换

上传成功后，在 RVP 文件列表里，我们可以看到这张图片：

如果我们点击顶部的“预览开关：禁用”，列表会变回“文件路径”模式，这可以方便我们复制文件的 URL。

15.3. 关键配置：URL 结构、自定义域名与前缀

我们来仔细研究一下上传成功后，RVP 生成的这个文件 URL。

15.3.1. URL 结构解析 (<host>:<port>/<bucket>/...)

禁用“预览开关”后，我们看到的 URL 类似：
http://127.0.0.1:9000/prorise/2025/11/12/6ebe406258bc4a379fb712ee3a527f2e.png

我们来拆解它：

• http://127.0.0.1:9000：来自“配置管理”中的“访问站点”。
• prorise：来自“桶名称”。
• 2025/11/12：RVP 自动生成的“日期路径”，便于归档。
• xxxxxxxx.png：RVP 重命名后的“文件名”。

15.3.2. “自定义域名”：使用 Nginx 反向代理隐藏 IP

在生产环境中，我们绝不能把 http://127.0.0.1:9000 这样的 IP 和端口暴露给用户，这既不安全也不专业。

我们需要使用“自定义域名”。

实现原理：Nginx 反向代理
我们需要配置 Nginx，将一个“漂亮”的域名（如 oss.prorise.com）反向代理到“丑陋”的 127.0.0.1:9000。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# 定义一个 upstream 块，用于指定后端服务器组。
# 这样做的好处是，如果未来有多个后端服务器，可以方便地进行负载均衡。
upstream minio_server {
    # server 指令定义了后端服务的一个地址。
    # 这里是我们要代理到的“丑陋”地址和端口。
    server 127.0.0.1:9000;
}

# 定义一个 server 块，它代表一个虚拟主机，用于处理特定域名的请求。
server {
    # 监听 80 端口，这是标准的 HTTP 请求端口。
    listen 80;
    # listen [::]:80; # 如果需要，取消此行注释以同时监听 IPv6 的 80 端口。

    # 指定这个 server 块要处理哪个域名过来的请求。
    # 这里的 oss.prorise.com 就是您想要使用的“漂亮”域名。
    server_name oss.prorise.com;

    # 定义根位置块，处理所有发往此域名的请求。
    location / {
        # proxy_pass 是反向代理的核心指令。
        # 它告诉 Nginx 将请求转发到哪里。
        # "http://minio_server" 引用了我们上面定义的 upstream 块。
        # Nginx 会将请求转发给 minio_server 组中的一台服务器。
        # 注意：这里的 http:// 不能省略。
        proxy_pass http://minio_server;

        # 以下是一些推荐的代理头信息设置，它们会将原始请求的一些重要信息传递给后端服务器。
        # 这对于后端应用正确识别客户端信息至关重要。

        # 将原始请求的 Host 头部字段传递给后端。
        # $host 变量包含了客户端请求的域名，即 "oss.prorise.com"。
        proxy_set_header Host $host;

        # 传递客户端的真实 IP 地址。
        proxy_set_header X-Real-IP $remote_addr;

        # 传递一个包含了客户端真实 IP 和所有经过的代理服务器 IP 的列表。
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # 告诉后端服务器，客户端是通过 HTTPS（如果使用了）还是 HTTP 连接到 Nginx 的。
        # $scheme 变量的值是 "http" 或 "https"。
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

RVP 如何配置？
假设 Nginx 已经配置完毕。我们只需回到“配置管理”，修改 MinIO 配置：

• 访问站点：http://127.0.0.1:9000 (保持不变！ 这里必须填 MinIO 的真实 API 地址)
• 自定义域名：http://oss.prorise.com (填写这个新字段)

保存后，我们 重新上传一张 图片。我们会发现，RVP 生成的新 URL 已经自动变成了：
http://oss.prorise.com/prorise/2025/11/12/yyyyyyyy.png

RVP 的逻辑是：如果“自定义域名”字段不为空，就优先使用它来拼接返回的 URL。

15.3.3. “前缀”配置：在 Bucket 内实现目录隔离

有时，我们希望在 Bucket 内部再加一层“虚拟目录”，比如把所有“文件管理”模块上传的文件都放到 upload 目录下。

1. 回到“配置管理”，修改 MinIO 配置。
2. 前缀：填入 upload
3. 点击“确定”保存。

我们 再次上传一张 图片。生成的 URL 会自动变为：
http://oss.prorise.com/prorise/upload/2025/11/12/zzzzzzzz.png

“前缀”字段会自动插入到 “Bucket” 和 “日期” 之间，非常适合用于在同一个 Bucket 内隔离不同业务模块的文件。

本节小结（前三节）

• 核心设计：RVP 提供了 ossTemplate 抽象层，通过“配置管理”实现多 OSS 渠道（MinIO, 阿里, 腾讯）的解耦。
• MinIO 实战：我们学会了启动 MinIO（9000/9001 端口）、获取 AK/SK，并在 RVP 中配置它。
• 自动创桶：RVP 在首次上传时会自动创建 Bucket。
• URL 定制：我们掌握了通过“自定义域名”（配合 Nginx 反代）和“前缀”来优化和组织我们的文件 URL。

15.4. [重点] HTTPS 配置的“陷阱”

在我们将系统部署到生产环境时，几乎 100% 会启用 HTTPS。而 MinIO 在 HTTPS 配置上，是 RVP 文件管理中 最容易出错 的“陷阱”之一。

15.4.1. 错误复现：MinIO + IP + HTTPS = SSL 错误

我们来模拟一次这个“经典”错误：

1. MinIO 状态：我们的 MinIO 服务仍是通过 .bat 启动的，运行在 http://127.0.0.1:9000（HTTP 模式）。
2. RVP 配置：我们回到“配置管理”，修改 MinIO 配置：
   • 访问站点：http://127.0.0.1:9000 (保持不变)
   • 是否 https：我们天真地将其改为 是。
3. 保存并上传：点击“确定”保存。然后回到“文件管理”界面，尝试上传一张新图片。
4. 现象：上传失败！系统会报出一个“天书”般的错误，大意是：
   判断 'bucket' 是否存在失败，Failed to send request, ... SSL ...

[核心] 错误原因：
这个错误是 必然 的。

RVP 的“是否 https”开关，是用来告诉 RVP 的 Java 客户端：“你应该用 https 协议去连接‘访问站点’”。

当 RVP 的客户端尝试用 https:// 协议去握手一个 只提供了 http:// 服务 的 9000 端口时，SSL 握手 100% 失败。

15.4.2. [重点] 正确的 HTTPS 解决方案

我们不能“强迫”一个 HTTP 服务去响应 HTTPS。正确的解决方案有两种，都发生在 RVP 之外：

方案一：Nginx 代理（推荐）
这是生产环境的最佳实践。

1. Nginx 层：配置 Nginx 监听 https://oss.prorise.com，并配置好 SSL 证书。
2. Nginx 转发：将所有请求 反向代理 到 MinIO 的 内网 HTTP 地址 http://127.0.0.1:9000。
3. RVP 配置：
   • 访问站点：http://127.0.0.1:9000 (RVP 依然连接内网 HTTP)
   • 自定义域名：https://oss.prorise.com (带 https:// 的 公网域名)
   • 是否 https：否 (因为 RVP 访问的“站点”本身是 http)

方案二：MinIO 本身配置 HTTPS
不推荐，这需要你为 MinIO 服务本身配置 SSL 证书，操作相对复杂。

[结论] RVP 的“是否 https”开关，必须忠实地反映“访问站点”字段的真实协议。如果“访问站点”是 http://，就必须选 否。

15.5. [核心] “公有桶” vs “私有桶”

这是 MinIO 配置中 第二大“巨坑”。它不仅关系到安全，更关系到 RVP 与 MinIO 状态 不同步 的问题。

15.5.1. 公有桶（Public）：直接 URL 访问

• RVP 配置：桶权限类型 = public
• RVP 行为：上传文件后，RVP 会返回一个 永久有效 的 URL，格式如：
  .../prorise/2025/11/12/file.png
• MinIO 状态：RVP 自动创建的 prorise 桶，在 MinIO 控制台（9001）的“Buckets -> Access Policy”中，默认为 public。
• 结论：一切正常。任何人拿到这个 URL 都能访问。

15.5.2. 私有桶（Private）：带时效性的“签名 URL”

• RVP 配置：桶权限类型 = private
• RVP 行为：上传文件后，RVP 会返回一个 带签名的临时 URL，格式如：
  .../prorise/file.png?X-Amz-Algorithm=...&X-Amz-Credential=...&X-Amz-Date=...&X-Amz-Expires=604800&X-Amz-Signature=...
• 核心：这个 URL 包含一个 Expires=604800 参数，代表它在 7 天（604800 秒）后 自动失效。

15.5.3. [巨坑] RVP 与 MinIO 控制台的“权限不同步”

现在，我们来复现这个“巨坑”：

1. MinIO 状态：我们的 prorise 桶是在“公有”模式下被 RVP 自动创建 的，其在 MinIO（9001）控制台的访问策略 目前是 public。
2. RVP 操作：我们回到 RVP“配置管理”，将 prorise 桶的“桶权限类型”从 public 修改为 private，并保存。
3. RVP 验证：我们回到“文件管理”界面，刷新列表。
4. 现象（RVP 侧）：RVP 开始 假装 这是一个私有桶。它显示的文件 URL 已经变成了 15.5.2 中那种 带签名的临时 URL。

陷阱来了：

此时，我们 故意 复制那个 不带签名 的“永久 URL”（.../prorise/2025/11/12/file.png），在浏览器中打开。

结果：文件依然可以访问！

[核心] 陷阱原因：
RVP 修改“桶权限类型”配置，仅仅是改变了 RVP 后端 ossTemplate 生成 URL 的“策略”（从“生成永久 URL”变为“生成签名 URL”）。

这个操作 并不会 自动登录到你的 MinIO（9001）控制台，去 修改那个桶的真实“访问策略”。

你制造了一个“精神分裂”的状态：RVP（程序）认为桶是私有的，而 MinIO（服务器）认为桶还是公有的。

15.5.4. [重点] 正确配置“私有桶”的流程

要真正实现“私有桶”，必须 手动同步 两边的状态：

1. 第一步（MinIO 侧）：登录 MinIO 控制台（9001），进入 Buckets -> prorise。
2. 第二步（MinIO 侧）：将其 Access Policy 从 public 修改为 private，并保存。
3. 第三步（RVP 侧）：回到 RVP“配置管理”，将 prorise 桶的“桶权限类型”修改为 private，并保存。

完成这三步后，才是一个真正的“私有桶”。此时，你再去访问那个“永久 URL”，MinIO 就会返回 Access Denied（访问拒绝）。只有 RVP 生成的那个带签名的“临时 URL”才能在有效期内访问。