حذف ایمیج یا تگ ایمیج

ایمیج یا تگ خاصی محلی را حذف می‌کند و منابع مرتبط را پاک‌سازی می‌نماید.

🧩 دستور کلی

async removeAnImage(imageName, tagName = "latest")

شرح عملکرد

این متد ایمیج یا تگ مشخص شده را حذف می‌کند. شامل:

اعتبارسنجی پارامترهای ورودی (نام ایمیج، تگ)
دریافت لیست تگ‌های موجود
بررسی وجود تگ درخواستی
بررسی تضادهای وابستگی (conflict check)
حذف layer ایمیج
پاک‌سازی layer‌های غیرمورد‌استفاده
حذف رکورد از پایگاه داده
حذف دایرکتوری ایمیج اگر آخرین تگ بود
logging عملیات

مهم: اگر ایمیج وابستگی با تگ دیگر داشته باشد، حذف ناموفق خواهد بود. همچنین حذف ایمیج قابل بازگشت نیست.

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
`imageName`	String	بله	نام ایمیج (مثلاً alpine, nginx)
`tagName`	String	خیر	نام تگ (پیش‌فرض: latest)

خروجی

نوع: String

پیام موفقیت:

removed latest tag of alpine

استثناها (Errors)

InvalidRemoveImageParameters (422)

پیام: "Invalid image name or tag name format."

زمان رخ دادن: نام ایمیج یا تگ نامعتبر باشد

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "imageName": "invalid@name",
  "tagName": "latest",
  "error": "Image name contains invalid characters"
}

راهنمای حل:

نام ایمیج را بررسی کنید (فقط حروف، اعداد، '-', '_' مجاز)
تگ را بررسی کنید
فرمت صحیح: imageName:tagName یا imageName (default latest)

ListImageTagsFailure (500)

پیام: "Failed to list image tags from ImageManager."

زمان رخ دادن: خطا در دریافت لیست تگ‌های ایمیج

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageName": "alpine",
  "error": "Image service communication failed"
}

راهنمای حل:

سرویس ImageManager را بررسی کنید
اتصال registry را تأیید کنید
ایمیج موجود است یا خیر؟

ImageTagNotFound (404)

پیام: "Image tag not found."

زمان رخ دادن: تگ مشخص شده در ایمیج موجود نیست

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "imageName": "alpine",
  "tagName": "v99.0",
  "availableTags": ["latest", "3.18", "3.17"]
}

راهنمای حل:

لیست تگ‌های موجود را بررسی کنید
تگ صحیح را وارد کنید
listImages() استفاده کنید تا تگ‌ها را ببینید

ImageTagConflict (409)

پیام: "Cannot remove image tag due to dependency conflict."

زمان رخ دادن: تگ درخواستی وابستگی با تگ دیگر دارد

جزئیات:

{
  "type": "INVALID_STATE_ERROR",
  "statusCode": 409,
  "imageName": "node",
  "tagName": "latest",
  "conflictsWith": "18",
  "error": "latest has conflict with tag 18"
}

راهنمای حل:

ابتدا تگ‌های وابسته را حذف کنید
تگ‌های دیگر را بررسی کنید
وابستگی‌ها را از پایگاه داده مشاهده کنید

ImageDependencyCheckFailure (500)

پیام: "Failed to check image dependencies."

زمان رخ دادن: خطا در بررسی تضادهای وابستگی

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageName": "ubuntu",
  "tagName": "22.04",
  "error": "Dependency check failed"
}

راهنمای حل:

ImageManager را restart کنید
لاگ‌های سیستم را بررسی کنید
عملیات را دوباره تلاش کنید

RemoveImageLayerFailure (500)

پیام: "Failed to remove image layer."

زمان رخ دادن: خطا در حذف layer ایمیج

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageName": "nginx",
  "tagName": "latest",
  "error": "Layer removal operation failed"
}

راهنمای حل:

سرویس ImageManager را بررسی کنید
اجازه‌های فایل سیستم را تأیید کنید
فضای دیسک کافی است یا خیر؟

PruneLayersFailure (500)

پیام: "Failed to prune unused image layers."

زمان رخ دادن: خطا در پاک‌سازی layer‌های غیرمورد‌استفاده

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageName": "mysql",
  "tagName": "8.0",
  "error": "Prune operation failed"
}

راهنمای حل:

