رفع مشکلات overlay2 و Docker Storage؛ خطای فضا، inode و Storage Driver

اگر Docker با خطاهایی مثل no space left on device، مشکل Mount شدن لایه‌های overlay2، رشد غیرعادی پوشه /var/lib/docker، کمبود inode یا خطا هنگام Start شدن Container روبه‌رو شده است، قبل از حذف فایل‌های داخل پوشه Docker باید علت اصلی را پیدا کنید. پاک‌کردن دستی فایل‌های overlay2 می‌تواند Imageها و Containerها را خراب کند و حتی باعث از دست رفتن داده شود.

overlay2 در Docker چیست؟

overlay2 یکی از Storage Driverهای کلاسیک Docker در لینوکس است. Docker برای نگهداری لایه‌های Image و Writable Layer مربوط به Container از Storage Driver استفاده می‌کند.

در OverlayFS چند لایه روی یکدیگر قرار می‌گیرند. به‌صورت ساده، لایه‌های فقط‌خواندنی Image در پایین قرار دارند و تغییرات Container در یک لایه قابل‌نوشتن ذخیره می‌شوند.

داخل ساختار OverlayFS معمولاً با این مفاهیم روبه‌رو می‌شوید:

قبل از هر کاری ببینید Docker واقعاً از overlay2 استفاده می‌کند یا نه

روی سرورهای جدید نباید صرفاً بر اساس وجود پوشه overlay2 نتیجه بگیرید که Backend فعلی Docker همین است. دستور زیر را اجرا کنید:

docker info

در خروجی دنبال بخش Storage بگردید. در سیستم‌هایی که Storage Driver کلاسیک فعال است ممکن است ببینید:

Storage Driver: overlay2
Backing Filesystem: extfs

یا روی XFS:

Storage Driver: overlay2
Backing Filesystem: xfs
Supports d_type: true

مشکلات رایج overlay2 و Docker Storage

بیشتر خطاهایی که مدیران سرور به overlay2 نسبت می‌دهند در یکی از دسته‌های زیر قرار می‌گیرند:

مرحله ۱: فضای دیسک را بررسی کنید

یکی از رایج‌ترین خطاهای Docker Storage این پیام است:

no space left on device

اول فضای فایل‌سیستم را بررسی کنید:

df -h

اگر پارتیشنی که /var/lib/docker روی آن قرار دارد نزدیک ۱۰۰٪ باشد، احتمالاً علت اصلی را پیدا کرده‌اید.

محل واقعی Docker Data Root را هم ببینید:

docker info | grep "Docker Root Dir"

مرحله ۲: inodeها را بررسی کنید

گاهی df -h نشان می‌دهد هنوز چند گیگابایت فضای آزاد دارید اما Docker همچنان خطای no space left on device می‌دهد. در این شرایط ممکن است inodeها تمام شده باشند.

df -i

اگر مقدار IUse% روی پارتیشن Docker نزدیک ۱۰۰٪ باشد، فایل‌سیستم دیگر نمی‌تواند فایل جدید بسازد؛ حتی اگر از نظر حجم فضای خالی وجود داشته باشد.

وجود تعداد بسیار زیاد فایل کوچک در Cache، Log یا لایه‌های Docker می‌تواند باعث این وضعیت شود.

مرحله ۳: ببینید Docker چقدر فضا مصرف کرده است

Docker ابزار داخلی برای بررسی مصرف دیسک دارد:

docker system df

برای جزئیات بیشتر:

docker system df -v

این خروجی کمک می‌کند بفهمید فضای دیسک بیشتر توسط کدام بخش مصرف شده است:

مرحله ۴: حجم واقعی پوشه Docker را بررسی کنید

اگر Docker از Data Root پیش‌فرض استفاده می‌کند، حجم کلی آن را مشاهده کنید:

sudo du -sh /var/lib/docker

برای دیدن مصرف زیرپوشه‌ها:

sudo du -h --max-depth=1 /var/lib/docker | sort -h

ممکن است پوشه‌هایی مانند overlay2، containers، volumes یا Build Cache سهم زیادی داشته باشند.

مرحله ۵: Imageهای بلااستفاده را بررسی کنید

docker image ls

برای پاک‌سازی Imageهای dangling می‌توانید از فرمان رسمی Docker استفاده کنید:

docker image prune

Docker قبل از حذف از شما تأیید می‌گیرد.

استفاده از گزینه -a دامنه حذف را گسترده‌تر می‌کند:

docker image prune -a

این دستور Imageهایی را که Container موجودی به آن‌ها وابسته نیست حذف می‌کند. قبل از اجرا خروجی Imageها و وابستگی پروژه‌ها را بررسی کنید.

مرحله ۶: Build Cache را پاک‌سازی کنید

اگر روی سرور مرتب Image می‌سازید، Build Cache می‌تواند حجم قابل‌توجهی اشغال کند.

docker builder prune

اگر می‌خواهید Cache بیشتری پاک شود:

docker builder prune -a

