文件上传

当你需要上传头像、导入文件、或对接对象存储（MinIO/OSS）时，从这篇开始。

youlai-django 提供统一的文件上传接口，前端仅需关心 url 返回值即可。本文涵盖：

• 存储方式配置与常用参数
• 上传/删除接口与响应结构
• MinIO 常见问题与排查

存储方式

通过 .env 中的 OSS_TYPE 配置切换：

存储类型	配置值	说明
本地存储	local	存储在服务器本地文件系统
MinIO	minio	开源对象存储服务
阿里云 OSS	aliyun	阿里云对象存储服务

说明：当前代码实现中已提供 MinIO 相关服务（apps/file/file/services.py），其他存储方式可按同一接口扩展。

接口说明

上传接口

POST /api/v1/files
Content-Type: multipart/form-data

参数	类型	必填	说明
file	File	是	表单文件对象

响应结构：

{
  "code": "00000",
  "msg": "成功",
  "data": {
    "name": "原始文件名.png",
    "url": "http://127.0.0.1:9000/public/xx/yy/xxx__token__原始文件名.png"
  }
}

删除接口

DELETE /api/v1/files?filePath={urlOrPath}

参数	类型	必填	说明
filePath	String	是	文件 URL 或对象存储路径（服务端会解析）

响应结构：

{
  "code": "00000",
  "msg": "成功",
  "data": null
}

配置说明（.env）

MinIO

OSS_TYPE=minio

MINIO_HOST_PORT=http://127.0.0.1:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=public
MINIO_SSL=false

# 是否在返回的 url 中写入自定义域名（可选）
MINIO_SAVE_FILE_PREFIX_DOMAIN=true
MINIO_CUSTOM_DOMAIN=https://www.youlai.tech/storage

代码位置

• 路由：apps/file/file/urls.py
• 视图：apps/file/file/views.py
• 存储服务（MinIO）：apps/file/file/services.py

常见问题

1) 上传失败 / 500

• 检查 MinIO 地址与凭据是否正确（MINIO_HOST_PORT / MINIO_ACCESS_KEY / MINIO_SECRET_KEY）
• 确认 MINIO_BUCKET_NAME 存储桶存在或允许创建

2) 返回的 URL 无法访问

• 如果你在容器中运行 MinIO，确认端口映射是否正确
• 如需外网域名访问，配置 MINIO_CUSTOM_DOMAIN 并确保反向代理/证书生效