سرویس ImageManager را restart کنید
لاگ‌های prune را بررسی کنید
وضعیت سیستم فایل را تأیید کنید

DeleteImageRecordFailure (500)

پیام: "Failed to delete image record from database."

زمان رخ دادن: خطا در حذف رکورد از پایگاه داده

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "imageName": "postgres",
  "tagName": "15",
  "error": "Database write failed"
}

راهنمای حل:

اتصال دیتابیس را بررسی کنید
دیتابیس را restart کنید
transaction logs را بررسی کنید

RemoveImageDirectoryFailure (500)

پیام: "Failed to remove image directory."

زمان رخ دادن: خطا در حذف دایرکتوری ایمیج (آخرین تگ)

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageName": "redis",
  "error": "Directory removal operation failed"
}

راهنمای حل:

اجازه‌های فایل سیستم را بررسی کنید
فایل‌های باز شده را ببندید
دایرکتوری را دستی بررسی کنید

GenericFailure (500)

پیام: "Generic failure during image removal."

زمان رخ دادن: خطای عمومی

جزئیات:

{
  "type": "GENERIC_ERROR",
  "statusCode": 500,
  "error": "Image removal failed"
}

راهنمای حل:

سیستم لاگ را بررسی کنید
تمام سرویس‌ها را restart کنید
دوباره تلاش کنید

مثال‌های استفاده

مثال 1: حذف تگ پیش‌فرض (latest)

