第24章 Cloudreve 第24章：缩略图生成机制详解

# 第24章 Thumbnails Cloudreve 支持多种缩略图生成器，可处理图片、视频、Office 文档等不同类型的文件。你还可以通过“缩略图代理”功能，为原本不支持缩略图的存储策略扩展缩略图生成能力。 ## 生成逻辑 ### 何时生成 Cloudreve 不会在文件上传后立即生成缩略图，而是在用户尝试加载时才进行。本节说明 Cloudreve 何时决定加载缩略图。每个文件的缩略图状态可分为两种： - Unknown：新上传文件的默认状态。在文件列表中查看该文件时，Cloudreve 会尝试加载或生成缩略图。如果缩略图 Blob 已存在，则直接用作缩略图；如果不存在，则尝试生成一个。 - Thumbnail doesn't exist：在文件列表中查看该文件时，Cloudreve 不会显示缩略图。 以下情况会将文件的缩略图状态重置为 Unknown： - 文件被重命名且扩展名发生变化； - 文件内容被更新。 以下情况会将文件的缩略图状态重置为 Thumbnail doesn't exist： - 找不到可用的缩略图生成器； - 生成器生成缩略图失败。 ### 如何生成 本节说明 Cloudreve 如何为文件生成缩略图。Cloudreve 支持多个缩略图生成器，并采用“流水线”机制，按顺序依次尝试每个生成器，直到某个成功返回缩略图为止。目前支持的生成器及其顺序如下表所示： | 生成器 | 说明 | 不支持的存储策略 | 优先级（从高到低） | |---|---|---|---| | 存储策略原生 | 使用第三方存储策略的原生能力生成缩略图。不会产生缩略图 Blob，只生成一个用于重定向的 URL。 | 本地存储、S3 | 1 | | Music Cover | 无第三方依赖，内置于 Cloudreve。可从 MP3 (ID3v1, 2.x)、MP4 (ACC, M4A, ALAC)、OGG 或 FLAC 中提取专辑封面。该生成器依赖任意其他图片生成器（Cloudreve 内置或 VIPS）来压缩提取出的封面图。当源文件位于第三方存储时，会尝试通过 Range 请求只下载所需部分，而无需下载整个文件。 | 除本地存储外所有未开启“生成器代理”的存储策略 | 2 | | LibreOffice | 使用 LibreOffice 为 Office 文档生成缩略图。该生成器依赖任意其他图片生成器（Cloudreve 内置或 VIPS）。当源文件位于第三方存储时，会下载整个源文件。 | 除本地存储外所有未开启“生成器代理”的存储策略 | 3 | | LibrRaw | 使用 LibRAW 为 RAW 文件生成缩略图。该生成器依赖任意其他图片生成器（Cloudreve 内置或 VIPS）。当源文件位于第三方存储时，会下载整个源文件。 | 除本地存储外所有未开启“生成器代理”的存储策略 | 4 | | VIPS | 使用 libvips 处理缩略图，支持更多图片格式，资源消耗更低。当源文件位于第三方存储时，会下载整个源文件。 | 除本地存储外所有未开启“生成器代理”的存储策略 | 5 | | FFmpeg | 使用 FFmpeg 生成视频缩略图。当源文件位于第三方存储时，会尝试通过 Range 请求只下载所需部分，而无需下载整个文件。 | 除本地存储外所有未开启“生成器代理”的存储策略 | 6 | | Cloudreve 内置 | 无第三方依赖，使用 Cloudreve 内置的图片处理能力，仅支持 PNG、JPEG 和 GIF 格式。当源文件位于第三方存储时，会下载整个源文件。 | 除本地存储外所有未开启“生成器代理”的存储策略 | 7 | 各生成器的详细说明见后续章节。 ## 代理缩略图生成 默认情况下，所有非原生存储策略只支持使用存储策略原生生成器，这种方式速度最快，但支持的文件格式有限，有些存储策略（如 S3）甚至完全不支持缩略图生成。你可以在 存储策略设置 -> Thumbnails -> 代理缩略图生成 中开启此功能。开启后，如果原生生成器生成缩略图失败，Cloudreve 会尝试使用已配置的生成器流水线，并将生成的缩略图上传回存储策略。 ## 生成器 ### 存储策略原生 使用存储策略的原生图片处理服务生成缩略图。你可以在 存储策略设置 -> Thumbnails 中设置适用的文件扩展名和大小限制。不同存储服务商支持的文件格式不同，请参阅存储服务商的文档。

TIP
对于远程存储策略，可参考“原生缩略图”一节来扩展原生缩略图能力。

