文件处理

所属入口：管理 -> 系统设置 -> 文件处理。其他分组和生效时机见系统设置。

这一组控制会读取、扫描、转换或临时展开文件内容的能力。默认规则：

项目	默认值
在线解压源压缩包大小上限	`512 MiB`
在线解压 staging 大小上限	`2 GiB`
在线解压展开大小上限	`1 GiB`
在线解压条目数量上限	`10000`
在线解压耗时上限	`300` 秒
在线归档压缩总开关	开启
用户侧归档下载开关	开启
分享侧归档下载开关	开启
归档构建条目数量上限	`10000`
归档构建源文件总大小上限	`2 GiB`
归档构建输出大小上限	`2 GiB`
压缩包预览总开关	关闭
压缩包预览用户侧开关	关闭
压缩包预览分享侧开关	关闭
压缩包预览源文件大小上限	`64 MiB`
压缩包预览条目数量上限	`2000`
压缩包预览 manifest 大小上限	`64 KiB`
压缩包预览扫描耗时上限	`30` 秒
链接导入引擎注册表	`builtin` 启用，`aria2` 关闭
链接导入文件大小上限	`1 GiB`
链接导入下载速度上限	`5` MB/s（`0` 仍表示不限制）
链接导入任务并发上限	`1`
链接导入请求超时	`600` 秒
aria2 RPC 请求超时	`10` 秒
aria2 split	`5`
aria2 单服务器连接数	`5`
aria2 最低速度阈值	`0`（关闭）
缩略图源文件大小上限	`64 MiB`
图片预览策略	优先原图
媒体元数据解析	开启
媒体元数据源文件大小上限	`256 MiB`

压缩包预览

压缩包预览是只读功能，只扫描支持格式的归档元数据并生成 manifest，不会把压缩包解开到用户文件夹里。它和“在线解压”不是一回事。

这一组里有三层开关：

启用压缩包预览：总开关
对用户启用压缩包预览：登录用户在个人空间和团队空间里能不能预览
对分享启用压缩包预览：公开分享页在通过密码和分享范围校验后能不能预览

默认三项都是关闭。建议只有在确实需要用户查看压缩包内部清单时再打开，尤其是分享侧开关；它会让访问者看到压缩包内部的文件名、目录结构、大小和修改时间这类元数据。

限制项控制源压缩包大小、条目数量、返回 manifest 大小和单次扫描耗时。第一次打开某个压缩包时，如果清单还没有缓存，系统会创建 archive_preview_generate 后台任务；生成完成后再次打开会直接复用缓存。

用户在预览工具栏切换 文件名编码 时，会按所选编码重新读取或生成清单。这个能力用于处理旧 ZIP 或跨语言环境生成的 ZIP 文件名乱码，不会修改原始压缩包。

在线解压和归档构建

在线解压、在线压缩和文件夹打包下载都会占用后台归档任务车道，也都会用到服务端临时目录。默认限制已经按“个人和小团队常见文件”设置，不建议一上来全部调大。

启用在线归档压缩 只控制用户能不能把选中的文件和文件夹创建成新的 ZIP 压缩包。它默认开启。关闭后，新建在线压缩任务会被拒绝；在线解压、文件夹打包下载和压缩包预览由各自配置单独控制，不会因为这个开关自动关闭。

ZIP 打包下载还有两个独立开关：

对用户启用归档下载：控制登录用户能否把个人空间或团队空间里的所选内容下载为 ZIP
对分享启用归档下载：控制公开分享访问者能否在通过密码、分享范围和下载次数校验后下载 ZIP

关闭后，服务端会拒绝新的对应 ZIP 下载请求，官方前端也会隐藏相关下载方式。两个开关彼此独立，不影响单文件直接下载，也不影响“在线归档压缩”创建新 ZIP 文件。

如果用户经常处理大压缩包或大目录，优先分别看这几项：

在线解压源压缩包大小上限：源压缩包本身太大时会直接拒绝
在线解压 staging 大小上限：按“源压缩包下载到本地 + 解压到 staging 的文件”一起算
在线解压展开大小、条目数量、路径深度、压缩比和耗时限制：用来挡压缩炸弹和异常元数据包
归档构建条目数量、源文件总大小和输出大小上限：影响批量在线压缩和文件夹打包下载

把这些限制调大前，先确认 server.temp_dir 所在磁盘、CPU 和后台归档任务并发都能承受。否则用户体验通常不是“能处理更大文件”，而是“任务排队更久或临时盘更快满”。

链接导入

链接导入会创建一个单独的后台任务车道，用来让服务端从 HTTP/HTTPS 源地址下载文件，再导入到当前工作空间。这里的运行时设置只负责限制大小、速度、并发、超时，以及选择 builtin / aria2 下载引擎。