const K3Core = require('k3-core');

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.imageCore.removeAnImage('alpine');
    console.log(result);
    // Output: removed latest tag of alpine
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 2: حذف تگ خاص

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.imageCore.removeAnImage('node', '18');
    console.log(result);
    // Output: removed 18 tag of node
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: حذف تگ و بررسی پیام

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.imageCore.removeAnImage('nginx', 'dev');
    
    if (result.includes('image directory also removed')) {
      console.log('تمام ایمیج حذف شد');
    } else {
      console.log('فقط تگ حذف شد');
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 4: حذف چند تگ

(async () => {
  const k3 = new K3Core();
  
  const tags = ['dev', '1.0', '1.1'];
  
  for (const tag of tags) {
    try {
      const result = await k3.imageCore.removeAnImage('app', tag);
      console.log(`✓ ${result}`);
    } catch (error) {
      if (error.type === 'CONFLICT') {
        console.log(`✗ ${tag} وابستگی دارد: ${error.message}`);
      } else if (error.type === 'NOT_FOUND') {
        console.log(`✗ ${tag} پیدا نشد`);
      } else {
        console.log(`✗ خطا: ${error.message}`);
      }
    }
  }
})();

مثال 5: حذف با بررسی تگ‌های موجود

(async () => {
  const k3 = new K3Core();
  const imageName = 'ubuntu';
  const tagToRemove = '20.04';
  
  try {
    // بررسی تگ‌های موجود
    const images = await k3.imageCore.listImages({ image: imageName });
    
    const tagExists = images.some(img => img.Tag === tagToRemove);
    
    if (!tagExists) {
      console.log(`تگ ${tagToRemove} برای ${imageName} موجود نیست`);
      console.log('تگ‌های موجود:');
      images.forEach(img => console.log(`  - ${img.Tag}`));
      return;
    }
    
    // حذف تگ
    const result = await k3.imageCore.removeAnImage(imageName, tagToRemove);
    console.log(result);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: حذف ایمیج کامل (تمام تگ‌ها)

(async () => {
  const k3 = new K3Core();
  const imageName = 'old-service';
  
  try {
    // دریافت تمام تگ‌ها
    const images = await k3.imageCore.listImages({ image: imageName });
    
    if (images.length === 0) {
      console.log('ایمیج موجود نیست');
      return;
    }
    
    console.log(`حذف ${images.length} تگ از ${imageName}...`);
    
    // حذف همه تگ‌ها
    for (const img of images) {
      try {
        const result = await k3.imageCore.removeAnImage(imageName, img.Tag);
        console.log(`✓ ${result}`);
      } catch (error) {
        console.log(`✗ خطا در حذف ${img.Tag}: ${error.message}`);
      }
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 8: حذف نوبتی و logging

(async () => {
  const k3 = new K3Core();
  
  const removeLog = [];
  
  try {
    // حذف تگ‌های dev قدیمی
    const devTags = ['dev', 'dev-1.0', 'dev-1.1'];
    
    for (const tag of devTags) {
      try {
        const result = await k3.imageCore.removeAnImage('app', tag);
        removeLog.push({
          status: 'success',
          tag: tag,
          message: result,
          timestamp: new Date()
        });
        console.log(`✓ ${tag}: ${result}`);
      } catch (error) {
        removeLog.push({
          status: 'failed',
          tag: tag,
          error: error.message,
          timestamp: new Date()
        });
        console.log(`✗ ${tag}: ${error.message}`);
      }
    }
    
    // گزارش نهایی
    console.log('\nخلاصه:');
    const successful = removeLog.filter(log => log.status === 'success').length;
    const failed = removeLog.filter(log => log.status === 'failed').length;
    console.log(`  موفق: ${successful}`);
    console.log(`  ناموفق: ${failed}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

الگوهای خطا و راهنمای حل

الگو 1: تگ پیدا نشد

خطا: ImageTagNotFound (404)

راهنمای حل:

try {
  await k3.imageCore.removeAnImage('alpine', 'v99.0');
} catch (error) {
  if (error.type === 'NOT_FOUND') {
    console.log('تگ موجود نیست');
    
    // دریافت تگ‌های موجود
    const images = await k3.imageCore.listImages({ image: 'alpine' });
    console.log('تگ‌های موجود:');
    images.forEach(img => console.log(`  - ${img.Tag}`));
    
    // حذف تگ درست
    if (images.length > 0) {
      await k3.imageCore.removeAnImage('alpine', images[0].Tag);
    }
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 2: تضاد وابستگی

خطا: ImageTagConflict (409)

راهنمای حل:

const removeImageSafely = async (imageName, tagName) => {
  try {
    const result = await k3.imageCore.removeAnImage(imageName, tagName);
    return { success: true, message: result };
  } catch (error) {
    if (error.type === 'CONFLICT') {
      console.log(`${tagName} وابستگی با تگ‌های دیگر دارد`);
      
      // دریافت همه تگ‌ها
      const images = await k3.imageCore.listImages({ image: imageName });
      console.log('سفارش حذف:');
      
      // حذف تگ‌های وابسته اول
      for (const img of images) {
        if (img.Tag !== tagName) {
          try {
            await k3.imageCore.removeAnImage(imageName, img.Tag);
            console.log(`  ✓ حذف شد: ${img.Tag}`);
          } catch (e) {
            console.log(`  ✗ نتوانست: ${img.Tag}`);
          }
        }
      }
      
      // سپس تگ اصلی
      const finalResult = await k3.imageCore.removeAnImage(imageName, tagName);
      return { success: true, message: finalResult };
    }
    throw error;
  }
};

await removeImageSafely('node', 'latest');

الگو 3: بررسی قبل از حذف

راهنمای حل:

const removeImageWithValidation = async (imageName, tagName) => {
  try {
    // Step 1: بررسی وجود ایمیج
    const images = await k3.imageCore.listImages({ image: imageName });
    
    if (!images.some(img => img.Tag === tagName)) {
      console.log(`ایمیج ${imageName}:${tagName} موجود نیست`);
      return false;
    }
    
    // Step 2: بررسی استفاده (optional - اگر سیستم اجازه داده)
    console.log(`حذف ${imageName}:${tagName}...`);
    
    // Step 3: حذف
    const result = await k3.imageCore.removeAnImage(imageName, tagName);
    console.log(`✓ ${result}`);
    
    // Step 4: تأیید حذف
    const afterRemove = await k3.imageCore.listImages({ image: imageName, tag: tagName });
    
    if (afterRemove.length === 0) {
      console.log('تأیید: تگ با موفقیت حذف شد');
      return true;
    }
  } catch (error) {
    console.log(`✗ خطا: ${error.message}`);
    return false;
  }
};

const success = await removeImageWithValidation('nginx', 'latest');

نکات عملی

پارامترهای اعتبار‌سنجی:
- نام ایمیج: فقط حروف، اعداد، '-', '_'
- تگ: فقط حروف، اعداد، '.', '-'
- بدون فاصله یا کاراکتر خاص
وابستگی:
- اگر تگ وابستگی دارد، حذف ناموفق است
- ابتدا تگ‌های وابسته را حذف کنید
آخرین تگ:
- اگر تنها تگ باشد، دایرکتوری کامل حذف می‌شود
- بررسی دو بار قبل از حذف
Prune:
- layer‌های غیرمورد‌استفاده خودکار پاک می‌شود
- اگر prune ناموفق، حذف نتمام می‌شود
Performance:
- حذف چند تگ را sequential انجام دهید
- parallel حذف ممکن است race condition ایجاد کند
Logging:
- تمام حذف‌ها توسط سیستم log می‌شود
- برای audit، log‌ها را ذخیره کنید
Database:
- رکورد ایمیج از DB حذف می‌شود
- تاریخچه حذف در سیستم log باقی می‌ماند

دنباله عملیات

اعتبارسنجی پارامترها
دریافت لیست تگ‌های موجود
بررسی وجود تگ
بررسی تضادهای وابستگی
حذف layer ایمیج
پاک‌سازی layer‌های غیرمورد‌استفاده
حذف رکورد از DB
حذف دایرکتوری (اگر آخرین تگ)
Logging موفقیت

مرجع سریع

وضعیت	کد	توضیح
موفق	200	تگ حذف شد
پارامتر نامعتبر	422	InvalidRemoveImageParameters
تگ نیافت	404	ImageTagNotFound
تضاد وابستگی	409	ImageTagConflict
خطای ImageManager	500	ListImageTagsFailure
خطای حذف	500	RemoveImageLayerFailure
خطای DB	500	DeleteImageRecordFailure
خطای عمومی	500	GenericFailure

موارد استفاده

Cleanup Operations

const result = await removeAnImage('old-service', 'dev');
console.log(result);

Release Management

const result = await removeAnImage('app', '1.0');

Registry Maintenance

const images = await listImages({});
for (const img of images) {
  if (shouldRemove(img)) {
    await removeAnImage(img.Name, img.Tag);
  }
}

CI/CD Pipeline

// Remove old build images
await removeAnImage('build-app', 'previous-version');

نسخه: 1.3
تاریخ آپدیت: 10 آذرماه ۱۴۰۴
تیم توسعه: K3 Development Team

🧩 دستور کلی​

شرح عملکرد​

ورودی‌ها​

خروجی​

استثناها (Errors)​

InvalidRemoveImageParameters (422)​

ListImageTagsFailure (500)​

ImageTagNotFound (404)​

ImageTagConflict (409)​

ImageDependencyCheckFailure (500)​

RemoveImageLayerFailure (500)​

PruneLayersFailure (500)​

DeleteImageRecordFailure (500)​

RemoveImageDirectoryFailure (500)​

GenericFailure (500)​

مثال‌های استفاده​

مثال 1: حذف تگ پیش‌فرض (latest)​

مثال 2: حذف تگ خاص​

مثال 3: حذف تگ و بررسی پیام​

مثال 4: حذف چند تگ​

مثال 5: حذف با بررسی تگ‌های موجود​

مثال 6: حذف ایمیج کامل (تمام تگ‌ها)​

مثال 8: حذف نوبتی و logging​

الگوهای خطا و راهنمای حل​

الگو 1: تگ پیدا نشد​

الگو 2: تضاد وابستگی​

الگو 3: بررسی قبل از حذف​

نکات عملی​

دنباله عملیات​

مرجع سریع​

موارد استفاده​

Cleanup Operations​

Release Management​

Registry Maintenance​

CI/CD Pipeline​

🧩 دستور کلی

شرح عملکرد

ورودی‌ها

خروجی

استثناها (Errors)

InvalidRemoveImageParameters (422)

ListImageTagsFailure (500)

ImageTagNotFound (404)

ImageTagConflict (409)

ImageDependencyCheckFailure (500)

RemoveImageLayerFailure (500)

PruneLayersFailure (500)

DeleteImageRecordFailure (500)

RemoveImageDirectoryFailure (500)

GenericFailure (500)

مثال‌های استفاده

مثال 1: حذف تگ پیش‌فرض (latest)

مثال 2: حذف تگ خاص

مثال 3: حذف تگ و بررسی پیام

مثال 4: حذف چند تگ

مثال 5: حذف با بررسی تگ‌های موجود

مثال 6: حذف ایمیج کامل (تمام تگ‌ها)

مثال 8: حذف نوبتی و logging

الگوهای خطا و راهنمای حل

الگو 1: تگ پیدا نشد

الگو 2: تضاد وابستگی

الگو 3: بررسی قبل از حذف

نکات عملی

دنباله عملیات

مرجع سریع

موارد استفاده

Cleanup Operations

Release Management

Registry Maintenance

CI/CD Pipeline