\345\257\271\350\261\241\345\255\230\345\202\250\346\235\203\351\231\220\350\256\276\350\256\241\346\226\271\346\241\210.md
... ...
@@ -1,3 +1,119 @@
1
+# Minio存储分桶方案设计文档 (V2)
2
+
3
+## 1. 概述
4
+
5
+为解决原有单一公有存储桶配置下，业务敏感数据（如用户个人信息、业务报告、内部文件等）存在的潜在泄露风险，同时兼顾非敏感静态资源（如Logo、图标、公开文档）的便捷访问需求，特设计此Minio存储分桶方案。本方案通过引入**私有桶**与**公有桶**的分离配置，使业务能根据数据敏感性灵活选择存储策略，并通过严格的**向后兼容**机制，确保存量业务平滑过渡。
6
+
7
+## 2. 设计目标
8
+
9
+1. **安全隔离**：为敏感数据提供私有桶存储，防止未经授权的直接访问。
10
+2. **灵活访问**：为非敏感静态资源保留公有桶，支持前端直接引用，无需后端代理。
11
+3. **业务无感升级（核心）**：通过版本开关控制，确保所有现有业务（V1）无需任何修改即可正常运行。
12
+4. **配置清晰**：新增配置项意图明确，与原有配置易于区分。
13
+5. **使用便捷**：为后端业务提供清晰的API接口，用于获取对应类型的桶；为前端上传提供明确的参数标识。
14
+
15
+## 3. 配置说明
16
+
17
+### 3.1 原有配置 (V1兼容模式)
18
+此配置保持完全不变，用于兼容所有现有业务。当 `minio.bucket.edition` 未配置或不为 `v2` 时，系统运行于此模式。
19
+```properties
20
+# Minio服务地址
21
+minio.endpoint=http://192.168.175.54:9000
22
+# 访问密钥
23
+minio.accessKey=snest
24
+# 私密密钥
25
+minio.secretKey=12345678
26
+# 默认存储桶名称（在此模式下，此桶被视为公有桶）
27
+minio.bucketName=apps
28
+```
29
+
30
+### 3.2 新增V2版本配置
31
+当开启V2版本后，系统启用公有、私有分桶模式。需在原有配置基础上增加如下两项：
32
+```properties
33
+# ========== 原有配置 ==========
34
+minio.endpoint=http://192.168.175.54:9000
35
+minio.accessKey=snest
36
+minio.secretKey=12345678
37
+minio.bucketName=apps
38
+# ========== 新增V2配置 ==========
39
+# 功能版本开关，必须显式设置为 `v2` 才能启用新特性
40
+minio.bucket.edition=v2
41
+# 公有桶名称，用于存放可公开访问的资源（如Logo,图标）
42
+minio.iidpBucket=iidp-bucket
43
+```
44
+**配置解读：**
45
+- `minio.bucket.edition=v2`：此配置为**总开关**。仅当应用读取到此配置且值为`v2`时，才会激活下文所述的所有V2新特性（包括分桶逻辑和新接口）。
46
+- `minio.iidpBucket`：此配置定义了一个**公有桶**的名称。
47
+- 原有的 `minio.bucketName` 所指向的桶(`apps`)，在V2模式下，其**语义变更为私有桶**。
48
+
49
+## 4. 接口变更与使用说明
50
+
51
+### 4.1 后端接口
52
+
53
+引擎层将提供以下接口供业务代码调用：
54
+
55
+| 接口方法 | 版本 | 返回桶类型 | 说明 |
56
+| :--- | :--- | :--- | :--- |
57
+| `getBucket()` | V1 & V2 | V1：公有桶<br>V2：**私有桶** | **兼容性核心接口**。V1模式下，返回原`minio.bucketName`(公有桶)；V2模式下，返回原`minio.bucketName`，但其性质为私有桶。**现有业务代码无需任何修改。** |
58
+| `getIIDPBucket()` | **仅 V2** | **公有桶** | **新增接口**。仅在配置了`minio.bucket.edition=v2`时有效，返回由`minio.iidpBucket`配置指定的公有桶对象。 |
59
+
60
+**后端业务代码调整示例：**
61
+```java
62
+// 场景1：访问敏感业务数据（如用户上传的身份证照），应使用私有桶
63
+MinioClient privateBucketClient = minioService.getBucket();
64
+privateBucketClient.putObject(...); // 此文件默认无法通过URL直接访问
65
+
66
+// 场景2：访问或存储公开资源（如网站logo），应使用公有桶
67
+// 注意：此调用在V1配置下会报错或返回null，需确保在V2模式下使用
68
+if (isV2Mode()) { // 业务可根据需要判断版本
69
+ MinioClient publicBucketClient = minioService.getIIDPBucket();
70
+ publicBucketClient.putObject(...); // 此文件生成URL可直接被前端访问
71
+}
72
+```
73
+
74
+### 4.2 前端上传联动
75
+
76
+前端文件上传组件需根据业务场景，在调用后端通用上传接口时，增加 `bucketType` 参数。
77
+
78
+- **上传到公有桶**：`bucketType = 'public'`
79
+- **上传到私有桶**：`bucketType = 'private'` 或 不传/传其他值（由后端定义默认逻辑，建议默认私有桶以保证安全）。
80
+
81
+前端示例（伪代码）：
82
+```javascript
83
+// 上传公开Logo
84
+uploadFile(file, {bucketType: 'public'}).then(url => {
85
+ // 获取的url可直接用于<img>标签src
86
+});
87
+
88
+// 上传用户私有文档
89
+uploadFile(file, {bucketType: 'private'}).then(url => {
90
+ // 此url通常无法直接访问，需通过后端有权限校验的接口代理访问或生成临时签名URL
91
+});
92
+```
93
+
94
+## 5. 使用场景总结
95
+
96
+| 场景 | 存储桶类型 | 配置版本 | 后端使用接口 | 前端上传参数 | 特点 |
97
+| :--- | :--- | :--- | :--- | :--- | :--- |
98
+| **历史存量业务** | 公有桶 | V1 (默认) | `getBucket()` | 无要求，按原逻辑 | 完全兼容，零成本迁移。 |
99
+| **新业务-敏感数据** <br>(用户数据、交易记录) | **私有桶** | V2 | `getBucket()` | `bucketType: ‘private’` | 数据安全，外网不可直接访问。 |
100
+| **新业务-公开资源** <br>(Logo、帮助文档、宣传图) | **公有桶** | V2 | `getIIDPBucket()` | `bucketType: ‘public’` | 访问高效，可直接通过URL访问。 |
101
+
102
+## 6. 实施步骤建议
103
+
104
+1. **评估与规划**：梳理现有业务数据，明确哪些应迁至私有桶，哪些可留在公有桶。
105
+2. **配置升级**：在应用配置中，将 `minio.bucket.edition` 设置为 `v2`，并设置 `minio.iidpBucket` 名称。
106
+3. **Minio服务端准备**：确保Minio服务中已创建 `iidp-bucket` 桶，并检查 `apps` 桶的访问策略是否符合私有要求。
107
+4. **后端代码更新**：对于**新业务逻辑**或需要存储公开资源的**存量业务**，将对应代码中的存储客户端获取方式改为 `getIIDPBucket()`。
108
+5. **前端代码更新**：改造文件上传组件，支持传递 `bucketType` 参数。
109
+6. **测试与验证**：全面测试V2模式下公有、私有桶的上传、访问（直接访问和签名URL访问）功能，并验证V1兼容模式仍正常工作。
110
+
111
+---
112
+**文档版本：V1.0**
113
+
114
+--
115
+--
116
+
1 117
### 业务和公共分桶方案
2 118
3 119
#### 现状分析