محل ذخیره‌سازی فایل‌ها در Nextcloud داکر

محل ذخیره‌سازی فایل‌ها در Nextcloud مبتنی بر Docker

Nextcloud در Docker فایل‌ها را در یک دایرکتوری داده درون کانتینر ذخیره می‌کند و محل واقعی آن‌ها روی سرور شما، همان volume یا bind mount است که به آن متصل کرده‌اید. در image ارائه شده توسط linuxserver.io، یعنی lscr.io/linuxserver/nextcloud، فایل‌های کاربر در /data قرار دارند و نصب Nextcloud به همراه config.php آن در /config واقع شده است. هر دوی این‌ها مسیرهای درون کانتینر هستند. یک دستور ساده، مسیر متناظر روی هاست را برای شما نمایش می‌دهد و باقی این راهنما به بخش پیچیده‌تر موضوع می‌پردازد: هر آنچه که در دایرکتوری داده قرار ندارد.

تگ image را ثابت (Pin) کنید. مسیرها متعلق به یک image خاص هستند، نه لزوماً خود Nextcloud، و یک تگ شناور ممکن است بدون اطلاع شما تغییر کند. تا اوت 2026، تگ پایدار فعلی برای این image برابر با 34.0.3 است.

services:
  nextcloud:
    image: lscr.io/linuxserver/nextcloud:34.0.3
    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:

دو رمز عبور از یک فایل .env در کنار فایل compose خوانده می‌شوند تا از فایل اصلی compose جدا بمانند. این یعنی سه volume در پاسخ وجود دارد که تنها یکی از آن‌ها حاوی فایل‌های کاربر است.

آن مسیرهای کانتینر از مستندات همان image خاص استخراج شده‌اند. یک image دیگر از Nextcloud ممکن است ساختار فایل‌سیستم متفاوتی داشته باشد و نصب را در root وب خود نگه دارد؛ بنابراین مسیری که از یک پست در انجمن‌ها کپی شده باشد، صرفاً یک حدس است. حقیقت را از کانتینری که در حال اجرای آن هستید، استخراج کنید.

docker inspect nextcloud

بخش Mounts در خروجی آن دستور، تمام mountها را فهرست می‌کند که در آن Source سمت هاست و Destination سمت کانتینر است. این فهرست، پاسخ نهایی را برای تنظیمات خاص شما، فارغ از اینکه چه imageای انتخاب کرده‌اید، ارائه می‌دهد.

چگونه مسیر واقعی میزبان (host path) را برای یک volume پیدا کنم؟

یک volume با نام (named volume) توسط Docker مدیریت می‌شود، بنابراین شما مسیر آن را انتخاب نمی‌کنید. شما باید آن را استعلام کنید.

docker volume ls
docker volume inspect nextcloud_nextcloud_data

نام اهمیت دارد. Docker Compose پیشوندی از نام پروژه را به نام volumeها اضافه می‌کند که به‌صورت پیش‌فرض همان نام دایرکتوری حاوی فایل compose شماست؛ بنابراین volumeای که در فایل به صورت 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 را اجرا می‌کند قرار دارد، بنابراین آن مسیر از جای دیگری شروع می‌شود.

استفاده از bind mount این پرسش را منتفی می‌کند. اگر در فایل compose عبارت - /srv/nextcloud/data:/data را بنویسید، مسیر میزبان همان مسیری است که خودتان تایپ کرده‌اید و دستور docker inspect آن را به عنوان Source گزارش می‌دهد. این انتخاب فراتر از تغییر مسیر است، زیرا named volumes and bind mounts در زمینه مالکیت فایل‌ها و پشتیبان‌گیری رفتار متفاوتی دارند.

چرا دایرکتوری داده‌ها به تنهایی یک نسخه پشتیبان محسوب نمی‌شود

راهنمای Nextcloud پنج مورد را فهرست می‌کند که یک نسخه پشتیبان باید شامل آن‌ها باشد: پوشه پیکربندی (config)، پوشه برنامه‌های سفارشی (apps)، پوشه داده‌ها (data)، پوشه پوسته (theme) و پایگاه داده. در این ایمیج، پوشه‌های config، apps و theme همگی در /config قرار دارند، در حالی که پایگاه داده در کانتینر اختصاصی خود با volume مخصوص به خود اجرا می‌شود. اگر فقط از /data نسخه پشتیبان تهیه کنید، در واقع کم‌اهمیت‌ترین بخش مسئله را ذخیره کرده‌اید.

