SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

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

محل دقیق دایرکتوری داده در کانتینر و مسیرهای متناظر روی هاست را پیدا کنید. برای بک‌آپ‌گیری کامل، علاوه بر فایل‌های کاربر، باید مسیر config و دیتابیس را نیز ذخیره کنید.

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

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

tag مربوط به image را ثابت نگه دارید. مسیرها به image تعلق دارند، نه به Nextcloud، و یک tag شناور ممکن است بدون اطلاع شما تغییر کند. در تاریخ November 20, 2026، نسخه پایدار فعلی image برابر با 35.0.3-ls3 است که Nextcloud 35.0.3، یعنی چهارمین release از نسخه اصلی Nextcloud 35، را شامل می‌شود. این image در هر مرحله فقط یک نسخه اصلی را ارتقا می‌دهد؛ بنابراین stackای که هنوز روی 34.x است، در یک گام به 35 منتقل می‌شود و پیش از این گام باید backup تهیه کنید.

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:

دو password از یک فایل .env در کنار فایل compose خوانده می‌شوند؛ بنابراین در خود فایل compose قرار نمی‌گیرند. در نتیجه پاسخ شامل سه volume است و فقط یکی از آن‌ها فایل‌های کاربر را نگه می‌دارد.

این مسیرهای container از مستندات همان image گرفته شده‌اند. یک image دیگر برای Nextcloud، filesystem را به شکل متفاوتی سازمان‌دهی می‌کند و installation را زیر web root مخصوص خود نگه می‌دارد؛ بنابراین مسیری که از یک پست forum کپی شده، فقط یک حدس است. واقعیت را از containerای که در حال اجرای آن هستید بخوانید.

docker inspect nextcloud

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

چگونه مسیر واقعی روی میزبان را پشت volume پیدا کنم؟

volume نام‌گذاری‌شده توسط Docker مدیریت می‌شود؛ بنابراین شما مسیر آن را انتخاب نمی‌کنید. مسیر را از Docker دریافت می‌کنید.

docker volume ls
docker volume inspect nextcloud_nextcloud_data

نام اهمیت دارد. Docker Compose نام volumeها را با نام پروژه prefix می‌کند. این نام به‌طور پیش‌فرض نام دایرکتوری حاوی فایل 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 پاسخ است. مسیر را از دستور بخوانید و آن را حدس نزنید، چون ممکن است تغییر کند. در Docker بدون root، کل ریشهٔ دادهٔ Docker به‌طور پیش‌فرض داخل home کاربری قرار دارد که daemon را اجرا می‌کند؛ بنابراین این مسیر از محل دیگری شروع می‌شود.

با bind mount این پرسش مطرح نیست. در فایل compose، - /srv/nextcloud/data:/data را بنویسید؛ در این حالت مسیر روی میزبان همان مسیری است که وارد کرده‌اید و docker inspect آن را به‌عنوان Source گزارش می‌کند. این انتخاب فقط مسیر را تغییر نمی‌دهد، زیرا volumeهای نام‌گذاری‌شده و bind mountها از نظر مالکیت و پشتیبان‌گیری رفتار متفاوتی دارند.

چرا پوشهٔ داده نسخهٔ پشتیبان نیست

راهنمای Nextcloud پنج موردی را مشخص می‌کند که نسخهٔ پشتیبان باید حفظ کند: پوشهٔ پیکربندی، پوشهٔ برنامه‌های سفارشی، پوشهٔ داده، پوشهٔ پوسته و پایگاه داده. در این image، پوشه‌های پیکربندی، برنامه‌ها و پوسته همگی در مسیر /config قرار دارند، درحالی‌که پایگاه داده در container جداگانه‌ای با volume اختصاصی خود اجرا می‌شود. اگر فقط /data را کپی کنید، کم‌اهمیت‌ترین بخش مسئله را ذخیره کرده‌اید.

پایگاه داده مهم است، چون رابط وب هیچ directoryای را فهرست نمی‌کند. این رابط ردیف‌های موجود در file cache را نمایش می‌دهد؛ به همین دلیل راهنما توصیه می‌کند پس از کپی‌کردن دستی فایل‌ها در data directory، یک scan اجرا کنید. اگر /data را در کنار پایگاه داده‌ای خالی restore کنید، byteهایی بدون index خواهید داشت: نه کاربری وجود دارد، نه shareای و نه چیزی در فهرست فایل‌ها. اگر پایگاه داده را در کنار /data خالی restore کنید، هر ردیف به فایلی اشاره می‌کند که دیگر وجود ندارد.

config.php اعتبارنامه‌های پایگاه داده و trusted domainها را نگه می‌دارد. instance id نیز در همین محل قرار دارد؛ این شناسه، پس از پیشوند گرفتن با appdata_، نام app data folder را تشکیل می‌دهد. به‌جای اعتماد به هرکدام از این مقادیر از روی حافظه، آن‌ها را از instance در حال اجرا دریافت کنید.

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

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

