hzdyjs/docs/开发文档/图片上传组件安全改造说明.md

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

📋 概述

为了配合MinIO安全改造，图片上传组件 ImageUpload/index.vue 已经进行了安全升级，支持bucket密码验证和预签名URL机制。

🔧 主要改动

1. 新增安全功能

• ✅ Bucket密码验证: 支持在文件上传时验证bucket访问密码
• ✅ 自定义上传: 使用 :http-request="customUpload" 替代默认上传
• ✅ 密码输入对话框: 当需要密码验证时，弹出密码输入界面
• ✅ 安全预览: 文件预览时使用安全机制

2. 新增Props参数

interface Props {
  // ... 原有参数 ...
  
  // bucket访问密码
  bucketPassword?: string;
  
  // 是否启用bucket密码验证
  enablePasswordValidation?: boolean;
}

🚀 使用方法

基础用法（不启用密码验证）

<template>
  <ImageUpload 
    v-model="imageList"
    :limit="5"
    :file-size="10"
    :file-type="['png', 'jpg', 'jpeg']"
  />
</template>

启用密码验证

<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>

动态密码验证

<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 为空时
• 用户选择文件后，弹出密码输入对话框
• 用户输入密码后，组件验证密码并执行上传

📝 上传接口变更

原有接口

// 直接上传到 /resource/oss/upload
const uploadImgUrl = baseUrl + '/resource/oss/upload'

新安全接口

// 使用自定义上传方法
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
  })
  
  // 处理响应...
}

🎯 预览功能升级

安全预览

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 属性或对话框输入

示例迁移

<!-- 旧版本 -->
<ImageUpload v-model="images" />

<!-- 新版本（启用密码验证） -->
<ImageUpload 
  v-model="images" 
  :enable-password-validation="true"
  :bucket-password="bucketPassword"
/>

🧪 测试建议

1. 功能测试

• 基础文件上传功能正常
• 密码验证功能正常
• 密码错误时提示正确
• 预览功能正常
• 删除功能正常

2. 安全测试

• 无密码时无法上传
• 错误密码时无法上传
• 密码验证失败时提示正确
• 密码不会在控制台泄露

3. 兼容性测试

• 不启用密码验证时功能正常
• 原有页面无需修改即可使用
• 文件格式限制正常
• 文件大小限制正常

📚 相关文档

• MinIO安全改造方案
• Bucket密码管理API
• 文件访问安全API

---

更新时间: 2025-01-27
版本: v2.0.0
维护者: 开发团队