📎 附件上传与存储
SunAdmin 上传链路由 Controller、Request、UploadService、StorageDriverManager 和存储驱动组成。
🎯 本页目标
读完本章节后，应能掌握：
- Admin 与用户端的上传接口分别是什么、需要带哪些校验参数。
- 本地存储、七牛、阿里云 OSS、腾讯云 COS 在配置和切换上的差异。
- 媒体 URL 在保存与读取阶段如何在相对路径与完整 URL 之间自动转换。
- 上传相关的大小、扩展名、富文本资源的统一处理边界。
⬆️ 上传接口
Admin：
text
POST /adminapi/system/upload/file用户端：
text
POST /api/system/upload/file
GET /api/system/upload/validate⭐ 上传配置
配置位置：
text
config/sunadmin.php支持的上传类型：
| type | 扩展名 | 大小 |
|---|---|---|
image | jpg、jpeg、png、gif、bmp、webp、svg | 5MB |
video | mp4、mov、avi、wmv、mkv、webm | 50MB |
file | pdf、doc、docx、xls、xlsx、ppt、pptx、zip、rar、txt、md | 20MB |
🧱 上传服务
核心文件：
text
modules/System/Application/Services/File/UploadService.php主要流程：
- 根据
type读取上传配置。 - 校验扩展名和大小。
- 通过
StorageDriverManager解析存储驱动。 - 生成
uploads/{type}/{Ymd}/{His}{random}.{ext}路径。 - 调用驱动写入物理文件。
- 写入文件表。
- 返回文件 ID、URL、扩展名、大小等信息。
返回字段：
| 字段 | 说明 |
|---|---|
id | 文件记录 ID |
cid | 分类 ID |
type | 文件类型枚举 |
name | 原始文件名 |
uri | 文件地址 |
url | 与 uri 保持一致，方便前端 |
ext | 扩展名 |
mime | MIME |
size | 文件大小 |
module | 业务模块 |
tag | 业务标签 |
💾 存储驱动
管理器：
text
modules/System/Application/Services/File/StorageDriverManager.php支持驱动：
| engine | 驱动 |
|---|---|
local | 本地存储 |
qiniu | 七牛云 |
aliyun | 阿里云 OSS |
qcloud | 腾讯云 COS |
默认存储引擎从后台配置读取：
php
$this->configService->getValue('storage', 'default', 'local')云存储必填项：
| engine | 必填 |
|---|---|
qiniu | bucket、access_key、secret_key、domain |
aliyun | bucket、access_key、secret_key、domain |
qcloud | bucket、region、access_key、secret_key、domain |
🔁 媒体 URL 转换
转换器：
text
app/Support/File/MediaUrlTransformer.php职责：
- API 输出时把本地相对路径补成完整 URL。
- 保存时把本站完整 URL 还原为相对路径，第三方存储会保留完整URL。
- 富文本中只处理
src、href、poster资源属性。 - data、blob、javascript、mailto、tel、锚点等特殊协议不处理。
🏠 本地存储注意事项
本地存储需要执行以下命令确保已经初始化本地存储目录映射（通过安装向导初始化会自动处理，无需手工操作）：
bash
# 创建 public/storage 到 storage/app/public 的公开访问软链接
php artisan storage:link并确保以下目录可写：
text
storage/
public/storage/🤳 前端上传注意事项
Admin 上传走后台 token，接口前缀为 adminapi。
uni-app 上传走用户端接口。小程序/App 必须配置完整 VITE_APP_BASE_URL，否则上传 URL 无法拼成合法请求地址。
📌 安全建议
- 不允许上传未配置扩展名。
- 不使用原始文件名作为物理文件名。
- 原始文件名最长保留 100 个字符。
- 云存储 URL 不做反向相对路径替换。
- 富文本保存时只还原本站资源 URL，外链保持原样。