اگر فضای دیسک سرور بعد از اجرای مکرر docker build کم شده است، ابتدا با docker system df و docker buildx du مشخص کنید چه مقدار فضا واقعاً به Build Cache تعلق دارد؛ سپس فقط کش قابل‌بازیابی Builder موردنظر را با فیلتر سن پاک‌سازی کنید. اجرای کورکورانه docker system prune --volumes یا حذف دستی /var/lib/docker راهکار امنی نیست و می‌تواند داده‌های مهم را به خطر بیندازد.
سناریو و پیش‌نیازهای بررسی
فرض کنید روی یک VPS لینوکسی، Pipeline استقرار هر روز چند Image می‌سازد و با وجود حذف Imageهای قدیمی، فضای دیسک همچنان کاهش می‌یابد. BuildKit لایه‌ها و خروجی‌های موقت را برای سرعت ساخت بعدی نگه می‌دارد. این فضا با لاگ کانتینر و Volume دیتابیس فرق دارد؛ برای سناریوی لاگ، راهنمای جلوگیری از پر شدن دیسک با لاگ Docker را بخوانید.
دسترسی SSH و مجوز اجرای Docker، آگاهی از Builder مورد استفاده و یک بازه نگهداری برای کش لازم است. قبل از هر پاک‌سازی، از داده‌های پایدار بکاپ بگیرید و عملیات را خارج از زمان Buildهای مهم انجام دهید. خروجی دستورهای تشخیصی را برای مقایسه قبل و بعد ذخیره کنید.
date -Is
df -h
df -i
docker version
docker buildx ls
docker system df
docker system df -vاگر df -i کمبود inode را نشان می‌دهد، پاک‌سازی کش شاید تنها بخشی از مسئله باشد. همچنین اگر فضای مصرف‌شده مربوط به Volume است، آن را با Build Cache اشتباه نگیرید؛ توضیح تفاوت‌ها در آموزش Docker Volume و Bind Mount آمده است.
مرحله اول: مصرف واقعی Build Cache را اندازه بگیرید
docker buildx ls
docker buildx du
docker system df -vدر خروجی docker buildx du به ستون‌های SIZE، RECLAIMABLE و LAST ACCESSED توجه کنید. گزینه RECLAIMABLE=false یعنی رکورد در حال استفاده است و حتی پاک‌سازی گسترده نیز لزوماً آن را حذف نمی‌کند. ممکن است چند Builder مستقل داشته باشید؛ ابتدا Builder فعال و هدف را با docker buildx ls شناسایی کنید.
مرحله دوم: پاک‌سازی کنترل‌شده کش قدیمی
در یک بازه تعمیراتی، ابتدا فقط رکوردهای کش قدیمی Builder انتخاب‌شده را هدف بگیرید. until=168h به رکوردهایی اشاره می‌کند که بر اساس معیار زمانی دستور، بیش از هفت روز از آخرین استفاده‌شان گذشته است. در نسخه و Driver نصب‌شده خود، خروجی و رفتار فیلتر را بررسی کنید.
docker buildx prune --filter "until=168h"دستور بدون --force تأیید تعاملی می‌خواهد. قبل از تأیید، Builder و فیلتر را دوباره بررسی کنید. پاک‌شدن کش معمولاً Imageهای در حال استفاده و Volumeهای برنامه را حذف نمی‌کند، اما Buildهای بعدی ممکن است به دانلود یا بازسازی لایه‌ها نیاز داشته باشند و زمان بیشتری ببرند.
مرحله سوم: اگر فضای آزاد کافی نشد
فقط بعد از اطمینان از اینکه فضای مصرفی مربوط به کش Builder است، محدودیت نگهداری را متناسب با ظرفیت دیسک تنظیم کنید. دستور زیر یک نمونه با سقف فضای مورد استفاده کش است؛ عدد ۵ گیگابایت باید بر اساس اندازه پروژه تغییر کند:
docker buildx prune --max-used-space 5gbاین گزینه بر فضای نگهداری کش اثر می‌گذارد، نه بر حجم کل Docker یا فایل‌های سیستم‌عامل. از --all و به‌خصوص docker system prune -a --volumes به‌عنوان اولین اقدام استفاده نکنید؛ این‌ها دامنه پاک‌سازی متفاوتی دارند و می‌توانند منابعی را حذف کنند که قصد حذفشان را نداشته‌اید.
مرحله چهارم: Garbage Collection خودکار BuildKit
BuildKit دارای سیاست‌های Garbage Collection است و در بسیاری از نصب‌ها تنظیم پیش‌فرض کافی است. اگر Buildها پرتکرار هستند، به جای اجرای مکرر پاک‌سازی دستی، سیاست‌های GC مربوط به Driver خود را مطابق مستندات رسمی Docker درباره Build Garbage Collection تنظیم کنید. تنظیمات Driver نوع docker و Builder مستقل docker-container یکسان نیستند؛ قبل از تغییر فایل تنظیمات، خروجی docker buildx ls را ملاک قرار دهید.
تغییر تنظیمات Daemon یا Builder در Production ممکن است نیازمند Restart یا بازسازی Builder باشد؛ بدون بکاپ تنظیمات و برنامه Rollback آن را انجام ندهید.
مرحله پنجم: Verify بعد از پاک‌سازی
docker buildx du
docker system df
df -h
df -i
docker ps --format 'table {{.Names}}t{{.Status}}'مقایسه قبل و بعد باید کاهش فضای قابل‌بازیابی کش و بهبود فضای آزاد را نشان دهد. سپس یک Build کنترل‌شده اجرا کنید و مطمئن شوید برنامه‌ها همچنان پاسخ می‌دهند. اگر Disk Usage تغییر نکرد، احتمالاً مصرف مربوط به لاگ، Volume، فایل‌های خارج از Docker یا Builder دیگری است؛ حذف تصادفی فایل‌ها را ادامه ندهید.
تفاوت Build Cache با Image، Container و Volume
Build Cache برای تسریع ساخت مجدد Image استفاده می‌شود؛ Image خروجی ساخت است؛ Container نمونه اجرایی Image است و Volume برای داده پایدار برنامه استفاده می‌شود. حذف Volume می‌تواند داده‌های دیتابیس یا فایل‌های آپلودی را از بین ببرد. برای معماری اجرای چند سرویس و محل نگهداری داده، آموزش Docker Compose روی لینوکس کمک می‌کند.
چه زمانی ظرفیت VPS را بازبینی کنیم؟
اگر پس از تنظیم GC و حذف کش واقعاً بلااستفاده، ساخت‌های روزانه همچنان فضای دیسک را پر می‌کنند، ظرفیت SSD/NVMe، نرخ رشد Artifactها و نیاز به فضای موقت Build را در برنامه زیرساخت بررسی کنید. در چنین سناریویی مقایسه ظرفیت دیسک و منابع پلن‌های سرور مجازی وان‌سرور می‌تواند برای تصمیم درباره زیرساخت مفید باشد؛ خرید VPS جدید به‌تنهایی مشکل تنظیم اشتباه BuildKit یا انباشت کش را حل نمی‌کند.
خطاهای رایج و مسیر بازگشت
- فضا آزاد نشد: Builder اشتباه، رکوردهای در حال استفاده، لاگ یا Volume را بررسی کنید.
- Build بعدی کند شد: پس از حذف کش، بازسازی لایه‌ها طبیعی است؛ سیاست GC را ملایم‌تر کنید.
- Build هم‌زمان شکست خورد: وضعیت Pipeline و Builder را بررسی کنید و پاک‌سازی را به زمان بدون Build منتقل کنید.
- پس از تغییر تنظیمات GC مشکل ایجاد شد: نسخه پشتیبان فایل تنظیمات را برگردانید، اعتبار پیکربندی را بررسی کنید و سرویس را در بازه نگهداری بازیابی کنید.
نکته امنیتی: خروجی docker inspect و فایل‌های Build ممکن است حاوی مسیرها یا اطلاعات محرمانه باشند؛ قبل از اشتراک‌گذاری لاگ‌ها، آن‌ها را بازبینی کنید. برای دستورات و رفتار دقیق هر نسخه به مرجع رسمی docker buildx prune مراجعه کنید.