默认值按“能直接用、不会明显打扰现有行为”来设：builtin 启用、aria2 关闭，文件大小上限 1 GiB，速度上限 5 MB/s，并发 1，请求超时 600 秒。aria2 相关参数默认只在启用 aria2 引擎后生效。

完整行为、安全边界、aria2 部署和常见问题见离线下载。

媒体处理

媒体处理这一块负责缩略图、图片预览图和媒体元数据的后端生成。它现在在 文件处理 -> 媒体处理 里有结构化编辑器，不需要手改 JSON。

你可以在那里做这些事：

开关某个处理器
给处理器绑定文件后缀
配置 vips_cli、ffmpeg_cli 或 ffprobe_cli 使用的命令
测试命令是否能被服务端执行
保留 AsterDrive 内置图片处理器作为兜底
配置生成缩略图和图片预览图的最大边长
选择网页图片预览默认先加载原图，还是先加载后端生成的中等预览图

默认内置链路覆盖常见图片格式。
如果你想给 HEIC、AVIF、PDF 封面、视频缩略图或视频元数据扩展能力，可以接 vips、ffmpeg 或 ffprobe，但前提是这些命令真的装在服务端环境里。

缩略图最大边长 和 图片预览最大边长 控制生成结果的尺寸，不控制源文件是否允许进入处理流程：

thumbnail_max_dimension 限制生成缩略图的宽度和高度，默认 400 像素。
image_preview_max_dimension 限制生成图片预览图的宽度和高度，默认 1600 像素。
两者都是最大边长限制：生成结果会保持宽高比，并保证 max(width, height) 不超过配置值。
存储原生缩略图处理器也会收到同样的尺寸，写入 NativeThumbnailRequest.max_width 和 max_height。

修改这两个值不会原地重写已有派生图。非默认尺寸会进入派生版本命名空间和 ETag，例如 1-d320 或 1-d2048，避免客户端或对象存储误用另一种尺寸生成的缓存。如果改回默认值，AsterDrive 会重新使用默认派生版本命名空间。

图片预览策略 只影响网页预览弹窗默认加载哪种图片来源：

优先原图：浏览器支持渲染当前格式时，先直接加载原图；如果浏览器不支持，或原图加载失败，再使用后端生成的预览图
优先中等预览：先加载后端生成的 WebP 预览图，用户选择查看原图时才下载原图

如果用户经常打开大照片，或者对象存储出口带宽比较敏感，可以选择“优先中等预览”。这个设置不改变原始文件，也不影响缩略图缓存；它只是改变前端预览弹窗的默认加载顺序。

首次启动时的媒体处理 ENV

服务第一次初始化系统设置时，会读取三个 bootstrap 环境变量，用来决定媒体处理默认配置里是否启用 CLI 处理器：

ASTER_BOOTSTRAP_ENABLE_VIPS_CLI=true
ASTER_BOOTSTRAP_ENABLE_FFMPEG_CLI=true
ASTER_BOOTSTRAP_ENABLE_FFPROBE_CLI=true

官方 Docker 完整镜像已经安装 vips、ffmpeg 和 ffprobe，并默认打开这三个 bootstrap ENV，所以新库通常会直接带上对应处理器。-slim / -metrics-slim 镜像不包含这些命令，并在新库中默认关闭对应处理器；已有数据库切换到 slim 镜像时会保留配置，但缺失的命令不会被公开能力接口声明为可用。镜像标签和切换注意事项见单实例 Docker 部署。

这三个变量只影响 media_processing_registry_json 还不存在时的初始默认值。这个规则表是统一媒体处理配置入口，用来管理内置 images、内置 lofty、VIPS CLI、FFmpeg CLI、FFprobe CLI 的启用状态、能力用途、后缀绑定和命令路径；缩略图和媒体元数据都会走这条链路。

媒体元数据

媒体元数据和缩略图共用 media_processing_registry_json：

media_metadata_enabled 是总开关
media_metadata_max_source_bytes 限制进入元数据后台任务的源文件大小
images 处理器启用且具备 metadata:image 用途时，负责图片元数据
lofty 处理器启用且具备 metadata:audio 用途时，负责音频元数据；具备 thumbnail:audio 用途时，负责从音频内嵌封面生成 WebP 缩略图
ffprobe_cli 处理器启用且具备 metadata:video 用途时，负责视频元数据；它的 config.command 可以是命令名或绝对路径

如果服务端的 ffprobe 改名了、没放进 PATH，或者需要指定自定义安装路径，把 media_processing_registry_json 里 ffprobe_cli.config.command 改成对应命令或绝对路径，然后在媒体处理注册表里执行 test_ffprobe_cli 探测。