215 lines
5.0 KiB
Markdown
215 lines
5.0 KiB
Markdown
# 图片上传组件安全改造说明
|
||
|
||
## 📋 概述
|
||
|
||
为了配合MinIO安全改造，图片上传组件 `ImageUpload/index.vue` 已经进行了安全升级，支持bucket密码验证和预签名URL机制。
|
||
|
||
## 🔧 主要改动
|
||
|
||
### 1. 新增安全功能
|
||
- ✅ **Bucket密码验证**: 支持在文件上传时验证bucket访问密码
|
||
- ✅ **自定义上传**: 使用 `:http-request="customUpload"` 替代默认上传
|
||
- ✅ **密码输入对话框**: 当需要密码验证时，弹出密码输入界面
|
||
- ✅ **安全预览**: 文件预览时使用安全机制
|
||
|
||
### 2. 新增Props参数
|
||
|
||
```typescript
|
||
interface Props {
|
||
// ... 原有参数 ...
|
||
|
||
// bucket访问密码
|
||
bucketPassword?: string;
|
||
|
||
// 是否启用bucket密码验证
|
||
enablePasswordValidation?: boolean;
|
||
}
|
||
```
|
||
|
||
## 🚀 使用方法
|
||
|
||
### 基础用法（不启用密码验证）
|
||
|
||
```vue
|
||
<template>
|
||
<ImageUpload
|
||
v-model="imageList"
|
||
:limit="5"
|
||
:file-size="10"
|
||
:file-type="['png', 'jpg', 'jpeg']"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
### 启用密码验证
|
||
|
||
```vue
|
||
<template>
|
||
<ImageUpload
|
||
v-model="imageList"
|
||
:limit="5"
|
||
:file-size="10"
|
||
:file-type="['png', 'jpg', 'jpeg']"
|
||
:enable-password-validation="true"
|
||
:bucket-password="bucketPassword"
|
||
/>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref } from 'vue'
|
||
|
||
const imageList = ref([])
|
||
const bucketPassword = ref('your_bucket_password')
|
||
</script>
|
||
```
|
||
|
||
### 动态密码验证
|
||
|
||
```vue
|
||
<template>
|
||
<ImageUpload
|
||
v-model="imageList"
|
||
:limit="5"
|
||
:file-size="10"
|
||
:file-type="['png', 'jpg', 'jpeg']"
|
||
:enable-password-validation="true"
|
||
/>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref } from 'vue'
|
||
|
||
const imageList = ref([])
|
||
// 不传入bucketPassword，组件会自动弹出密码输入对话框
|
||
</script>
|
||
```
|
||
|
||
## 🔐 密码验证流程
|
||
|
||
### 1. 自动密码验证
|
||
- 当 `enablePasswordValidation=true` 且 `bucketPassword` 有值时
|
||
- 组件会自动在请求头中添加 `bucket-password` 参数
|
||
- 后端验证密码后允许上传
|
||
|
||
### 2. 手动密码验证
|
||
- 当 `enablePasswordValidation=true` 且 `bucketPassword` 为空时
|
||
- 用户选择文件后，弹出密码输入对话框
|
||
- 用户输入密码后，组件验证密码并执行上传
|
||
|
||
## 📝 上传接口变更
|
||
|
||
### 原有接口
|
||
```javascript
|
||
// 直接上传到 /resource/oss/upload
|
||
const uploadImgUrl = baseUrl + '/resource/oss/upload'
|
||
```
|
||
|
||
### 新安全接口
|
||
```javascript
|
||
// 使用自定义上传方法
|
||
const customUpload = async (options) => {
|
||
const formData = new FormData()
|
||
formData.append('file', options.file)
|
||
|
||
const response = await fetch(uploadImgUrl.value, {
|
||
method: 'POST',
|
||
headers: {
|
||
...headers.value,
|
||
'bucket-password': bucketPassword || passwordForm.bucketPassword || ''
|
||
},
|
||
body: formData
|
||
})
|
||
|
||
// 处理响应...
|
||
}
|
||
```
|
||
|
||
## 🎯 预览功能升级
|
||
|
||
### 安全预览
|
||
```javascript
|
||
const handlePictureCardPreview = async (file) => {
|
||
try {
|
||
if (file.ossId) {
|
||
// 使用安全预览机制
|
||
dialogImageUrl.value = file.url // 简化处理，实际应调用安全预览API
|
||
} else {
|
||
// 直接使用URL预览
|
||
dialogImageUrl.value = file.url
|
||
}
|
||
dialogVisible.value = true
|
||
} catch (error) {
|
||
console.error('预览失败:', error)
|
||
proxy?.$modal.msgError('预览失败')
|
||
}
|
||
}
|
||
```
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 后端接口要求
|
||
- 上传接口需要支持 `bucket-password` 请求头
|
||
- 需要验证bucket密码的有效性
|
||
- 返回标准的响应格式：`{ code: 200, data: { fileName, url, ossId } }`
|
||
|
||
### 2. 密码安全
|
||
- 密码不会在组件中明文存储
|
||
- 密码验证失败时会提示用户重新输入
|
||
- 建议使用强密码并定期更换
|
||
|
||
### 3. 兼容性
|
||
- 组件保持向后兼容，不启用密码验证时行为不变
|
||
- 原有的文件上传、预览、删除功能正常工作
|
||
|
||
## 🔄 迁移指南
|
||
|
||
### 从旧版本迁移
|
||
1. **不启用密码验证**: 无需修改，组件自动兼容
|
||
2. **启用密码验证**: 添加 `enable-password-validation="true"` 属性
|
||
3. **提供密码**: 通过 `bucket-password` 属性或对话框输入
|
||
|
||
### 示例迁移
|
||
```vue
|
||
<!-- 旧版本 -->
|
||
<ImageUpload v-model="images" />
|
||
|
||
<!-- 新版本（启用密码验证） -->
|
||
<ImageUpload
|
||
v-model="images"
|
||
:enable-password-validation="true"
|
||
:bucket-password="bucketPassword"
|
||
/>
|
||
```
|
||
|
||
## 🧪 测试建议
|
||
|
||
### 1. 功能测试
|
||
- [ ] 基础文件上传功能正常
|
||
- [ ] 密码验证功能正常
|
||
- [ ] 密码错误时提示正确
|
||
- [ ] 预览功能正常
|
||
- [ ] 删除功能正常
|
||
|
||
### 2. 安全测试
|
||
- [ ] 无密码时无法上传
|
||
- [ ] 错误密码时无法上传
|
||
- [ ] 密码验证失败时提示正确
|
||
- [ ] 密码不会在控制台泄露
|
||
|
||
### 3. 兼容性测试
|
||
- [ ] 不启用密码验证时功能正常
|
||
- [ ] 原有页面无需修改即可使用
|
||
- [ ] 文件格式限制正常
|
||
- [ ] 文件大小限制正常
|
||
|
||
## 📚 相关文档
|
||
|
||
- [MinIO安全改造方案](../中间件配置/minio-security-solution.md)
|
||
- [Bucket密码管理API](../API/用户认证登录API.md)
|
||
- [文件访问安全API](../API/API文档基础规范.md)
|
||
|
||
---
|
||
|
||
**更新时间**: 2025-01-27
|
||
**版本**: v2.0.0
|
||
**维护者**: 开发团队 |