### Music Cover 无需第三方库。可从 MP3 (ID3v1, 2.x)、MP4 (ACC, M4A, ALAC)、OGG 或 FLAC 中提取专辑封面。依赖任意其他支持图片的生成器（VIPS 或 Cloudreve 原生）。 ### LibreOffice 主页：https://www.libreoffice.org/discover/libreoffice/ 该生成器可为 Office 文档创建缩略图，依赖任意其他支持图片的生成器（VIPS 或 Cloudreve 原生）。 在 Ubuntu 上安装 LibreOffice： ```sh sudo apt install libreoffice ``` ### LibrRaw 主页：https://libraw.org/ Cloudreve 使用 LibRAW 中的 simple_dcraw 工具生成缩略图。在 Ubuntu 上： ```sh sudo apt install libraw-bin # 查找 simple_dcraw 的路径 sudo find / -name "simple_dcraw" # 输出示例： # /usr/lib/libraw/simple_dcraw ``` 然后在 设置 -> 媒体处理 -> Thumbnails 中启用 LibrRaw/DCRaw 生成器，并在 Executable 中填入 simple_dcraw 的路径。 Windows 和 macOS 用户可从 LibRAW Download 下载预编译的 simple_dcraw 工具。 其他 Linux 发行版如果软件包管理器没有提供 libraw-bin 包，则需要自行编译。

TIP
你也可以使用 DCRaw 工具生成缩略图，但需手动将 Executable 配置为 dcraw。注意在测试可执行文件时会报错，但缩略图生成器仍可正常工作。

### VIPS 主页：https://www.libvips.org/ 在 Ubuntu 上： ```sh sudo apt install libvips-tools ``` Cloudreve 仅支持 libvips 8.5 及以上版本。可用以下命令查看已安装的版本： ```sh vips -v ``` 部分较旧的发行版软件源可能没有最新版的 libvips，建议从源码编译安装最新版本：https://www.libvips.org/install.html ### FFMpeg 主页：https://ffmpeg.org 在 Ubuntu 上： ```shell sudo apt install ffmpeg ``` ### Cloudreve 内置 可直接为常见图片格式（PNG、JPEG、GIF）生成缩略图。 ## 排查缩略图不显示的问题 如果已配置了相应的缩略图生成器，但缩略图仍然不显示，请按本节步骤逐一排查。 ### 确认缩略图状态 确认该文件的缩略图状态是否被标记为 Thumbnail doesn't exist。在管理后台找到该文件，检查其 Metadata 中是否存在 thumb:disabled： - 如果存在，说明之前的缩略图生成失败，导致该文件被标记为 Thumbnail doesn't exist。你可以删除 thumb:disabled 元数据，或将文件重命名为其他扩展名再改回来，以重置缩略图状态。 - 重置后，刷新浏览器页面（而不只是刷新文件列表），看缩略图是否出现。 ### 确认是否使用了原生缩略图生成器 进入该文件所在存储策略的设置，查看 Thumbnails 下的原生缩略图设置，核对该文件的扩展名和大小是否符合原生缩略图的条件： - 如果符合条件，说明正在使用原生缩略图生成器，但缩略图仍不显示。此时应检查存储服务商的配置：例如对应的图片处理服务是否已开启，或存储服务商是否真的支持该文件格式。 - 如果不符合条件，检查生成器代理是否已开启： - 未开启：由于没有可用的生成器，缩略图不显示属于预期行为； - 已开启：前往 设置 -> 媒体处理 -> Thumbnails，检查是否有能处理该文件的生成器。如果没有，说明没有可用生成器，缩略图不显示属于预期行为；如果有，则继续后续排查步骤。 ### 检查缩略图生成器 缩略图生成器可能因各种原因无法正常工作。进入管理后台的事件列表，筛选“缩略图生成”类型的事件，找到对应文件的缩略图生成事件，查看其中记录的错误信息：

TIP
你也可以开启 Debug 模式后再次触发缩略图生成，以查看 Cloudreve 的日志输出。

### 检查缩略图 Blob 如果缩略图生成器工作正常但缩略图仍不显示，检查缩略图 Blob 是否存在。查看文件详情，在“数据”下会显示缩略图 Blob 的大小。如果缩略图 Blob 存在，问题可能出在存储策略上，导致缩略图无法加载。请参阅对应存储策略的文档排查文件下载问题。 ## 生成队列 所有非原生缩略图生成请求都通过队列管理。你可以在管理后台的 设置 -> 队列 -> 缩略图生成 中设置队列参数。缩略图队列任务不会被持久化，因此无法在后台任务列表中找到。 ## 常见问题 ### LibreOffice 生成的缩略图有的成功有的失败 这是一个已知问题：LibreOffice 在同时生成多张缩略图时有时会启动失败。你可以将缩略图队列的工作线程数调整为 1-2，避免同时生成过多缩略图。 ### 缩略图何时会占用用户的存储容量？ 使用非原生生成器生成的缩略图会存放在缩略图 Blob 中，计入用户的存储容量。存储策略原生缩略图不占用用户容量。 ### 如何重新触发文件缩略图生成？ 右键点击文件，选择 更多操作 -> 重置损坏的缩略图。