Docker 中 Nextcloud 的文件存储位置怎么查
了解 Nextcloud 数据目录在容器内的位置、Docker volume 对应的主机路径,以及备份所需的 5 项内容,而不只是用户文件。
Docker 中 Nextcloud 存储文件的位置
Docker 中的 Nextcloud 会将文件存储在容器内的数据目录中。服务器上的实际位置取决于您为其附加的 volume 或 bind mount。对于 linuxserver.io 镜像,lscr.io/linuxserver/nextcloud,用户文件位于 /data,config.php、应用和主题位于 /config 下。这两个路径都是容器路径。一条命令可以显示它们对应的主机路径。本指南的其余部分将回答问题中更复杂的部分:数据目录不包含哪些内容。
固定镜像标签。路径属于镜像,而不是 Nextcloud;浮动标签可能在您不知情的情况下发生变化。截至 November 20, 2026,当前的稳定镜像版本是 35.0.3-ls3,其中包含 Nextcloud 35.0.3,也就是 Nextcloud 35 主版本的第 4 个版本。该镜像一次只升级一个主版本,因此仍在 34.x 上的 stack 会分一步升级到 35,升级前应先执行备份。
services:
nextcloud:
image: lscr.io/linuxserver/nextcloud:35.0.3-ls3
container_name: nextcloud
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
volumes:
- nextcloud_config:/config
- nextcloud_data:/data
ports:
- 443:443
restart: unless-stopped
nextcloud-db:
image: mariadb:11.8
container_name: nextcloud-db
environment:
- MARIADB_ROOT_PASSWORD=${MARIADB_ROOT_PASSWORD}
- MARIADB_DATABASE=nextcloud
- MARIADB_USER=nextcloud
- MARIADB_PASSWORD=${NEXTCLOUD_DB_PASSWORD}
volumes:
- nextcloud_db:/var/lib/mysql
restart: unless-stopped
volumes:
nextcloud_config:
nextcloud_data:
nextcloud_db:这两个密码来自 compose 文件旁的 .env 文件,因此不会写入 compose 文件本身。答案中共有 3 个 volume,只有其中 1 个存储用户文件。
这些容器路径来自该镜像的文档。其他 Nextcloud 镜像的文件系统布局可能不同,并会将安装内容放在自己的 web root 下,因此直接使用论坛帖子中的路径只是猜测。请从正在运行的容器中读取实际配置。
docker inspect nextcloud该输出中的 Mounts 部分会列出每个挂载点,其中 Source 位于主机侧,Destination 位于容器侧。无论您选择哪个镜像,该列表都会给出当前配置的实际答案。
如何查找卷背后的真实主机路径?
命名卷由 Docker 管理,因此您无需选择其路径。您只需查询该路径。
docker volume ls
docker volume inspect nextcloud_nextcloud_data卷名称很重要。Docker Compose 会在卷名称前加上项目名称。默认情况下,项目名称是存放 compose 文件的目录名称。因此,文件中写作 nextcloud_data 的卷,通常会以 nextcloud_nextcloud_data 的名称存在于磁盘上。docker volume ls 会显示真实名称。裁剪后的 inspect 输出如下:
[
{
"CreatedAt": "2026-08-18T09:12:44Z",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/nextcloud_nextcloud_data/_data",
"Name": "nextcloud_nextcloud_data",
"Scope": "local"
}
]Mountpoint 就是答案。请通过命令读取该路径,不要假定它不会变化,因为路径可能发生改变。默认情况下,在 rootless Docker 中,整个 Docker 数据根目录位于运行 daemon 的用户主目录内,因此路径会从其他位置开始。
使用绑定挂载可以避免这个问题。在 compose 文件中写入 - /srv/nextcloud/data:/data,主机路径就是您输入的路径;docker inspect 会将其报告为 Source。这种选择影响的不只是路径,因为命名卷和绑定挂载在所有权和备份方面的行为不同。
数据目录不是备份
Nextcloud 手册列出了备份必须保留的五项内容:config 文件夹、custom apps 文件夹、data 文件夹、theme 文件夹和数据库。在此镜像中,config、apps 和 theme 文件夹都位于 /config 下,而数据库运行在拥有独立卷的容器中。单独复制 /data,实际上只保存了问题中最不重要的部分。
数据库很重要,因为 Web 界面从不直接列出目录。它列出的是文件缓存中的行记录,所以手册要求您在手动将文件复制到 data 目录后运行扫描。将 /data 恢复到一个空数据库旁边,得到的只是没有索引的字节:没有用户、没有共享,也不会在文件列表中显示任何内容。将数据库恢复到一个空的 /data 旁边,则每一行都指向已经不存在的文件。
config.php 保存数据库凭据和受信任域名。它还保存实例 ID。该 ID 加上 appdata_ 前缀后,会构成应用数据文件夹的名称。请从正在运行的实例中查询这些值,不要依赖记忆中的值。
docker exec -it nextcloud occ config:system:get datadirectory
docker exec -it nextcloud occ config:system:get instanceid第一条命令会输出此实例实际使用的数据目录,此处为 /data。此镜像在 PATH 中提供了 occ 包装器,因此请直接通过 docker exec 运行它。不要照搬 Nextcloud 手册中较长的 sudo 和 php occ 形式,因为手册针对的是容器外部的安装。
数据卷为何会悄悄被占满?
预览文件和每个用户的历史版本与文件存放在同一个卷中,但用户在 Web 界面中看到的存储用量不包含这两类数据。
- 预览文件是生成的缩略图。它们位于数据目录中的应用数据文件夹内,目录名为
appdata_,后面跟实例 ID。 - 删除的文件会保留在回收站中。
trashbin_retention_obligation默认为auto。有可用空间时,删除的文件可以保留超过 30 天;需要空间时,也可以在未满 30 天前删除。删除的文件不计入用户的正常配额,但回收站有自己的限制:默认最多使用用户剩余配额空间的 50%;没有配额的用户则最多使用可用磁盘空间。当回收站超过该限制时,Nextcloud 会先删除最早符合条件的项目。在auto下,文件即使未满 30 天也可能被删除。 - 旧版本也会保留。
versions_retention_obligation也默认为auto。它会随着时间推移减少版本数量,并保留每个时间窗口中的最新版本;配置最大保留期限后,后台作业会删除超过该期限的版本,或删除文件已不存在的版本。对于设置了配额的账户,Versions 应用会将目标设为用户当前剩余配额空间的 50%;没有配额时,则直接使用文件系统的可用空间。当需要释放空间时,它会先删除最旧的版本,同时至少保留最近的两个版本,因此该目标并不是硬性上限。用户手动命名的版本不会被自动过期机制删除,但用户仍可手动删除;occ versions:cleanup会将已命名版本与其他版本一并删除。
删除任何内容前,先进行测量。
docker exec -it nextcloud sh -c 'du -sh /data/*'
docker exec -it nextcloud sh -c 'du -sh /data/appdata_*'第一行会分别列出每个用户文件夹和应用数据文件夹的一个数值。如果应用数据的数值较大,请检查其 preview 子目录;应用数据还包含头像和缓存资源。下面的清理命令都有文档说明,而且每条命令都会有意销毁数据。
docker exec -it nextcloud occ trashbin:cleanup --all-users
docker exec -it nextcloud occ versions:cleanup alice
docker exec -it nextcloud occ preview:cleanuppreview:cleanup 会删除所有已生成的预览。用户打开这些文件时,Nextcloud 会重新生成预览,因此空间占用会逐步恢复,同时增加 CPU 负载。如果该卷只是更大磁盘问题的一部分,旧镜像和过期的构建缓存 通常是另一部分。
为什么复制到主机上的文件不会出现在 Nextcloud 中?
因为 Nextcloud 从数据库读取文件缓存,而不是直接读取目录。复制操作在磁盘上创建了文件,但没有创建匹配的数据库记录,因此 Web 界面没有可列出的内容。手册明确说明了这种情况:直接将文件复制到数据目录后,必须执行扫描。
docker exec -it nextcloud occ files:scan --path="/alice/files/Photos"
docker exec -it nextcloud occ files:scan --all --unscanned -v
docker exec -it nextcloud occ files:scan --all--path参数还展示了数据目录中的布局:每个用户都有一个以其用户名命名的文件夹,其中的 files 保存该用户在 Web 界面中看到的内容。知道文件所在位置时,可以只扫描一个路径。--all 会遍历所有用户;对于大型实例,这可能需要很长时间。--unscanned 只处理标记为尚未完成扫描的文件。-v 会在处理文件时逐个输出文件名,这样可以区分命令无响应和命令仍在运行。
文件所有权决定扫描是否足够。如果容器用户无法写入某个文件,扫描会将其编入索引,但后续移动操作会失败。因此列表看起来正确,但在 Web 界面中重命名或删除文件会失败。
设置 PUID 和 PGID 后,为什么写入仍会失败?
因为内核比较的是数字,而不是名称。PUID 和 PGID 设置容器进程运行时使用的数字用户 ID(uid)和组 ID(gid)。主机上的每个文件也都有数字所有者。两个数字不一致时,写入会被拒绝,无论两端显示的名称是什么。
docker exec -it nextcloud id abc
sudo ls -ln /var/lib/docker/volumes/nextcloud_nextcloud_data/_dataid abc会输出容器实际使用的 uid 和 gid,也就是你设置的 PUID 和 PGID。ls -ln会输出数字所有者,而 -n 很重要:普通的 ls -l 会通过主机自己的用户列表将这些数字转换为名称,但该名称在容器内没有意义。请比较这两个数字。
然后直接测试写入,不要靠猜测。
docker exec -u abc -it nextcloud touch /data/writetest名为 /data 的 Permission denied 是确认结果。先在容器内修复所有权,再运行同样的测试。
docker exec -u 0 -it nextcloud chown -R abc:abc /data
docker exec -u abc -it nextcloud touch /data/writetest
docker exec -u abc -it nextcloud rm /data/writetest之所以要在容器内执行,是因为 rootless Docker 会通过 /etc/subuid 中的 subordinate 范围映射容器的用户 ID。因此,容器内的 uid 1000 会对应主机上高得多的 uid。在主机上执行 chown 1000:1000 会设置一个容器无法使用的所有者,写入仍会失败。在容器内运行 chown 时,会使用与 Nextcloud 进程相同的映射,因此这些数字会自然对应。这也是为什么在排查其他问题前,必须先确保 PUID 和 PGID 与磁盘上的所有者一致。
如何备份,才能确保恢复成功?
数据库和目录必须来自同一时刻。维护模式会阻止登录,因此在导出和复制之间不会有上传写入。
docker exec -it nextcloud occ maintenance:mode --on
docker exec nextcloud-db mariadb-dump --single-transaction -u nextcloud -p"$NEXTCLOUD_DB_PASSWORD" nextcloud > nextcloud-sqlbkp.sql
docker run --rm -v nextcloud_nextcloud_data:/data:ro -v "$PWD":/backup alpine:3.22 tar czf /backup/nextcloud-data.tgz -C /data .
docker run --rm -v nextcloud_nextcloud_config:/config:ro -v "$PWD":/backup alpine:3.22 tar czf /backup/nextcloud-config.tgz -C /config .
docker exec -it nextcloud occ maintenance:mode --off注意导出命令中没有什么:没有 `-t 标志。TTY 会改写行尾,经过 TTY 的 SQL 导出文件可能损坏,而且通常要到恢复时才会发现。还要注意,命令运行时,命令行中的密码会显示在 ps 输出中;将密码从 .env 文件读取到 shell,可以避免将密码输入 shell 历史记录,但不会隐藏展开后的命令行参数。较旧的数据库镜像使用 mysqldump,而不是 mariadb-dump`;手册同时记录了这两种写法。
恢复时,将导出文件加载到空数据库中,将两个归档分别解压到新的卷中,启动容器,然后关闭维护模式。如果目录和导出文件来自不同时间点,文件缓存与磁盘上的数据就会不一致,而 `occ files:scan --all` 只能单向修复。它可以找出存在文件但没有对应记录的情况,但无法恢复记录所指向的文件。
将恢复结果保存在服务器之外。存放在同一 VPS 内的副本会随 VPS 一起丢失。因此,使用 restic 备份到服务器外的存储库应纳入这一流程;提供商快照与备份是不同工具。如果您还在搭建整个环境,在 VPS 上完整安装 Nextcloud介绍了本指南未涵盖的反向代理和 TLS(传输层安全)证书配置。
FAQ
Nextcloud 数据目录在 Docker 容器中的什么位置?
使用 linuxserver.io 镜像时,数据目录在容器内的 /data,而 config.php、应用和主题位于 /config。这些都是容器路径。要查看主机路径,请运行 docker inspect nextcloud,然后读取 Mounts 部分中的 Source 值;也可以在该卷上运行 docker volume inspect,然后读取 Mountpoint。其他 Nextcloud 镜像使用不同的容器路径,因此请查看所固定标签的文档,并使用 docker exec -it nextcloud occ config:system:get datadirectory 进行确认。
为什么我复制到卷中的文件不会显示在 Nextcloud 中?
Nextcloud 从数据库中的文件缓存读取文件列表,而不是直接读取目录。因此,未通过 Nextcloud 添加的文件没有对应记录,会保持不可见。针对一个文件夹运行 docker exec -it nextcloud occ files:scan --path="/alice/files/Photos",或针对所有用户运行 occ files:scan --all。如果文件显示出来,但随后无法移动或删除,原因是所有权不正确:容器用户必须具有写入这些文件的权限。
只复制数据卷就足以恢复 Nextcloud 吗?
不够。数据卷保存文件内容。数据库保存文件索引、用户和共享信息,而 config.php 保存数据库凭据和实例 ID。要完成有效恢复,需要数据目录、配置目录、数据库,以及自定义应用和主题目录(如果使用)。这些内容必须取自同一时刻,因为数据库比文件更新时,可能会指向不存在的文件。
为什么我的数据卷比用户看到的文件大很多?
预览、已删除文件和旧版本都保存在同一卷中,但用户看到的容量统计不会包含它们。使用 docker exec -it nextcloud sh -c 'du -sh /data/*' 进行测量。默认情况下,空间不足时,回收站会删除超过 30 天的文件;空间充足时则会保留更长时间。对于设置了配额的账户,版本清理会以剩余配额空间的一半为目标;对于未设置配额的账户,则直接使用文件系统可用空间作为目标。保留较新的版本可能导致无法达到该目标。使用 occ trashbin:cleanup --all-users、occ versions:cleanup alice 和 occ preview:cleanup 清理这些内容。用户打开文件后,预览仍可能重新增长。
可以将 Nextcloud 数据目录移动到另一块磁盘吗?
将新位置挂载到相同的容器路径,不要修改 Nextcloud 已知的路径。停止容器,使用保留所有权的方式将旧内容复制到新磁盘(cp -a 或 rsync -aAX),然后在 compose 文件中将卷或绑定挂载指向新位置,最后重新启动容器。Nextcloud 仍会看到 /data,因此无需修改数据库中的任何记录。使用 docker exec -it nextcloud occ config:system:get datadirectory 和一次测试上传进行验证。