پایگاه داده اهمیت دارد زیرا رابط وب هرگز یک دایرکتوری را فهرست نمی‌کند. این رابط، ردیف‌هایی از کش فایل‌ها را نمایش می‌دهد؛ به همین دلیل است که راهنما توصیه می‌کند پس از کپی دستی فایل‌ها در دایرکتوری داده، یک اسکن اجرا کنید. اگر /data را در کنار یک پایگاه داده خالی بازیابی کنید، شما فقط تعدادی بایت بدون ایندکس خواهید داشت: بدون کاربر، بدون اشتراک‌گذاری و بدون هیچ فایلی در لیست. اگر پایگاه داده را در کنار یک /data خالی بازیابی کنید، هر ردیف به فایلی اشاره می‌کند که وجود ندارد.

فایل config.php حاوی اعتبارنامه‌های پایگاه داده و دامنه‌های مورد اعتماد (trusted domains) است. این فایل همچنین شامل instance id است که نام پوشه داده‌های برنامه در داخل دایرکتوری داده‌ها محسوب می‌شود. به جای اعتماد به مقادیر حافظه، از خودِ instance در حال اجرا پرس‌وجو کنید.

docker exec -it nextcloud occ config:system:get datadirectory
docker exec -it nextcloud occ config:system:get instanceid

دستور اول، دایرکتوری داده‌ای که این instance واقعاً از آن استفاده می‌کند را چاپ می‌کند، که در اینجا /data است. این ایمیج یک wrapper به نام occ در مسیر سیستم دارد، بنابراین آن را مستقیماً از طریق docker exec اجرا کنید. از کپی کردن دستور طولانی‌تر sudo و php occ از راهنمای Nextcloud خودداری کنید، زیرا آن دستور برای نصب خارج از کانتینر نوشته شده است.

چه چیزی حجم داده را به‌طور پنهانی پر می‌کند؟

پیش‌نمایش‌ها و تاریخچهٔ هر کاربر در همان حجمی (volume) قرار دارند که فایل‌ها ذخیره می‌شوند و هیچ‌کدام از آن‌ها در آمار فضای ذخیره‌سازی که کاربر در رابط وب می‌بیند، لحاظ نمی‌شوند.

• پیش‌نمایش‌ها، تصاویر بندانگشتی (thumbnails) تولیدشده هستند. آن‌ها در پوشهٔ app data در داخل دایرکتوری data قرار دارند و نام آن‌ها با appdata_ و به دنبال آن شناسهٔ نمونه (instance id) شروع می‌شود.
• فایل‌های حذف‌شده در سطل زباله باقی می‌مانند. trashbin_retention_obligation به‌صورت پیش‌فرض روی auto تنظیم شده است که آن‌ها را به مدت 30 روز نگه می‌دارد و پس از آن تنها زمانی که به فضا نیاز باشد، حذفشان می‌کند. فایل‌های حذف‌شده همچنان در سهمیهٔ (quota) کاربر محاسبه می‌شوند و هنگامی که سهمیه پر شود، تنظیمات نگهداری نادیده گرفته شده و سطل زباله تا زمانی که فضای کافی برای سهمیه ایجاد شود، پاک‌سازی می‌شود.
• نسخه‌های قدیمی فایل‌ها نیز باقی می‌مانند. versions_retention_obligation نیز به‌صورت پیش‌فرض روی auto تنظیم شده است. برنامهٔ Versions هرگز بیش از 50 درصد از فضای آزاد فعلی کاربر را اشغال نمی‌کند و هنگام پاک‌سازی، قدیمی‌ترین نسخه‌ها را حذف کرده و دو نسخهٔ اخیر را نگه می‌دارد. نسخه‌ای که کاربر به‌صورت دستی نام‌گذاری کرده باشد، هرگز حذف نمی‌شود.

پیش از حذف هر چیزی، ابتدا اندازه‌گیری کنید.

docker exec -it nextcloud sh -c 'du -sh /data/*'
docker exec -it nextcloud sh -c 'du -sh /data/appdata_*'

