Metadata Server - seafile-manual-cn

Metadata Server 用于管理 Seafile 资料库中的文件元数据。启用后，可以在资料库中使用扩展属性，并通过视图查看和整理文件信息。

本文适用于 Seafile 14.0 和 13.0 的 Docker 部署。以下以 Seafile 14.0 为主；Seafile 13.0 的配置方法见文末 Seafile 13.0 配置。

部署前准备

先完成 Seafile 部署并确认服务正常运行。 Metadata Server 启动时需要读取 Seafile 的 seafile.conf 。首次安装 Seafile 时，不要让 Metadata Server 比 Seafile 更早启动。

使用 Redis 缓存。 Metadata Server 不支持以 Memcached 作为缓存服务。在 Seafile 的 .env 中确认：

                    
                
                        
                
                    
                        
                            CACHE_PROVIDER=redis

如果使用了外部 Redis，还需要确保 Seafile 和 Metadata Server 都能够连接到该 Redis，并正确配置访问地址、端口和密码。对于 原来使用 Memcached 的现有部署 ，还应检查 seafile.conf 、 seahub_settings.py 和 seafevents.conf 中的缓存配置是否已切换到 Redis；不要仅修改 .env 而忽略已有配置文件。

确认数据访问方式。 与 Seafile 集成部署时，Metadata Server 可以使用现有配置和持久化数据目录；独立部署（常见于集群环境）时，必须确保它能够访问 Seafile 的配置文件和实际存储的数据。独立部署主要适用于使用 S3 等共享存储后端的场景。

注意：本文示例以 /opt/seafile 为 Docker Compose 文件目录，以 /opt/seafile-data 为 Seafile 持久化数据目录。如果安装时使用了其他路径，请相应调整。

一、与 Seafile 集成部署（推荐）

1. 下载 Docker Compose 文件

在存放 seafile-server.yml 和 .env 的目录执行：

Seafile 14.0：

            
                
                
                
            
                
                    cd /opt/seafile
                
            
    
                
            
                
                
            
                
                    wget https://manual.seafile.com/14.0/repo/docker/md-server.yml

Seafile 13.0：

            
                
                
                
            
                
                    cd /opt/seafile
                
            
    
                
            
                
                
            
                
                    wget https://manual.seafile.com/13.0/repo/docker/md-server.yml

2. 修改 .env

将 md-server.yml 加入 COMPOSE_FILE 。 请保留已经使用的其他 Compose 文件 ，例如 caddy.yml 、 seadoc.yml 或 seasearch.yml ，不要直接覆盖原列表。

例如，原配置包含 seafile-server.yml 、 caddy.yml 和 seadoc.yml 时，修改为：

            
                
                
                
            
                
                    COMPOSE_FILE=seafile-server.yml,caddy.yml,seadoc.yml,md-server.yml

Seafile 14.0 还需要在 Seafile 服务使用的 .env 中启用元数据管理：

            
                
                
                
            
                
                    CACHE_PROVIDER=redis
                
            
    
                
            
                
                
            
                
                    ENABLE_METADATA_MANAGEMENT=True

对于与 Seafile 一同部署的 Metadata Server，默认内部访问地址为 http://seafile-md-server:8084 ，通常无需设置 INNER_METADATA_SERVER_URL 。

Metadata Server 与 Seafile 共享相关配置（包括 JWT_PRIVATE_KEY ），默认将元数据保存在 /opt/seafile-data/seafile/md-data 。也可以按需指定镜像版本和缓存上限：

            
                
                
                
            
                
                    MD_IMAGE=seafileltd/seafile-md-server:14.0-latest
                
            
    
                
            
                
                
            
                
                    MD_MAX_CACHE_SIZE=1GB

MD_MAX_CACHE_SIZE 限制内存缓存大小，不限制磁盘占用。使用 Seafile 13.0 时，请使用对应的 13.0-latest 镜像标签，并按照文末说明启用元数据管理。

3. 使用 S3 保存元数据（可选）

如果准备将 Metadata Server 的元数据存储在 S3 中，请先创建 单独的元数据存储桶 ，然后在 .env 中设置：

            
                
                
                
            
                
                    MD_STORAGE_TYPE=s3
                
            
    
                
            
                
                
            
                
                    S3_MD_BUCKET=seafile-md-bucket
                
            
    
                
            
                
                
            
                
                    S3_KEY_ID=<your-key-id>
                
            
    
                
            
                
                
            
                
                    S3_SECRET_KEY=<your-secret-key>
                
            
    
                
            
                
                
            
                
                    S3_USE_V4_SIGNATURE=true
                
            
    
                
            
                
                
            
                
                    S3_PATH_STYLE_REQUEST=false
                
            
    
                
            
                
                
            
                
                    S3_AWS_REGION=us-east-1
                
            
    
                
            
                
                
            
                
                    S3_HOST=
                
            
    
                
            
                
                
            
                
                    S3_USE_HTTPS=true
                
            
    
                
            
                
                
            
                
                    S3_SSE_C_KEY=