چه چیزی بی‌سروصدا volume داده را پر می‌کند؟

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

  • پیش‌نمایش‌ها thumbnailهای تولیدشده هستند. این فایل‌ها در پوشهٔ دادهٔ برنامه، داخل data directory، قرار دارند و نام آن‌ها با appdata_ و سپس شناسهٔ instance ساخته می‌شود.
  • فایل‌های حذف‌شده در trash باقی می‌مانند. trashbin_retention_obligation به‌طور پیش‌فرض روی auto تنظیم است؛ بنابراین وقتی فضا موجود باشد، فایل‌های حذف‌شده می‌توانند بیش از 30 روز باقی بمانند، اما هنگام نیاز به فضا نیز ممکن است پیش از 30 روز حذف شوند. فایل‌های حذف‌شده در quota عادی کاربر محاسبه نمی‌شوند، اما trash محدودیت جداگانه‌ای دارد: به‌طور پیش‌فرض حداکثر تا 50% از فضای quota باقی‌ماندهٔ کاربر، یا برای کاربری که quota ندارد، تا میزان فضای آزاد دیسک. وقتی حجم trash از این حد عبور کند، Nextcloud ابتدا قدیمی‌ترین موارد واجد شرایط را حذف می‌کند؛ این موارد، تحت auto، می‌توانند حتی کمتر از 30 روز عمر داشته باشند.
  • نسخه‌های قدیمی نیز باقی می‌مانند. versions_retention_obligation نیز به‌طور پیش‌فرض روی auto تنظیم است؛ این قابلیت به‌مرور نسخه‌ها را کاهش می‌دهد و جدیدترین نسخه را در هر بازهٔ زمانی نگه می‌دارد. اگر حداکثر مدت نگهداری تنظیم شده باشد، یک background job نسخه‌هایی را که از آن مدت گذشته‌اند یا فایل اصلی آن‌ها دیگر وجود ندارد، حذف می‌کند. برای حساب‌هایی که quota دارند، برنامهٔ Versions هدف خود را 50% از فضای quota فعلیِ آزاد کاربر قرار می‌دهد؛ برای حساب‌های بدون quota، مستقیماً از فضای آزاد filesystem استفاده می‌کند. هنگام نیاز به آزاد کردن فضا، قدیمی‌ترین نسخه‌ها را حذف می‌کند و دست‌کم 2 نسخهٔ جدیدتر را نگه می‌دارد؛ بنابراین این مقدار یک سقف سخت‌گیرانه نیست. نسخه‌ای که کاربر به‌صورت دستی نام‌گذاری کرده باشد، از انقضای خودکار مستثنا می‌شود؛ اما کاربر همچنان می‌تواند آن را به‌صورت دستی حذف کند و occ versions:cleanup نسخه‌های نام‌گذاری‌شده را همراه با سایر نسخه‌ها حذف می‌کند.

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

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

خط اول برای هر user folder و همچنین app data folder، یک عدد ارائه می‌کند. اگر مقدار app data زیاد است، زیرپوشهٔ preview را بررسی کنید؛ app data، avatarها و assetهای cache‌شده را نیز نگه می‌دارد. فرمان‌های cleanup زیر مستند هستند و هرکدام از آن‌ها عمداً داده‌ها را حذف می‌کنند.

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 همهٔ previewهای تولیدشده را حذف می‌کند. Nextcloud هنگام باز کردن فایل‌ها توسط کاربران، این previewها را دوباره تولید می‌کند؛ بنابراین فضا به‌تدریج دوباره مصرف می‌شود و هزینهٔ آن را CPU پرداخت می‌کند. اگر volume فقط بخشی از یک مشکل گسترده‌تر در دیسک است، imageهای قدیمی و build cacheهای بدون استفاده معمولاً بخش دیگر مشکل هستند.

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

زیرا Nextcloud فهرست فایل‌ها را از cache فایل در database می‌خواند، نه از directory. کپی شما فایلی روی disk ایجاد کرده است که row متناظر در database ندارد؛ بنابراین web interface چیزی برای نمایش ندارد. manual دقیقاً به همین وضعیت اشاره می‌کند: پس از کپی مستقیم فایل‌ها به data directory، باید scan اجرا شود.

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 همچنین ساختار داخل data directory را نشان می‌دهد: هر کاربر folderای با نام username خود دارد و files درون آن، فایل‌هایی را نگه می‌دارد که کاربر در web interface می‌بیند. اگر می‌دانید فایل‌ها کجا قرار گرفته‌اند، فقط همان path را scan کنید. --all همه کاربران را بررسی می‌کند و در یک instance بزرگ، زمان زیادی می‌برد. --unscanned فقط فایل‌هایی را بررسی می‌کند که هنوز به‌طور کامل scan نشده‌اند. -v هر فایل را هنگام پردازش چاپ می‌کند؛ این تفاوت میان فرمانی است که ظاهراً متوقف شده و فرمانی که می‌توانید روند اجرای آن را monitor کنید.