گزینه -a Build Cache بلااستفاده بیشتری را حذف می‌کند و Build بعدی ممکن است دوباره نیاز به دانلود یا ساخت بعضی Layerها داشته باشد.

مرحله ۷: از docker system prune با احتیاط استفاده کنید

فرمان زیر چند نوع Object بلااستفاده Docker را به‌صورت یکجا پاک می‌کند:

docker system prune

این فرمان می‌تواند Containerهای متوقف‌شده، Networkهای بلااستفاده، Imageهای dangling و Build Cache بلااستفاده را حذف کند.

مرحله ۸: Logهای Docker را بررسی کنید

گاهی overlay2 متهم اصلی نیست و در واقع Log یک Container کل دیسک را پر کرده است.

در حالت پیش‌فرض بسیاری از نصب‌ها، Docker از Logging Driver نوع json-file استفاده می‌کند. ابتدا Driver فعلی را بررسی کنید:

docker info --format '{{.LoggingDriver}}'

برای پیدا کردن فایل‌های بزرگ داخل دایرکتوری Containerها می‌توانید صرفاً اندازه آن‌ها را مشاهده کنید:

sudo du -h /var/lib/docker/containers/*/*-json.log 2>/dev/null | sort -h | tail

اگر Logها چندین گیگابایت شده‌اند، بهتر است Log Rotation را برای Containerهای جدید تنظیم کنید.

تنظیم Log Rotation

می‌توانید در /etc/docker/daemon.json محدودیت Log قرار دهید. اگر این فایل از قبل وجود دارد، تنظیمات جدید را با JSON موجود ادغام کنید و فایل را بازنویسی کورکورانه نکنید.

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

قبل از Restart کردن Docker، JSON را بررسی کنید:

python3 -m json.tool /etc/docker/daemon.json

سپس:

sudo systemctl restart docker

توجه کنید تنظیم Logging پیش‌فرض جدید معمولاً روی Containerهایی که بعداً ساخته می‌شوند اعمال می‌شود؛ Containerهای موجود ممکن است نیاز به Recreation داشته باشند.

مرحله ۹: روی XFS مقدار ftype را بررسی کنید

اگر Backing Filesystem شما XFS است، overlay2 به قابلیت d_type=true نیاز دارد که معمولاً در خروجی XFS با ftype=1 مشخص می‌شود.

ابتدا Mount مربوط به Docker را پیدا کنید:

df -T /var/lib/docker

اگر XFS است:

sudo xfs_info /var/lib/docker

در خروجی باید ftype=1 وجود داشته باشد.

مرحله ۱۰: خطاهای mount overlay را از Logهای Docker بخوانید

اگر Docker Start نمی‌شود یا Container با خطای mount متوقف می‌شود، Log سرویس Docker یکی از بهترین منابع تشخیص است.

sudo systemctl status docker --no-pager

سپس Logهای اخیر:

sudo journalctl -u docker -n 200 --no-pager

به عبارت‌هایی مانند موارد زیر توجه کنید:

خود متن خطا مشخص می‌کند که باید سمت دیسک، inode، فایل‌سیستم، Storage Driver یا Layerهای Docker بررسی را ادامه دهید.

مرحله ۱۱: آیا فایل‌سیستم Read-only شده است؟

اگر Docker ناگهان قادر به نوشتن نیست و خطاهای read-only file system می‌بینید، ممکن است مشکل از خود فایل‌سیستم میزبان باشد و نه overlay2.

Mountها را بررسی کنید:

mount | grep -E ' / |/var/lib/docker'

همچنین پیام‌های Kernel را بررسی کنید:

sudo dmesg | tail -n 100

خطاهای I/O، EXT4، XFS یا Block Device را جدی بگیرید. در این سناریو Restart مکرر Docker راه‌حل اصلی نیست.

مرحله ۱۲: داده‌های حجیم را داخل Writable Layer نگه ندارید

Writable Layer Container برای نگهداری دائمی دیتابیس، فایل‌های آپلودی یا داده‌های بزرگ انتخاب مناسبی نیست. برای داده ماندگار از Docker Volume یا Bind Mount مناسب استفاده کنید.

برای مثال یک دیتابیس نباید بدون Volume به این شکل اجرا شود:

docker run -d postgres

یک نمونه ساده با Volume:

docker volume create postgres-data

docker run -d \
  --name postgres-db \
  -v postgres-data:/var/lib/postgresql/data \
  postgres

در محیط Production باید علاوه بر Volume، Backup منظم دیتابیس نیز داشته باشید؛ Volume به‌تنهایی Backup محسوب نمی‌شود.

مرحله ۱۳: تغییر Docker Data Root در صورت کمبود فضای دیسک

اگر پارتیشن Root کوچک است ولی یک دیسک یا Mount جداگانه با فضای کافی دارید، می‌توانید Docker Data Root را به محل دیگری منتقل کنید.

ابتدا Docker را متوقف کنید:

sudo systemctl stop docker

یک مسیر جدید ایجاد کنید. در این مثال دیسک جدید از قبل روی /mnt/docker-data Mount شده است:

sudo mkdir -p /mnt/docker-data

داده‌ها را با حفظ ویژگی‌های فایل منتقل کنید. برای Migration واقعی بهتر است ابتدا Backup جداگانه داشته باشید:

sudo rsync -aHAXx /var/lib/docker/ /mnt/docker-data/

سپس daemon.json را بررسی کنید:

sudo nano /etc/docker/daemon.json

اگر فایل خالی است، نمونه پایه:

{
  "data-root": "/mnt/docker-data"
}

اگر فایل از قبل تنظیمات دیگری دارد، مقدار data-root را با حفظ JSON موجود اضافه کنید.

JSON را بررسی کنید:

python3 -m json.tool /etc/docker/daemon.json

سپس Docker را Start کنید:

sudo systemctl start docker

محل جدید را تأیید کنید:

docker info | grep "Docker Root Dir"

مرحله ۱۴: چرا نباید /var/lib/docker/overlay2 را دستی پاک کنیم؟

دایرکتوری overlay2 مجموعه‌ای از Layerهایی است که Docker ارتباط میان آن‌ها را در Metadata خود نگهداری می‌کند. نام پوشه‌ها معمولاً برای مدیر سرور معنای مستقیمی ندارند.

فرمانی مانند نمونه زیر راه‌حل پاک‌سازی Docker نیست:

rm -rf /var/lib/docker/overlay2/*

این دستور را اجرا نکنید. ممکن است بخش مهمی از Imageها، Layerها و Containerها را از بین ببرد.

مرحله ۱۵: تغییر Storage Driver چه خطری دارد؟

تغییر Storage Driver از overlay2 به Driver دیگر عملیات ساده‌ای مثل تغییر Theme نیست. Docker اعلام می‌کند با تغییر Storage Driver، Imageها و Containerهای ساخته‌شده با Driver قبلی در Backend جدید قابل دسترسی نیستند.

بنابراین قبل از Migration باید:

روش سریع تشخیص مشکلات Docker Storage

ترتیب پیشنهادی عیب‌یابی بدون ریسک

مرحله ۱: با docker info Storage Backend را مشخص کنید.

مرحله ۲: با df -h فضای دیسک را بررسی کنید.

مرحله ۳: با df -i inode را بررسی کنید.

مرحله ۴: با docker system df -v مصرف داخلی Docker را ببینید.

مرحله ۵: Logهای Container را بررسی کنید.

مرحله ۶: Build Cache و Imageهای بلااستفاده را شناسایی کنید.

مرحله ۷: Log سرویس Docker را بررسی کنید.

مرحله ۸: در XFS، وضعیت ftype را بررسی کنید.

مرحله ۹: اگر مشکل دیسک ادامه دارد، Data Root یا ظرفیت Storage را بررسی کنید.

پرسش‌های متداول

آیا حذف پوشه overlay2 برای خالی کردن فضای Docker درست است؟

خیر. فایل‌های این پوشه بخشی از Layerهای Docker هستند و حذف دستی آن‌ها می‌تواند Image و Containerها را خراب کند. برای پاک‌سازی از فرمان‌های رسمی Docker استفاده کنید.

چرا overlay2 چند ده گیگابایت شده است؟

ممکن است تعداد Imageها زیاد باشد، Containerها داده زیادی در Writable Layer نوشته باشند یا Build Cache رشد کرده باشد. ابتدا docker system df -v را بررسی کنید.

چرا Docker می‌گوید دیسک پر است ولی df -h فضای خالی نشان می‌دهد؟

یکی از دلایل مهم تمام‌شدن inodeهاست. خروجی df -i را بررسی کنید.

آیا docker system prune اطلاعات دیتابیس را پاک می‌کند؟

فرمان پایه docker system prune Volumeها را به‌صورت پیش‌فرض پاک نمی‌کند، اما Objectهای بلااستفاده دیگری را حذف می‌کند. استفاده از گزینه‌های اضافی مانند –volumes نیازمند بررسی دقیق‌تر است.

برای دیتابیس بهتر است overlay2 استفاده شود یا Volume؟

داده ماندگار دیتابیس بهتر است روی Docker Volume یا Storage مناسب قرار گیرد و داخل Writable Layer Container نگهداری نشود.

آیا Docker Engine 29 همچنان overlay2 دارد؟

overlay2 همچنان برای نصب‌هایی که از Storage Driver کلاسیک استفاده می‌کنند وجود دارد، اما Docker Engine 29.0 و جدیدتر در نصب تازه به‌طور پیش‌فرض از containerd image store استفاده می‌کند. به همین دلیل همیشه ابتدا خروجی docker info را بررسی کنید.

منابع رسمی

🔹 مستندات رسمی Docker درباره OverlayFS و overlay2

🔹 راهنمای انتخاب Docker Storage Driver

🔹 مستندات docker system df

🔹 راهنمای رسمی پاک‌سازی Objectهای بلااستفاده Docker

🔹 مستندات مدیریت Logging در Docker