请将存储桶名称、凭据、区域和访问端点替换为实际值。若使用第三方兼容 S3 的对象存储，按服务商要求设置 S3_HOST 和路径样式访问方式；如需 SSE-C 加密，则需要妥善管理 S3_SSE_C_KEY 。Seafile 本身使用的 S3 存储桶和认证信息也必须配置完整。

有关 S3 参数的说明，请参阅使用 S3 存储后端。

4. 启动服务

修改配置后，在 Seafile 的 Compose 目录执行：

            
                
                
                
            
                
                    cd /opt/seafile
                
            
    
                
            
                
                
            
                
                    docker compose config --quiet
                
            
    
                
            
                
                
            
                
                    docker compose down
                
            
    
                
            
                
                
            
                
                    docker compose up -d

docker compose down 会中断当前 Compose 项目中的服务，请在合适的维护时段执行。首次启动时请确认 Seafile 已经成功初始化并存在 seafile.conf 。

二、独立部署 Metadata Server

集群部署或需要单独管理元数据服务时，可以将 Metadata Server 部署到另一台主机。此模式要求 Metadata Server 能够连接 Seafile 使用的 Redis 和数据库，并访问 Seafile 的配置及存储数据 ；通常使用 S3 等共享存储后端。

1. 下载独立部署文件

在 Metadata Server 主机执行：

Seafile 14.0：

            
                
                
                
            
                
                    mkdir -p /opt/seafile-md-server
                
            
    
                
            
                
                
            
                
                    cd /opt/seafile-md-server
                
            
    
                
            
                
                
            
                
                    wget https://manual.seafile.com/14.0/repo/docker/metadata-server/md-server.yml
                
            
    
                
            
                
                
            
                
                    wget -O .env https://manual.seafile.com/14.0/repo/docker/metadata-server/env

Seafile 13.0：

            
                
                
                
            
                
                    mkdir -p /opt/seafile-md-server
                
            
    
                
            
                
                
            
                
                    cd /opt/seafile-md-server
                
            
    
                
            
                
                
            
                
                    wget https://manual.seafile.com/13.0/repo/docker/metadata-server/md-server.yml
                
            
    
                
            
                
                
            
                
                    wget -O .env https://manual.seafile.com/13.0/repo/docker/metadata-server/env

2. 配置独立部署环境

根据下载的 .env 模板填写实际配置，并确认以下内容：

JWT_PRIVATE_KEY 与 Seafile 服务端的配置 完全一致 。
REDIS_HOST 、 REDIS_PORT 、 REDIS_PASSWORD 指向可访问的 Redis。
SEAF_SERVER_STORAGE_TYPE 与 Seafile 部署时使用的存储类型一致，例如 s3 或 multiple 。
存储桶、访问凭据及其他存储参数与 Seafile 使用的后端相匹配；同时为元数据存储配置 MD_STORAGE_TYPE 及其参数。
Metadata Server 能读取 Seafile 的配置文件，例如 seafile.conf 。如果使用独立容器或远程机器，请根据实际部署检查所需的挂载和网络访问。

如果元数据保存在 S3，可按前面的示例配置 MD_STORAGE_TYPE=s3 和 S3_MD_BUCKET 。不要仅因 Seafile 使用 S3，就假定 Metadata Server 已配置好自己的元数据存储桶。

3. 启动独立的 Metadata Server

            
                
                
                
            
                
                    cd /opt/seafile-md-server
                
            
    
                
            
                
                
            
                
                    docker compose config --quiet
                
            
    
                
            
                
                
            
                
                    docker compose up -d

4. 在 Seafile 端启用元数据管理

**Seafile 14.0：**在 Seafile 服务器使用的 .env 中设置：

            
                
                
                
            
                
                    CACHE_PROVIDER=redis
                
            
    
                
            
                
                
            
                
                    ENABLE_METADATA_MANAGEMENT=True
                
            
    
                
            
                
                
            
                
                    INNER_METADATA_SERVER_URL=http://<metadata-server-host>:8084

将 <metadata-server-host> 替换为 Seafile 容器能够访问的 Metadata Server 主机名或 IP 地址。 INNER_METADATA_SERVER_URL 是服务端内部访问地址，不应使用浏览器所访问的公共网页路径。

若部署了多个 Seafile 节点，请在各个需要连接 Metadata Server 的节点中设置 ENABLE_METADATA_MANAGEMENT=True 和 INNER_METADATA_SERVER_URL 。随后按该节点的部署方式重启 Seafile 服务。