مالکیت فایل تعیین می‌کند که scan کافی باشد یا نه. اگر user مربوط به container نتواند روی فایلی بنویسد، فایل index می‌شود اما سپس جابه‌جا نمی‌شود؛ در نتیجه listing درست به نظر می‌رسد، ولی rename یا delete فایل از web interface شکست می‌خورد.

چرا پس از تنظیم 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 باید با مالک روی دیسک مطابقت داشته باشند.

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

پایگاه داده و پوشه‌ها را از یک لحظه یکسان تهیه کنید. حالت نگهداری ورود کاربران را متوقف می‌کند؛ بنابراین بین dump و کپی، هیچ upload جدیدی ثبت نمی‌شود.

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 چه چیزی ندارد: یک flag به نام -t. TTY پایان خط‌ها را بازنویسی می‌کند و SQL dump که از TTY عبور کرده باشد، به‌گونه‌ای خراب می‌شود که خرابی آن را فقط هنگام restore متوجه می‌شوید. همچنین توجه کنید که password در خط فرمان، هنگام اجرای command در خروجی ps قابل مشاهده است؛ خواندن آن از فایل .env در shell باعث می‌شود password را در shell history وارد نکنید، اما آرگومان گسترش‌یافته خط فرمان را مخفی نمی‌کند. imageهای قدیمی‌تر database به‌جای mariadb-dump، mysqldump را ارائه می‌کنند و manual هر دو را مستند کرده است.

برای restore، dump را در یک database خالی بارگذاری کنید، هر دو archive را در volumeهای جدید باز کنید، containerها را راه‌اندازی کنید و سپس حالت نگهداری را خاموش کنید. اگر پوشه‌ها و dump از زمان‌های متفاوتی تهیه شده باشند، file cache و disk با یکدیگر سازگار نیستند و occ files:scan --all فقط یکی از جهت‌ها را اصلاح می‌کند. این ابزار fileهایی را پیدا می‌کند که وجود دارند اما row متناظر ندارند. نمی‌تواند fileای را برگرداند که یک row به آن اشاره می‌کند.

نتیجه را خارج از server نگه دارید. کپی‌ای که داخل همان VPS قرار دارد، همراه با VPS از بین می‌رود. به همین دلیل استفاده از restic برای یک repository خارج از server باید بخشی از این فرایند باشد و snapshot ارائه‌دهنده ابزار متفاوتی با backup است. اگر هنوز در حال ساخت stack هستید، نصب کامل Nextcloud روی یک VPS، reverse proxy و گواهی TLS (transport layer security) را پوشش می‌دهد؛ مواردی که این راهنما توضیح نمی‌دهد.

FAQ

دایرکتوری دادهٔ Nextcloud در یک container از نوع Docker کجاست؟

در image مربوط به linuxserver.io، این مسیر داخل container برابر با /data است و config.php، apps و themes در مسیر /config قرار دارند. این‌ها مسیرهای container هستند. برای یافتن مسیر روی host، docker inspect nextcloud را اجرا کنید و مقدار Source را در بخش Mounts بخوانید؛ یا docker volume inspect را روی volume اجرا کنید و مقدار Mountpoint را بخوانید. سایر imageهای Nextcloud از مسیرهای متفاوتی داخل container استفاده می‌کنند. بنابراین مستندات tag‌ای را که pin کرده‌اید بررسی کنید و نتیجه را با docker exec -it nextcloud occ config:system:get datadirectory تأیید کنید.

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

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

آیا کپی یک data volume برای بازیابی Nextcloud کافی است؟

خیر. data volume محتوای فایل‌ها را نگه می‌دارد. پایگاه داده، file index را همراه با کاربران و shareها نگه می‌دارد و config.php شامل اعتبارنامه‌های پایگاه داده و instance id است. برای بازیابی موفق، به data folder، config folder، پایگاه داده و custom apps و theme folderها نیاز دارید؛ البته اگر از آن‌ها استفاده می‌کنید. همه این موارد را از یک زمان یکسان تهیه کنید، زیرا اگر پایگاه داده جدیدتر از فایل‌ها باشد، به فایل‌هایی اشاره می‌کند که وجود ندارند.

چرا data volume من بسیار بزرگ‌تر از فایل‌هایی است که کاربران می‌بینند؟

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

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

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

آیا این مقاله مفید بود؟