# 图片上传组件安全改造说明

## 📋 概述

为了配合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  
**维护者**: 开发团队