**Seafile 13.0：**请使用文末的 seahub_settings.py 配置方式。

Kubernetes 部署

如果使用 Kubernetes，而不是 Docker Compose，请将非敏感配置放入 seafile-env.yaml 的 data 中：

            
                
                
                
            
                
                    ENABLE_METADATA_MANAGEMENT: "true"
                
            
    
                
            
                
                
            
                
                    INNER_METADATA_SERVER_URL: "http://<metadata-server-host>:8084"

MD_FILE_COUNT_LIMIT 也可在相应 ConfigMap 中设置。 JWT_PRIVATE_KEY 、Redis 密码及 S3 密钥等敏感信息应放入 seafile-secret ，不要直接写入普通 ConfigMap。确保所有需要访问 Metadata Server 的 Seafile Pod 都能够连接该服务。

三、环境变量说明

以下为 Metadata Server 常用的环境变量。集成部署通常复用 Seafile 现有的 .env ；独立部署则需要在 Metadata Server 的 .env 中设置相关连接信息。

环境变量

用途

默认值或要求

JWT_PRIVATE_KEY

Seafile 和 Metadata Server 通信使用的 JWT 密钥

必须一致

CACHE_PROVIDER

Seafile 缓存服务类型

必须为 redis

REDIS_HOST

Redis 主机地址

redis

REDIS_PORT

Redis 服务端口

6379

REDIS_PASSWORD

Redis 访问密码

按实际配置填写

MD_IMAGE

Metadata Server Docker 镜像

14.0 示例为 seafileltd/seafile-md-server:14.0-latest

MD_MAX_CACHE_SIZE

Metadata Server 内存缓存上限，不影响磁盘用量

1GB

SEAF_SERVER_STORAGE_TYPE

Seafile 资料库数据使用的存储类型

默认 disk ；应与 Seafile 配置一致，可使用 disk 、 s3 、 multiple 等

MD_STORAGE_TYPE

Metadata Server 自身元数据的存储类型

disk ；还支持 s3 、 ceph

S3_MD_BUCKET

Metadata Server 元数据的 S3 存储桶

MD_STORAGE_TYPE=s3 时必填

MD_CEPH_CONFIG

Ceph 配置文件路径，例如 /etc/ceph/ceph.conf

MD_STORAGE_TYPE=ceph 时必填

MD_CEPH_POOL

Metadata Server 使用的 Ceph 存储池

MD_STORAGE_TYPE=ceph 时必填

MD_CEPH_CLIENT_ID

Ceph 客户端 ID

可选，默认 admin

MD_CHECK_UPDATE_INTERVAL

定期检查并修复因事件遗漏而产生的元数据不一致

30m

MD_FILE_COUNT_LIMIT

允许启用元数据管理的资料库文件数量上限

100000

当资料库文件数量超过 MD_FILE_COUNT_LIMIT 时，无法为该资料库启用元数据管理。对于已启用元数据管理的资料库，如果记录数达到上限，尚未写入元数据服务器的文件将被跳过。

MD_CHECK_UPDATE_INTERVAL 不是正常的元数据同步频率。 元数据变更通常由事件实时触发同步；该参数用于定期执行一致性检查，处理可能遗漏的更新。

使用 MD_STORAGE_TYPE=ceph 时，还必须确保容器可以读取相应的 Ceph 配置文件并访问指定存储池。其余 S3 参数请参阅使用 S3 存储后端。

四、启动后检查

1. 检查 Metadata Server 容器

在 Docker 主机执行：

            
                
                
                
            
                
                    docker ps --filter name=seafile-md-server
                
            
    
                
            
                
                
            
                
                    docker logs -f seafile-md-server

正常启动时，日志中会出现类似信息：

            
                
                
                
            
                
                    [md-server] [INFO] Created data links
                
            
    
                
            
                
                
            
                
                    [md-server] [INFO] Database initialization completed
                
            
    
                
            
                
                
            
                
                    [md-server] [INFO] Starting Metadata server

2. 检查 Seafile 日志

检查 Seafile 的 seafevents.log 和 seahub.log ：确认元数据任务开始处理，且 Seahub 中没有与 Metadata Server 连接相关的错误。必要时可在宿主机的 Seafile 日志目录查看文件，或使用 Docker 日志辅助排查。

3. 在网页端启用扩展属性

打开目标资料库，在侧边栏进入设置，找到 Metadata & AI（元数据与 AI） 选项卡，开启 Enable extended properties（启用扩展属性） 。

然后进入资料库的 视图（Views） ，即可查看文件及其扩展属性。

五、目录结构

Metadata Server 与 Seafile 集成部署且使用默认持久化目录时，相关目录为：

