add thumbnail-server (#539)

* add thumbnail-server * Update mkdocs.yml * Update thumbnail-server.md * update thumbnail-server version * add descriptions of S3 --------- Co-authored-by: Daniel Pan <freeplant@gmail.com> Co-authored-by: Junxiang Huang <wacmkxiaoyi@gmail.com>
2025-12-26 02:32:50 +00:00 · 2025-06-25 11:31:43 +08:00 · 2025-06-25 11:31:43 +08:00 · d43e7c1593
parent a8180e3326
commit d43e7c1593
5 changed files with 223 additions and 0 deletions
--- a/manual/extension/thumbnail-server.md
+++ b/manual/extension/thumbnail-server.md
@ -0,0 +1,120 @@
+# Thumbnail Server Overview
+
+Since Seafile 13.0, a new component thumbnail server is added. Thumbnail server can create thumbnails for images, videos, PDFs and other file types. Thumbnail server uses a task queue based architecture, it can better handle workloads than thumbnail generating inside Seahub component. 
+
+## How to configure and run
+
+First download `thumbnail-server.yml` to Seafile directory:
+
+```sh
+wget https://manual.seafile.com/13.0/repo/docker/thumbnail-server.yml
+```
+
+Modify `.env`, and insert `thumbnail-server.yml` into `COMPOSE_FILE`:
+
+```env
+COMPOSE_FILE='seafile-server.yml,caddy.yml,thumbnail-server.yml'
+```
+
+Finally, You can run thumbnail server with the following command:
+
+```sh
+docker compose down
+docker compose up -d
+```
+
+## Thumbnail Server in Seafile cluster
+
+There is no additional features for thumbnail server in the Pro Edition. It works the same as in community edition.
+
+If you enable [clustering](../setup_binary/cluster_deployment.md), You need to deploy thumbnail server on one of the servers, or a separate server. The load balancer should forward websockets requests to this node.
+
+Download `.env` and `thumbnail-server.yml` to thumbnail server directory:
+
+```sh
+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
+```
+
+Then modify the `.env` file according to your environment. The following fields are needed to be modified:
+
+| variable               | description                                                                                                   |  
+|------------------------|---------------------------------------------------------------------------------------------------------------|  
+| `SEAFILE_VOLUME`        | The volume directory of thumbnail server data                                                                            |  
+| `SEAFILE_MYSQL_DB_HOST`| Seafile MySQL host                                                                                            |  
+| `SEAFILE_MYSQL_DB_USER`| Seafile MySQL user, default is `seafile`                                                                       |  
+| `SEAFILE_MYSQL_DB_PASSWORD`| Seafile MySQL password                                                                                    |  
+| `TIME_ZONE`            | Time zone                                                                                                     |  
+| `JWT_PRIVATE_KEY`      | JWT key, the same as the config in Seafile `.env` file                                                         |  
+| `INNER_SEAHUB_SERVICE_URL`| Inner Seafile url                                                                                            |  
+| `SEAF_SERVER_STORAGE_TYPE`   | What kind of the Seafile data for storage. Available options are `disk` (i.e., local disk), `s3` and `multiple` (see the details of [multiple storage backends](../setup/setup_with_multiple_storage_backends.md)) |
+| `S3_COMMIT_BUCKET`   | S3 storage backend commit objects bucket |
+| `S3_FS_BUCKET`   | S3 storage backend fs objects bucket |
+| `S3_BLOCK_BUCKET`   | S3 storage backend block objects bucket |
+| `S3_KEY_ID`   | S3 storage backend key ID | 
+| `S3_SECRET_KEY`   | S3 storage backend secret key | 
+| `S3_AWS_REGION`   | Region of your buckets | 
+| `S3_HOST`   | Host of your buckets | 
+| `S3_USE_HTTPS`   | Use HTTPS connections to S3 if enabled |
+| `S3_USE_V4_SIGNATURE`   | Use the v4 protocol of S3 if enabled |
+| `S3_PATH_STYLE_REQUEST`   | This option asks Seafile to use URLs like `https://192.168.1.123:8080/bucketname/object` to access objects. In *Amazon S3*, the default URL format is in virtual host style, such as `https://bucketname.s3.amazonaws.com/object`. But this style relies on advanced DNS server setup. So most self-hosted storage systems only implement the path style format. |
+| `S3_SSE_C_KEY`   | A string of 32 characters can be generated by openssl rand -base64 24. It can be any 32-character long random string. It's required to use V4 authentication protocol and https if you enable SSE-C. |
+
+Then you can run thumbnail server with the following command:
+
+```sh
+docker compose up -d
+```
+
+You need to configure load balancer according to the following forwarding rules:
+
+1. Forward `/thumbnail` requests to thumbnail server via http protocol.
+
+Here is a configuration that uses haproxy to support thumbnail server. Haproxy version needs to be >= 2.0.
+You should use similar configurations for other load balancers.
+
+```
+#/etc/haproxy/haproxy.cfg
+
+# Other existing haproxy configurations
+......
+
+frontend seafile
+    bind 0.0.0.0:80
+    mode http
+    option httplog
+    option dontlognull
+    option forwardfor
+    acl thumbnail_request url_sub -i /thumbnail/
+    use_backend thumbnail_backend if thumbnail_request
+    default_backend backup_nodes
+
+backend backup_nodes
+    cookie SERVERID insert indirect nocache
+    server seafileserver01 192.168.0.2:80
+
+backend thumbnail_backend
+    option forwardfor
+    server thumbnail 192.168.0.9:80
+
+```
+
+!!! warning "Thumbnail server has to access Seafile' storage"
+    The thumbnail server needs to access Seafile storage. 
+
+    - If you use local storage, you need to mount the `/opt/seafile-data` directory of the Seafile node to the thumbnail node, and set `SEAFILE_VOLUME` to the mounted directory correctly.
+
+    - If you use single backend S3 storage, please correctly set relative environment vairables in `.env`.
+
+    - If you are using multiple storage backends, you have to copy the `seafile.conf` of the Seafile node to the `/opt/seafile-data/seafile/conf` directory of the thumbnail node, and set `SEAF_SERVER_STORAGE_TYPE=multiple` in `.env`.
+
+## Thumbnail server directory structure
+
+`/opt/seafile-data`
+
+Placeholder spot for shared volumes. You may elect to store certain persistent information outside of a container, in our case we keep various log files outside. This allows you to rebuild containers easily without losing important information.
+
+* /opt/seafile-data/conf: This is the directory for config files.
+* /opt/seafile-data/logs: This is the directory for logs.
+* /opt/seafile-data/seafile-data: This is the directory for seafile storage (if you use local storage).
+* /opt/seafile-data/seahub-data/thumbnail: This is the directory for thumbnail files.
--- a/manual/repo/docker/thumbnail-server.yml
+++ b/manual/repo/docker/thumbnail-server.yml
@ -0,0 +1,46 @@
+services:
+
+  thumbnail-server:
+    image: ${THUMBNAIL_SERVER_IMAGE:-seafileltd/thumbnail-server:13.0.0-testing}
+    container_name: thumbnail-server
+    restart: always
+    volumes:
+      - ${SEAFILE_VOLUME:-/opt/seafile-data}:/shared
+    # ports:
+    #   - "80:80"
+    environment:
+      - TIME_ZONE=${TIME_ZONE:-Etc/UTC}
+      - SEAFILE_MYSQL_DB_HOST=${SEAFILE_MYSQL_DB_HOST:-db}
+      - SEAFILE_MYSQL_DB_PORT=${SEAFILE_MYSQL_DB_PORT:-3306}
+      - SEAFILE_MYSQL_DB_USER=${SEAFILE_MYSQL_DB_USER:-seafile}
+      - SEAFILE_MYSQL_DB_PASSWORD=${SEAFILE_MYSQL_DB_PASSWORD:?Variable is not set or empty}
+      - SEAFILE_MYSQL_DB_CCNET_DB_NAME=${SEAFILE_MYSQL_DB_CCNET_DB_NAME:-ccnet_db}
+      - SEAFILE_MYSQL_DB_SEAFILE_DB_NAME=${SEAFILE_MYSQL_DB_SEAFILE_DB_NAME:-seafile_db}
+      - JWT_PRIVATE_KEY=${JWT_PRIVATE_KEY:?Variable is not set or empty}
+      - SITE_ROOT=${SITE_ROOT:-/}
+      - INNER_SEAHUB_SERVICE_URL=${INNER_SEAHUB_SERVICE_URL:-http://seafile}
+      - SEAF_SERVER_STORAGE_TYPE=${SEAF_SERVER_STORAGE_TYPE:-}
+      - S3_COMMIT_BUCKET=${S3_COMMIT_BUCKET:-}
+      - S3_FS_BUCKET=${S3_FS_BUCKET:-}
+      - S3_BLOCK_BUCKET=${S3_BLOCK_BUCKET:-}
+      - S3_KEY_ID=${S3_KEY_ID:-}
+      - S3_SECRET_KEY=${S3_SECRET_KEY:-}
+      - S3_USE_V4_SIGNATURE=${S3_USE_V4_SIGNATURE:-true}
+      - S3_AWS_REGION=${S3_AWS_REGION:-us-east-1}
+      - S3_HOST=${S3_HOST:-}
+      - S3_USE_HTTPS=${S3_USE_HTTPS:-true}
+      - S3_PATH_STYLE_REQUEST=${S3_PATH_STYLE_REQUEST:-false}
+      - S3_SSE_C_KEY=${S3_SSE_C_KEY:-}
+    labels:
+      caddy: ${SEAFILE_SERVER_PROTOCOL:-http}://${SEAFILE_SERVER_HOSTNAME:?Variable is not set or empty}
+      caddy.1_handle: "/thumbnail/*"
+      caddy.1_handle.0_reverse_proxy: "{{upstreams 80}}"
+    depends_on:
+      db:
+        condition: service_healthy
+    networks:
+      - seafile-net
+
+networks:
+  seafile-net:
+    name: seafile-net
--- a/manual/repo/docker/thumbnail-server/env
+++ b/manual/repo/docker/thumbnail-server/env
@ -0,0 +1,17 @@
+COMPOSE_FILE='thumbnail-server.yml'
+COMPOSE_PATH_SEPARATOR=','
+
+
+THUMBNAIL_SERVER_IMAGE=seafileltd/thumbnail-server:13.0.0-testing
+
+SEAFILE_VOLUME=/opt/seafile-data
+
+SEAFILE_MYSQL_DB_HOST=192.168.0.2
+SEAFILE_MYSQL_DB_USER=seafile
+SEAFILE_MYSQL_DB_PASSWORD=PASSWORD
+
+TIME_ZONE=Etc/UTC
+
+JWT_PRIVATE_KEY=
+
+INNER_SEAHUB_SERVICE_URL=192.168.0.2
--- a/manual/repo/docker/thumbnail-server/thumbnail-server.yml
+++ b/manual/repo/docker/thumbnail-server/thumbnail-server.yml
@ -0,0 +1,39 @@
+services:
+
+  thumbnail-server:
+    image: ${THUMBNAIL_SERVER_IMAGE:-seafileltd/thumbnail-server:13.0.0-testing}
+    container_name: thumbnail-server
+    restart: always
+    volumes:
+      - ${SEAFILE_VOLUME:-/opt/seafile-data}:/shared
+    ports:
+      - "80:80"
+    environment:
+      - TIME_ZONE=${TIME_ZONE:-Etc/UTC}
+      - SEAFILE_MYSQL_DB_HOST=${SEAFILE_MYSQL_DB_HOST:-db}
+      - SEAFILE_MYSQL_DB_PORT=${SEAFILE_MYSQL_DB_PORT:-3306}
+      - SEAFILE_MYSQL_DB_USER=${SEAFILE_MYSQL_DB_USER:-seafile}
+      - SEAFILE_MYSQL_DB_PASSWORD=${SEAFILE_MYSQL_DB_PASSWORD:?Variable is not set or empty}
+      - SEAFILE_MYSQL_DB_CCNET_DB_NAME=${SEAFILE_MYSQL_DB_CCNET_DB_NAME:-ccnet_db}
+      - SEAFILE_MYSQL_DB_SEAFILE_DB_NAME=${SEAFILE_MYSQL_DB_SEAFILE_DB_NAME:-seafile_db}
+      - JWT_PRIVATE_KEY=${JWT_PRIVATE_KEY:?Variable is not set or empty}
+      - SITE_ROOT=${SITE_ROOT:-/}
+      - INNER_SEAHUB_SERVICE_URL=${INNER_SEAHUB_SERVICE_URL:Variable is not set or empty}
+      - SEAF_SERVER_STORAGE_TYPE=${SEAF_SERVER_STORAGE_TYPE:-}
+      - S3_COMMIT_BUCKET=${S3_COMMIT_BUCKET:-}
+      - S3_FS_BUCKET=${S3_FS_BUCKET:-}
+      - S3_BLOCK_BUCKET=${S3_BLOCK_BUCKET:-}
+      - S3_KEY_ID=${S3_KEY_ID:-}
+      - S3_SECRET_KEY=${S3_SECRET_KEY:-}
+      - S3_USE_V4_SIGNATURE=${S3_USE_V4_SIGNATURE:-true}
+      - S3_AWS_REGION=${S3_AWS_REGION:-us-east-1}
+      - S3_HOST=${S3_HOST:-}
+      - S3_USE_HTTPS=${S3_USE_HTTPS:-true}
+      - S3_PATH_STYLE_REQUEST=${S3_PATH_STYLE_REQUEST:-false}
+      - S3_SSE_C_KEY=${S3_SSE_C_KEY:-}
+    networks:
+      - seafile-net
+
+networks:
+  seafile-net:
+    name: seafile-net
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -138,6 +138,7 @@ nav:
      - SeaDoc Integration: extension/setup_seadoc.md
      - Notification Server: extension/notification-server.md
      - Metadata Server: extension/metadata-server.md
+      - Thumbnail Server: extension/thumbnail-server.md
      - WebDAV extension: extension/webdav.md
      - FUSE extension: extension/fuse.md
    - Online Office: