文件处理
所属入口：管理 -> 系统设置 -> 文件处理。其他分组和生效时机见 系统设置。
这一组控制会读取、扫描、转换或临时展开文件内容的能力。默认规则：
| 项目 | 默认值 |
|---|---|
| 在线解压源压缩包大小上限 | 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 文件名乱码，不会修改原始压缩包。
在线解压和归档构建
Section titled “在线解压和归档构建”在线解压、在线压缩和文件夹打包下载都会占用后台归档任务车道，也都会用到服务端临时目录。默认限制已经按“个人和小团队常见文件”设置，不建议一上来全部调大。
启用在线归档压缩 只控制用户能不能把选中的文件和文件夹创建成新的 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=trueASTER_BOOTSTRAP_ENABLE_FFMPEG_CLI=trueASTER_BOOTSTRAP_ENABLE_FFPROBE_CLI=true官方 Docker 镜像已经安装 vips、ffmpeg 和 ffprobe，并默认打开这三个 bootstrap ENV，所以新库通常会直接带上对应处理器。
这三个变量只影响 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 探测。