خط اول، یک عدد برای هر پوشهٔ کاربر به علاوهٔ پوشهٔ app data ارائه می‌دهد. اگر عدد مربوط به app data بزرگ است، دلیل آن پیش‌نمایش‌ها هستند. دستورات پاک‌سازی زیر مستند شده‌اند و هر یک از آن‌ها عمداً داده‌ها را از بین می‌برند.

docker exec -it nextcloud occ trashbin:cleanup --all-users
docker exec -it nextcloud occ versions:cleanup alice
docker exec -it nextcloud occ preview:cleanup

preview:cleanup تمام پیش‌نمایش‌های تولیدشده را حذف می‌کند و Nextcloud با باز کردن فایل‌ها توسط کاربران، آن‌ها را دوباره تولید می‌کند؛ بنابراین فضا به‌تدریج بازمی‌گردد و هزینهٔ آن از نظر پردازشی (CPU) پرداخت می‌شود. اگر این حجم تنها بخشی از یک مشکل دیسکی گسترده‌تر باشد، تصاویر قدیمی و کش ساخت‌وساز (build cache) بلااستفاده معمولاً بخش دیگر آن هستند.

چرا فایل‌هایی که روی host کپی می‌کنم در Nextcloud نمایش داده نمی‌شوند؟

زیرا Nextcloud کش فایل‌های خود را از پایگاه‌داده می‌خواند، نه از دایرکتوری. کپی کردن شما باعث ایجاد فایلی روی دیسک شده که ردیف متناظری در پایگاه‌داده ندارد، بنابراین رابط وب چیزی برای نمایش دادن ندارد. مستندات دقیقاً به همین مورد اشاره کرده‌اند: پس از کپی مستقیم فایل‌ها در دایرکتوری data، نیاز به اجرای یک scan است.

docker exec -it nextcloud occ files:scan --path="/alice/files/Photos"
docker exec -it nextcloud occ files:scan --unscanned -v
docker exec -it nextcloud occ files:scan --all

آرگومان --path ساختار داخل دایرکتوری data را نیز نشان می‌دهد: هر کاربر پوشه‌ای به نام کاربری خود دارد و files در داخل آن، محتوایی را که در رابط وب می‌بینند نگه می‌دارد. وقتی می‌دانید فایل‌ها کجا قرار گرفته‌اند، یک مسیر مشخص را اسکن کنید. دستور --all تمام کاربران را بررسی می‌کند و در نمونه‌های بزرگ، زمان زیادی می‌برد. دستور --unscanned فقط فایل‌هایی را بررسی می‌کند که هنوز به‌طور کامل اسکن نشده‌اند. دستور -v هر فایل را در حین پردازش چاپ می‌کند؛ این تفاوت بین دستوری است که به نظر می‌رسد متوقف شده و دستوری است که می‌توانید روند آن را مشاهده کنید.

مالکیت فایل تعیین می‌کند که آیا اسکن کافی است یا خیر. فایلی که کاربر container اجازه نوشتن در آن را نداشته باشد، ایندکس می‌شود اما هنگام جابه‌جایی با خطا مواجه می‌شود؛ بنابراین لیست فایل‌ها درست به نظر می‌رسد، اما تغییر نام یا حذف آن از طریق رابط وب با شکست مواجه خواهد شد.

چرا پس از تنظیم PUID و PGID، عملیات نوشتن با خطا مواجه می‌شود؟

دلیل این است که هسته سیستم‌عامل (kernel) اعداد را مقایسه می‌کند، نه نام‌ها را. PUID و PGID شناسه عددی کاربر (uid) و شناسه گروه (gid) را تعیین می‌کنند که فرآیند کانتینر با آن اجرا می‌شود. هر فایل روی میزبان (host) نیز یک مالک عددی دارد. هنگامی که این دو عدد با هم متفاوت باشند، عملیات نوشتن رد می‌شود؛ فارغ از اینکه نام‌ها در هر دو سمت چگونه به نظر می‌رسند.

docker exec -it nextcloud id abc
sudo ls -ln /var/lib/docker/volumes/nextcloud_nextcloud_data/_data

دستور id abc، شناسه uid و gid که کانتینر واقعاً از آن استفاده می‌کند (همان PUID و PGID تنظیم‌شده) را چاپ می‌کند. دستور ls -ln مالکان عددی را چاپ می‌کند و استفاده از -n اهمیت دارد: دستور ls -l ساده، آن اعداد را از طریق لیست کاربران میزبان ترجمه می‌کند و نامی را نشان می‌دهد که داخل کانتینر هیچ معنایی ندارد. این دو عدد را با هم مقایسه کنید.

