Thumbnail Server 是 Seafile 的缩略图服务，可为图片、PDF、视频等文件生成缩略图。服务采用任务队列架构，分别处理不同类型的文件：
-
图片队列 ：处理速度较快的图片文件。
-
PDF 队列 ：处理 PDF 文件。
-
视频队列 ：处理耗时较长的视频文件。
通过分离处理队列，缩略图服务可以根据文件类型分配资源，提高并发处理能力。启用后，需由 Caddy 或其他反向代理将
/thumbnail/
请求转发至缩略图服务器。
缩略图服务在 Seafile 社区版和专业版中的功能相同，支持 Seafile 14.0 和 13.0。
单节点 Docker 部署
以下以 Seafile 默认 Docker 部署目录
/opt/seafile
为例。请确保 Seafile 已经安装并可以正常访问。
1. 下载配置文件
进入 Seafile 的 Docker Compose 配置目录：
cd /opt/seafile
Seafile 14.0：
wget https://manual.seafile.com/14.0/repo/docker/thumbnail-server.yml
Seafile 13.0：
wget https://manual.seafile.com/13.0/repo/docker/thumbnail-server.yml
2. 启用 Docker Compose 服务
编辑
/opt/seafile/.env
，将
thumbnail-server.yml
加入
COMPOSE_FILE
：
COMPOSE_FILE='seafile-server.yml,caddy.yml,seadoc.yml,thumbnail-server.yml'
上面仅为示例。
应保留原有的全部 Compose 文件
，只添加
thumbnail-server.yml
，不要移除已有的 SeaDoc、Notification Server、SeaSearch 或其他组件配置。如果采用外部反向代理，也不要为了照搬示例重新添加
caddy.yml
。
3. 启用缩略图功能
编辑 Seafile 的
seahub_settings.py
。默认 Docker 部署中，该文件位于：
/opt/seafile-data/seafile/conf/seahub_settings.py
Seafile 14.0：
ENABLE_THUMBNAIL_SERVER = True
该配置用于启用独立的缩略图服务器，默认关闭。
Seafile 13.0：
如果需要启用视频缩略图，在
seahub_settings.py
中添加：
ENABLE_VIDEO_THUMBNAIL = True
此项是 Seafile 13.0 所使用的视频缩略图配置；不要将它当作 Seafile 14.0 的
ENABLE_THUMBNAIL_SERVER
的直接替代项。
4. 启动服务
在
/opt/seafile
目录执行：
docker compose config --quiet
docker compose down
docker compose up -d
docker compose down
会中断现有服务，请在合适的维护窗口执行；不会删除正常配置的持久化数据卷。
检查容器状态和日志：
docker compose ps
docker logs -f thumbnail-server
默认 Caddy 代理已在缩略图服务的 Compose 文件中提供
/thumbnail/
转发规则。启用 HTTPS 后，可以尝试访问：
https://seafile.example.com/thumbnail/ping
请将域名替换为实际地址。此请求可用于检查反向代理是否能够访问缩略图服务；完整验证还应在 Seafile 网页端打开图片、PDF 或视频并查看缩略图是否生成。
集群或独立部署
集群部署可以把缩略图服务部署在某个节点，也可以部署在独立服务器上。负载均衡器需要通过
HTTP
将
/thumbnail/
请求转发到缩略图服务器。
在单独机器上运行缩略图服务器前，应确保它可以访问 Seafile 数据库、Seahub 服务以及相关存储后端。
1. 下载独立部署文件
建议使用独立目录，例如
/opt/thumbnail-server
：
mkdir -p /opt/thumbnail-server
cd /opt/thumbnail-server
Seafile 14.0：
wget https://manual.seafile.com/14.0/repo/docker/thumbnail-server/thumbnail-server.yml
wget -O .env https://manual.seafile.com/14.0/repo/docker/thumbnail-server/env
Seafile 13.0：
wget https://manual.seafile.com/13.0/repo/docker/thumbnail-server/thumbnail-server.yml
wget -O .env https://manual.seafile.com/13.0/repo/docker/thumbnail-server/env
独立部署与单节点集成部署使用的
thumbnail-server.yml
不是同一个路径下的模板
，不要混用。
2. 修改
.env
按照实际环境配置
.env
。主要参数如下：
变量名
说明
SEAFILE_VOLUME
缩略图服务器的数据持久化目录，默认
/opt/seafile-data
。
SEAFILE_MYSQL_DB_HOST
Seafile 数据库的主机地址。
SEAFILE_MYSQL_DB_PORT
数据库端口，通常为
3306
。
SEAFILE_MYSQL_DB_USER
数据库用户名，通常为
seafile
。
SEAFILE_MYSQL_DB_PASSWORD
数据库用户密码。
TIME_ZONE
时区，如
Asia/Shanghai
。
JWT_PRIVATE_KEY
与 Seafile 服务器使用的 JWT 密钥保持一致。
INNER_SEAHUB_SERVICE_URL
缩略图服务器访问 Seahub 的地址，用于验证访问权限。
SEAF_SERVER_STORAGE_TYPE
存储后端类型：
disk
、
s3
、
multiple
；也可不设置，改由
seafile.conf
中的配置确定。
NON_ROOT
是否以非 root 用户运行容器。
使用 S3 时，还需根据存储服务填写以下变量：
变量名
说明
S3_COMMIT_BUCKET
commit 对象的 S3 存储桶。
S3_FS_BUCKET
fs 对象的 S3 存储桶。
S3_BLOCK_BUCKET
block 对象的 S3 存储桶。
S3_KEY_ID
S3 访问密钥 ID。
S3_SECRET_KEY
S3 访问密钥。
S3_AWS_REGION
S3 所在区域。
S3_HOST
非 AWS S3 或自建 S3 的访问端点。
S3_USE_HTTPS
是否通过 HTTPS 访问 S3。
S3_USE_V4_SIGNATURE
是否使用 S3 V4 签名。
S3_PATH_STYLE_REQUEST
是否使用路径风格的 S3 URL，自建 S3 服务常需要启用。
S3_SSE_C_KEY
使用 SSE-C 加密时的密钥；启用时需配合 HTTPS 和 V4 签名。
INNER_SEAHUB_SERVICE_URL
缩略图服务器需要调用 Seahub 校验权限，因此该地址必须能从
缩略图服务器所在节点
访问。通常建议使用某个前端节点的内网地址，例如：
INNER_SEAHUB_SERVICE_URL=http://192.168.0.10
也可以使用外部 HTTPS 地址：
INNER_SEAHUB_SERVICE_URL=https://seafile.example.com
如使用 HTTPS，需要保证缩略图服务器信任该站点的 CA 证书。
3. 配置存储访问
缩略图服务器必须能够访问 Seafile 的文件数据，否则即使服务已启动，也无法正常生成缩略图。
单一 S3 存储
在缩略图服务器的
.env
中设置：
SEAF_SERVER_STORAGE_TYPE=s3
并填写与 Seafile 服务器相匹配的 S3 存储桶、端点和凭据，确保缩略图服务器可以读取对象。
多存储后端
在
.env
中设置：
SEAF_SERVER_STORAGE_TYPE=multiple
同时将 Seafile 节点的
seafile.conf
复制到缩略图节点相应配置目录。例如在使用默认数据卷目录时：
/opt/seafile-data/seafile/conf/seafile.conf
Ceph、Swift 等存储后端
可不设置
SEAF_SERVER_STORAGE_TYPE
，在
seafile.conf
中配置相应后端，并确保缩略图容器能够访问所需的配置文件及存储服务。
本地磁盘存储
若独立部署在另一台机器，缩略图服务器无法直接读取 Seafile 节点的本地文件。只有先将数据通过共享存储等方式正确挂载，并确认缩略图容器能够读取实际数据，才具备使用条件。对于完全独立的跨主机部署，不应仅设置
SEAF_SERVER_STORAGE_TYPE=disk
就认为数据已经可用。
4. 启动独立缩略图服务器
cd /opt/thumbnail-server
docker compose config --quiet
docker compose up -d
docker compose ps
查看日志：
docker logs -f thumbnail-server
Seafile 服务器侧还应按照前文的版本说明启用对应缩略图功能，并让反向代理转发缩略图请求。
5. 配置负载均衡器
独立部署时，负载均衡器需要转发
/thumbnail/
下的 HTTP 请求。以下示例中的 IP 和端口仅为示例，请替换为实际地址。
Nginx
在 Nginx 的
http
上下文中定义缩略图上游服务器（也可根据实际情况配置多个节点）：
upstream thumbnail_backend {
server 192.168.0.9:80;
}
在现有 Seafile 站点的
server
配置块中添加：
location ^~ /thumbnail/ {
proxy_pass http://thumbnail_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering on;
proxy_buffer_size 4k;
proxy_buffers 8 4k;
proxy_busy_buffers_size 8k;
proxy_connect_timeout 30s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
}
修改后检查并重新加载配置：
sudo nginx -t
sudo systemctl reload nginx
HAProxy
使用 HAProxy 2.0 或更高版本时，可在现有
/etc/haproxy/haproxy.cfg
的相应配置段中增加以下规则：
frontend seafile
bind 0.0.0.0:80
mode http
option httplog
option dontlognull
option forwardfor
acl thumbnail_request path_beg -i /thumbnail/
use_backend thumbnail_backend if thumbnail_request
default_backend backup_nodes
backend backup_nodes
server seafileserver01 192.168.0.2:80
backend thumbnail_backend
option forwardfor
server thumbnail 192.168.0.9:80
示例给出了完整的相关配置段，用于展示请求转发关系。对于已经存在的 HAProxy 配置，应将
acl
、
use_backend
和
backend
规则合并到原配置，不要重复创建同名
frontend
。修改后先验证配置，再重新加载：
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy
应限制缩略图服务器监听端口的外部访问，仅允许可信的反向代理或负载均衡器连接。
数据目录
默认情况下，缩略图服务器使用
/opt/seafile-data
存放持久化数据。独立部署时，常见目录包括：
目录
用途
/opt/seafile-data/conf
缩略图服务相关配置文件目录。
/opt/seafile-data/logs
日志目录。
/opt/seafile-data/seafile-data
使用本地存储时的 Seafile 数据目录。
/opt/seafile-data/seahub-data/thumbnail
已生成的缩略图文件目录。
在需要与 Seafile 共用
seafile.conf
的部署中，还应检查
/opt/seafile-data/seafile/conf/seafile.conf
是否存在且可读取。不同 Docker 模板和挂载方式的目录可能不同，请以实际配置的
SEAFILE_VOLUME
为准。
常见问题
无法生成高分辨率图片的缩略图
处理高分辨率图片可能消耗较多资源。缩略图服务器通过环境变量
THUMBNAIL_IMAGE_ORIGINAL_SIZE_LIMIT
限制原图大小，默认值为
256 MB
。
如有需要，可在
.env
中设置，例如：
THUMBNAIL_IMAGE_ORIGINAL_SIZE_LIMIT=512
官方 Docker Compose 模板已传递该变量；修改后需要重新创建相应容器，才能应用新的环境变量。提高限制可能增加内存和 CPU 压力，请根据服务器资源谨慎调整。
大型 PDF 无法生成缩略图
为了避免过大的 PDF 导致性能问题，缩略图服务器采用以下限制：当
PDF 文件大小超过
THUMBNAIL_PDF_SIZE_THRESHOLD
（默认 50 MB）
，
且
首页面积超过
8,000,000 平方点
时，不生成缩略图。
如果确需调整
THUMBNAIL_PDF_SIZE_THRESHOLD
，应检查当前 Compose 模板是否把它传递给缩略图容器。若模板中没有对应项，仅修改宿主机
.env
不会自动让容器读取该变量；需在
thumbnail-server.yml
的
thumbnail-server.environment
中显式添加，例如：
services:
thumbnail-server:
environment:
- THUMBNAIL_PDF_SIZE_THRESHOLD=${THUMBNAIL_PDF_SIZE_THRESHOLD:-50}
上述片段用于说明应增加的环境变量，
不要用它替换现有的整个
environment
配置
。调整阈值可能使 PDF 处理消耗更多资源。
服务已启动但缩略图仍不可用
请依次检查：
-
docker compose ps 是否显示缩略图服务正常运行，并查看 docker logs -f thumbnail-server 是否有报错。
-
seahub_settings.py 中是否按 Seafile 版本设置了正确的开关，配置修改后 Seafile 是否已重启。
-
/thumbnail/ 是否已经通过 Caddy、Nginx 或负载均衡器转发到缩略图服务器。
-
INNER_SEAHUB_SERVICE_URL 是否可以从缩略图节点访问，且 JWT 密钥是否与 Seafile 一致。
-
缩略图服务是否能访问文件存储后端；使用 S3 或多存储后端时，检查凭据、对象存储配置和 seafile.conf 。
如果使用的是默认 Caddy，检查
/thumbnail/ping
的访问结果；如果采用自定义代理，请确认它保留了正确的 URL 路径。
