文件管理

file

功能概述

文件管理用来管系统中的文件资源,支持上传、分组、图片预览、WebP 转换和压缩。上传图片时会自动检测是不是有效图片;默认会压缩尺寸并转成 WebP 格式省空间(KeepOriginalFile=true 时非 WebP 原图直接保留,不转换也不缩放;已是 WebP 的图片超过最大宽度时仍会缩放重编码)。开了多租户的话,文件按租户编码分目录存,各租户的文件互不干扰。

使用方法

进入文件管理页面

导航里找到 "系统管理" → "文件管理" 点进去。

上传文件

  1. 点 "上传" 按钮或者直接把文件拖到 CardUpload 区域。
  2. 可以选个文件分组(默认按日期自动归档)。
  3. 系统会自动验文件类型(配置里设了允许/禁止的扩展名)和大小(默认 10MB)。
  4. 上传成功,文件信息自动出现在列表里。

查看和管理文件

  • 列表展示:文件名、大小、类型、上传时间。
  • 图片预览:鼠标悬停或点一下就能预览。
  • 分组筛选:左边分组树点一下,就只看那个分组的文件。
  • 删除:勾选后点 "删除"。

文件分组

  • 系统默认按日期自动分组(配置 FileSettings:DateTimeDirectory,默认 yyyy/MM/dd)。
  • 上传时也可以手动选分组。
  • 左侧树形分组导航,点一下就能快速切换。

图片处理

上传的图片会自动走一遍流程:

  1. 格式验证:用 SkiaSharp 检测是不是有效图片
  2. 尺寸压缩:超过配置的最大宽度时自动缩(KeepOriginalFile=true 且原图不是 WebP 时跳过;WebP 原图超宽仍会缩放)
  3. 格式转换:默认自动转成 WebP;KeepOriginalFile=true 时非 WebP 原图保留原格式,不生成 WebP

多租户文件隔离

多租户启用时,文件存储路径自动加上租户 code 前缀:wwwroot/uploads/{tenantCode}/yyyy/MM/dd/。

界面说明

左侧分组树

  • 显示所有文件分组目录
  • 点击切换文件列表过滤

上传区域

  • CardUpload 卡片上传组件
  • 支持拖拽上传和点击选择
  • 自动显示上传进度

文件列表

  • 文件名:原始文件名称(含图标标识文件类型)
  • 大小:格式化后的文件大小
  • 目录:存储路径
  • 操作列:预览、删除

文件访问地址

文件统一通过 LinkUrl 指向的静态地址访问(SysFile.AccessUrl 与之相同),框架不提供额外的受控下载接口 —— 也就是说,上传目录本身是对外可访问的静态资源目录。

需要控制文件可见性时,请通过 Web 服务器 / 网关层限制上传目录的访问(例如 Nginx location + 鉴权),而不是依赖应用层接口。

图片处理限制

  • 图片上传后默认压缩并转成 WebP;KeepOriginalFile=true 时非 WebP 原图直接保留,不生成 WebP、也不做尺寸压缩(已是 WebP 的图片超宽时仍会缩放重编码)。
  • FileSettings:MaxImagePixels 限制单张图片允许的像素总数(宽 × 高,默认 4000 万,约 160MB RGBA 缓冲区),0 表示不限制。解码会一次性按 宽 × 高 × 4 字节分配内存,一张几百 KB 的高压缩 PNG 就能吃掉 2GB+ 内存,所以必须在解码前拦截。
  • 实际生成 WebP 时,转换后的文件名(xxx.webp)会做唯一性校验,与已有文件冲突时自动追加随机后缀,不会静默覆盖。

分组名称限制

分组名会经过统一路径服务校验:拒绝路径穿越(..)、盘符、UNC 与非法字符,并拒绝 Windows 保留设备名(NUL、CON、COM1 等,含 NUL.txt 这类带扩展名的写法)—— 这些名字在 Windows 上指向设备而不是目录,直接建目录会抛系统级异常。

相关实体/服务

  • SysFile — 文件实体
  • FileService — 文件上传、删除、图片处理服务
  • IConfiguration — 读取文件配置(允许扩展名、大小限制、WebP 质量、像素上限等)