سپس به‌جای حدس زدن، عملیات نوشتن را تست کنید.

docker exec -u abc -it nextcloud touch /data/writetest

یک دستور Permission denied که نام /data را مشخص می‌کند، تأییدکننده است. مالکیت را از داخل کانتینر اصلاح کنید و سپس همان تست را دوباره اجرا کنید.

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

این کار را به دلیلی از داخل انجام دهید. در Docker بدون دسترسی ریشه (rootless)، شناسه کاربران کانتینر از طریق محدوده فرعی در /etc/subuid نگاشت (map) می‌شوند؛ بنابراین uid 1000 داخل کانتینر به یک uid بسیار بزرگ‌تر روی میزبان تعلق دارد. در نتیجه، یک دستور chown 1000:1000 در سمت میزبان، مالکی را تعیین می‌کند که کانتینر نمی‌تواند از آن استفاده کند و عملیات نوشتن همچنان با خطا مواجه می‌شود. اجرای دستور chown در داخل کانتینر، از همان نگاشتی عبور می‌کند که خود فرآیند Nextcloud از آن استفاده می‌کند، بنابراین اعداد به‌طور خودکار با هم منطبق می‌شوند. به همین دلیل است که پیش از عیب‌یابی هر مورد دیگری، PUID و PGID باید با مالک روی دیسک مطابقت داشته باشند.

چگونه بک‌آپ بگیرم تا بازیابی واقعاً کار کند؟

پایگاه داده و پوشه‌ها را از یک لحظهٔ زمانی یکسان تهیه کنید. حالت نگهداری (maintenance mode) ورود کاربران را متوقف می‌کند، بنابراین هیچ فایلی بین زمان dump گرفتن و کپی کردن پوشه‌ها بارگذاری نمی‌شود.

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

به آنچه در دستور dump وجود ندارد دقت کنید: فلگ -t. یک TTY انتهای خطوط را بازنویسی می‌کند و فایل SQL dump که از آن عبور کرده باشد، به شکلی خراب می‌شود که تنها هنگام بازیابی متوجه آن خواهید شد. همچنین توجه داشته باشید که رمز عبور در خط فرمان در خروجی ps هنگام اجرای دستور قابل مشاهده است، بنابراین آن را از فایل .env خود به درون shell بخوانید و از تایپ کردن آن خودداری کنید. ایمیج‌های قدیمی‌تر پایگاه داده به جای mariadb-dump از mysqldump استفاده می‌کنند و راهنما هر دو را مستند کرده است.

برای بازیابی، dump را در یک پایگاه داده خالی بارگذاری کنید، هر دو آرشیو را در volumeهای جدید باز کنید، کانتینرها را استارت بزنید و سپس حالت نگهداری را خاموش کنید. اگر پوشه‌ها و dump از لحظات زمانی متفاوتی باشند، کش فایل و دیسک با هم همخوانی نخواهند داشت و occ files:scan --all تنها یک جهت را تعمیر می‌کند. این ابزار فایل‌هایی را پیدا می‌کند که بدون ردیف (row) در پایگاه داده وجود دارند، اما نمی‌تواند فایلی را که یک ردیف به آن اشاره دارد اما وجود ندارد، بازگرداند.

نسخهٔ پشتیبان را خارج از سرور نگه دارید. نسخه‌ای که درون همان VPS قرار دارد، با از بین رفتن VPS نابود می‌شود؛ به همین دلیل است که استفاده از restic برای مخزن خارج از سرور باید در این چرخه گنجانده شود و اسنپ‌شات ارائه‌دهنده سرویس ابزاری متفاوت از بک‌آپ است. اگر هنوز در حال ساخت stack هستید، نصب کامل Nextcloud روی یک VPS مباحث مربوط به reverse proxy و گواهی TLS (امنیت لایه انتقال) را که در این راهنما پوشش داده نشده‌اند، توضیح می‌دهد.

FAQ

دایرکتوری داده‌های Nextcloud در کانتینر Docker کجا قرار دارد؟

در ایمیج linuxserver.io، این مسیر داخل کانتینر /data است و نصب با config.php در /config قرار دارد. این‌ها مسیرهای داخل کانتینر هستند. برای یافتن مسیر روی میزبان (host)، دستور docker inspect nextcloud را اجرا کرده و مقدار Source را در بخش Mounts بخوانید، یا دستور docker volume inspect را روی volume اجرا کرده و Mountpoint را بررسی کنید. سایر ایمیج‌های Nextcloud از مسیرهای متفاوتی استفاده می‌کنند، بنابراین مستندات تگ مورد استفاده خود را بررسی کرده و با دستور docker exec -it nextcloud occ config:system:get datadirectory آن را تأیید کنید.

چرا فایل‌هایی که در volume کپی می‌کنم در Nextcloud نمایش داده نمی‌شوند؟

Nextcloud به جای خواندن مستقیم دایرکتوری، ردیف‌های مربوط به فایل‌ها را از کشِ موجود در دیتابیس می‌خواند؛ بنابراین فایلی که بدون عبور از Nextcloud اضافه شود، ردیفی ندارد و دیده نمی‌شود. برای یک پوشه دستور docker exec -it nextcloud occ files:scan --path="/alice/files/Photos" و برای تمام کاربران دستور occ files:scan --all را اجرا کنید. اگر فایل‌ها ظاهر شدند اما امکان جابه‌جایی یا حذف آن‌ها وجود ندارد، مشکل از مالکیت (ownership) است: کاربر کانتینر باید دسترسی نوشتن روی آن‌ها را داشته باشد.

آیا کپی گرفتن از volume داده‌ها برای بازیابی Nextcloud کافی است؟

خیر. volume داده‌ها فقط محتوای فایل‌ها را نگه می‌دارد. دیتابیس شامل ایندکس فایل‌ها، کاربران و اشتراک‌گذاری‌ها است و config.php نیز اطلاعات ورود به دیتابیس و شناسه instance را در خود دارد. برای بازیابی کامل، به پوشه داده‌ها، پوشه پیکربندی، دیتابیس و در صورت استفاده، پوشه‌های برنامه‌ها و تم‌های سفارشی نیاز دارید. از همه این موارد در یک لحظه زمانی مشخص کپی بگیرید، زیرا اگر دیتابیس جدیدتر از فایل‌ها باشد، به فایل‌هایی اشاره می‌کند که وجود ندارند.

چرا حجم volume داده‌های من بسیار بیشتر از فایل‌هایی است که کاربران می‌بینند؟

پیش‌نمایش‌ها (previews)، فایل‌های حذف‌شده و نسخه‌های قدیمی در همان volume ذخیره می‌شوند و هیچ‌کدام در حجم نمایش‌داده‌شده به کاربر محاسبه نمی‌شوند. با دستور docker exec -it nextcloud sh -c 'du -sh /data/*' فضا را اندازه‌گیری کنید. سطل زباله به‌صورت پیش‌فرض فایل‌های حذف‌شده را تا 30 روز نگه می‌دارد و تنها در صورت نیاز به فضا آن‌ها را زودتر پاک می‌کند؛ همچنین برنامه Versions می‌تواند تا نیمی از فضای خالی فعلی کاربر را اشغال کند. با دستورات occ trashbin:cleanup --all-users، occ versions:cleanup alice و occ preview:cleanup آن‌ها را پاکسازی کنید؛ توجه داشته باشید که با باز کردن فایل‌ها توسط کاربران، پیش‌نمایش‌ها دوباره ایجاد خواهند شد.

آیا می‌توانم دایرکتوری داده‌های Nextcloud را به دیسک دیگری منتقل کنم؟

به جای تغییر مسیری که Nextcloud می‌شناسد، مکان جدید را روی همان مسیر داخل کانتینر mount کنید. کانتینر را متوقف کنید، محتویات قدیمی را با حفظ مالکیت (cp -a یا rsync -aAX) به دیسک جدید منتقل کنید، در فایل compose خود volume یا bind mount را به مکان جدید اشاره دهید و سپس کانتینر را دوباره اجرا کنید. Nextcloud همچنان /data را می‌بیند، بنابراین نیازی به تغییر هیچ ردیفی در دیتابیس نیست. با دستور docker exec -it nextcloud occ config:system:get datadirectory و یک آپلود تستی، صحت عملکرد را بررسی کنید.