宿主机目录

用途

/opt/seafile-data/seafile/md-data

元数据及缓存数据

/opt/seafile-data/seafile/logs/seaf-md-server

Metadata Server 运行日志和访问日志

如果使用了自定义 SEAFILE_VOLUME 或独立部署，请以实际 Docker 卷映射为准。

六、工作原理

Metadata Server 通过事件收集、增量更新和属性提取维护资料库中的文件元数据。

事件收集与增量更新

文件修改后，Seafile 产生 repo_update 事件， seafevents 将相关任务写入 Redis 队列 metadata_task 。Metadata Server 消费该队列中的任务，检查资料库的提交历史，并将文件变更应用到元数据记录中。

为跟踪处理进度，Metadata Server 在 MySQL 表 md_server_head_commit 中保存上次成功处理的提交 ID（ from_commit ）以及当前处理的提交 ID（ to_commit ）。处理时会沿提交历史回溯并计算差异，再按时间顺序更新元数据。这样可以区分移动文件与删除后重新创建文件等不同操作。

初始化和恢复

Metadata Server 会根据资料库元数据的状态决定处理方式：

状态

判断依据

处理方式

尚未初始化

md_server_head_commit 中没有记录

等待初始化任务，忽略其他更新事件

初始化中断

from_commit 为 NULL 且 initializing=1

重启后重新安排初始化，清理未完成的基础数据并重新导入

正常增量同步

from_commit 、 to_commit 均有值且 initializing=0

持续处理增量更新事件

并发处理和文件属性提取

Metadata Server 使用工作线程池处理任务。一个资料库正在更新时，后续更新会暂存在内存队列 pending_tasks ，避免多个工作线程同时修改同一资料库的元数据。

新文件加入资料库后，Metadata Server 还会向 Redis 队列 metadata_slow_task 发送 file_info_extract 任务，由相应组件补充图片尺寸等文件属性。 seafevents 也会通过 Redis 频道 metadata_update 发布消息，供其他扩展组件接收。

七、Seafile 13.0 配置

Seafile 13.0 的 Docker 部署和存储配置与上述方法基本相同，但 启用元数据管理的设置位置不同 。

1. 使用对应镜像与 Compose 文件

            
                
                
                
            
                
                    cd /opt/seafile
                
            
    
                
            
                
                
            
                
                    wget https://manual.seafile.com/13.0/repo/docker/md-server.yml

如需指定镜像版本，在 .env 中使用：

            
                
                
                
            
                
                    MD_IMAGE=seafileltd/seafile-md-server:13.0-latest

确认已启用 Redis，并在原有 COMPOSE_FILE 中增加 md-server.yml 。

2. 修改 seahub_settings.py

在 Seafile 的 seahub_settings.py 中启用元数据管理。默认 Docker 部署的宿主机配置路径通常为：

            
                
                
                
            
                
                    /opt/seafile-data/seafile/conf/seahub_settings.py

与 Seafile 集成部署：

            
                
                
                
            
                
                    ENABLE_METADATA_MANAGEMENT = True
                
            
    
                
            
                
                
            
                
                    METADATA_SERVER_URL = 'http://seafile-md-server:8084'

独立部署：

            
                
                
                
            
                
                    ENABLE_METADATA_MANAGEMENT = True
                
            
    
                
            
                
                
            
                
                    METADATA_SERVER_URL = 'http://<metadata-server-host>:8084'

独立部署地址应是 Seafile 服务容器可以访问的地址。完成后重启 Seafile，并查看 Metadata Server 与 Seahub 日志确认配置生效。

Seafile 14.0 应优先使用前文的 .env 配置 ENABLE_METADATA_MANAGEMENT 和 INNER_METADATA_SERVER_URL ，不要将本节中的 METADATA_SERVER_URL 当作 14.0 Docker 部署的标准环境变量。

常见问题

Metadata Server 无法启动，提示找不到 seafile.conf 。请确认 Seafile 已经初始化完成；集成部署应检查共享目录挂载，独立部署则需要检查配置文件是否在 Metadata Server 容器内可读取。

容器运行正常，但网页端没有元数据功能。 请检查 Redis、Seafile 端的启用配置、Metadata Server 的内部访问地址，以及浏览器中的扩展属性开关。Seafile 13.0 还需要检查 seahub_settings.py 。

启用后文件元数据没有及时更新。 请先确认 Redis 队列及日志中的任务处理是否正常。不要通过调小 MD_CHECK_UPDATE_INTERVAL 来替代对实时事件处理异常的排查。

独立部署无法读取资料库文件。 请确认两端的存储后端配置一致，且 Metadata Server 确实有访问 S3、Ceph 或其他相应后端的权限。