فهرست ایمیج‌های کانتینر محلی

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

---

🧩 دستور کلی

async listImages(options = {})

---

شرح عملکرد

این متد لیست تمام ایمیج‌های ثبت‌شده در ImageManager را دریافت می‌کند. شامل:

• واکشی تمام ایمیج‌ها از ImageManager
• اعتبارسنجی پاسخ (باید آرایه باشد)
• فیلتر اختیاری بر اساس نام ایمیج (image)
• فیلتر اختیاری بر اساس تگ (tag)
• بازگرداندن آرایه‌ای از ایمیج‌های منطبق
• logging عملیات

اگر هیچ فیلتری داده نشود، تمام ایمیج‌ها برگشت داده می‌شود. هر ایمیج شامل نام، تگ و اندازه است.

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
options	Object	خیر	گزینه‌های فیلتر
options.image	String	خیر	نام ایمیج (مثلاً alpine, nginx)
options.tag	String	خیر	تگ ایمیج (مثلاً latest, 1.2.0)

---

خروجی

نوع: Array<Object> (لیست ایمیج‌ها)

هر شیء شامل:

نام	نوع	توضیح
Name	String	نام ایمیج
Tag	String	نسخه یا تگ ایمیج
Size	String	اندازه تقریبی (مثلاً "3 MB", "150 MB")

نمونه خروجی:

[
  { Name: "alpine", Tag: "latest", Size: "3 MB" },
  { Name: "nginx", Tag: "latest", Size: "150 MB" },
  { Name: "node", Tag: "18", Size: "850 MB" }
]

---

استثناها (Errors)

ListImagesFailure (500)

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

زمان رخ دادن: هنگام واکشی لیست ایمیج‌ها از ImageManager

جزئیات:

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

راهنمای حل:

• سرویس ImageManager را بررسی کنید
• اتصال registry را تأیید کنید
• لاگ‌های ImageManager را بررسی کنید

---

InvalidImageListResponse (422)

پیام: "Invalid image list response (not an array)."

زمان رخ دادن: وقتی پاسخ ImageManager آرایه نباشد

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "error": "Response is not an array"
}

راهنمای حل:

• ImageManager را restart کنید
• سلامت registry را بررسی کنید
• پایگاه داده registry را بررسی کنید

---

GenericFailure (500)

پیام: "Generic failure during list images operation."

زمان رخ دادن: خطای عمومی در فیلتر یا پردازش

جزئیات:

{
  "type": "GENERIC_ERROR",
  "statusCode": 500,
  "error": "List operation failed"
}

راهنمای حل:

• سیستم لاگ را بررسی کنید
• منابع سیستم را تأیید کنید
• عملیات را دوباره تلاش کنید

---

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

مثال 1: دریافت تمام ایمیج‌ها

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const images = await k3.imageCore.listImages({});
    console.log(`کل ایمیج‌ها: ${images.length}`);
    
    images.forEach(img => {
      console.log(`${img.Name}:${img.Tag} (${img.Size})`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 2: فیلتر بر اساس نام ایمیج

(async () => {
  const k3 = new K3Core();
  
  try {
    const images = await k3.imageCore.listImages({
      image: 'alpine'
    });
    
    if (images.length === 0) {
      console.log('ایمیج alpine پیدا نشد');
    } else {
      images.forEach(img => {
        console.log(`${img.Name}:${img.Tag} (${img.Size})`);
      });
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: فیلتر بر اساس تگ

(async () => {
  const k3 = new K3Core();
  
  try {
    const images = await k3.imageCore.listImages({
      tag: 'latest'
    });
    
    console.log(`ایمیج‌هایی با تگ 'latest': ${images.length}`);
    images.forEach(img => {
      console.log(`  ${img.Name}:${img.Tag} (${img.Size})`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 4: فیلتر بر اساس نام و تگ

(async () => {
  const k3 = new K3Core();
  
  try {
    const images = await k3.imageCore.listImages({
      image: 'node',
      tag: '18'
    });
    
    if (images.length > 0) {
      console.log('ایمیج node:18 پیدا شد');
      console.log(`اندازه: ${images[0].Size}`);
    } else {
      console.log('ایمیج node:18 پیدا نشد');
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 5: شمارش ایمیج‌ها بر اساس نام

(async () => {
  const k3 = new K3Core();
  
  try {
    const allImages = await k3.imageCore.listImages({});
    
    // شمارش ایمیج‌ها
    const nameCount = {};
    allImages.forEach(img => {
      nameCount[img.Name] = (nameCount[img.Name] || 0) + 1;
    });
    
    console.log('شمارش ایمیج‌ها بر اساس نام:');
    Object.entries(nameCount).forEach(([name, count]) => {
      console.log(`  ${name}: ${count} تگ`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: محاسبه کل اندازه ایمیج‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    const images = await k3.imageCore.listImages({});
    
    let totalSize = 0;
    images.forEach(img => {
      // تبدیل اندازه به عدد (MB)
      const sizeStr = img.Size.replace(/[^\d]/g, '');
      totalSize += parseInt(sizeStr) || 0;
    });
    
    console.log(`کل اندازه ایمیج‌ها: ${totalSize} MB`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 7: نمایش اطلاعات دقیق ایمیج‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    const images = await k3.imageCore.listImages({});
    
    console.log('=== ایمیج‌های کانتینر ===');
    console.log(`کل: ${images.length}\n`);
    
    images.forEach((img, index) => {
      console.log(`${index + 1}. ${img.Name}`);
      console.log(`   تگ: ${img.Tag}`);
      console.log(`   اندازه: ${img.Size}`);
      console.log(`   شناسه کامل: ${img.Name}:${img.Tag}`);
      console.log('');
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 8: جستجو برای ایمیج و اجرای کانتینر

(async () => {
  const k3 = new K3Core();
  
  try {
    // جستجو برای ایمیج
    const images = await k3.imageCore.listImages({
      image: 'alpine'
    });
    
    if (images.length === 0) {
      console.log('ایمیج alpine پیدا نشد، نیاز به pull');
      return;
    }
    
    console.log(`ایمیج alpine پیدا شد: ${images[0].Tag}`);
    
    // اجرای کانتینر
    const result = await k3.containerCore.runContainer({
      containerId: 'test-alpine',
      image: 'alpine',
      tag: images[0].Tag
    });
    
    console.log('کانتینر ایجاد شد:', result);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

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

الگو 1: هیچ ایمیجی موجود نیست

خطا: هیچ یا آرایه خالی

راهنمای حل:

try {
  const images = await k3.imageCore.listImages({});
  
  if (images.length === 0) {
    console.log('هیچ ایمیجی پیدا نشد');
    console.log('دستورات دستیاب:');
    console.log('  - Pull ایمیج: imageCore.pullImage()');
    console.log('  - ایجاد ایمیج: imageCore.createImage()');
  } else {
    console.log(`${images.length} ایمیج پیدا شد`);
  }
} catch (error) {
  console.log(error.createFullMessage());
}

الگو 2: خطای ImageManager

خطا: ListImagesFailure (500)

راهنمای حل:

try {
  const images = await k3.imageCore.listImages({});
} catch (error) {
  if (error.type === 'IMAGE_SERVICE_ERROR') {
    console.log('خطای سرویس ImageManager');
    console.log('خطوات حل مسئله:');
    console.log('  1. وضعیت ImageManager را بررسی کنید');
    console.log('  2. سرویس ImageManager را restart کنید');
    console.log('  3. اتصال registry را بررسی کنید');
    
    // تلاش مجدد
    setTimeout(async () => {
      try {
        const images = await k3.imageCore.listImages({});
        console.log('تلاش مجدد موفق بود');
      } catch (e) {
        console.log('تلاش مجدد ناموفق:', e.message);
      }
    }, 5000);
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 3: ایمیج خاصی یافت نشد

راهنمای حل:

const findOrPullImage = async (imageName, imageTag = 'latest') => {
  try {
    // جستجو برای ایمیج
    const images = await k3.imageCore.listImages({
      image: imageName,
      tag: imageTag
    });
    
    if (images.length > 0) {
      console.log(`ایمیج پیدا شد: ${imageName}:${imageTag}`);
      return images[0];
    }
    
    console.log(`ایمیج پیدا نشد، تلاش برای pull ${imageName}:${imageTag}...`);
    
    // Pull ایمیج
    await k3.imageCore.pullImage({
      image: imageName,
      tag: imageTag
    });
    
    console.log('ایمیج با موفقیت pull شد');
    
    // جستجو دوباره
    const result = await k3.imageCore.listImages({
      image: imageName,
      tag: imageTag
    });
    
    return result[0];
  } catch (error) {
    console.log('خطا:', error.message);
    return null;
  }
};

const image = await findOrPullImage('nginx', 'latest');

الگو 4: فیلتر پیشرفته

راهنمای حل:

const advancedFilter = async (criteria = {}) => {
  try {
    const images = await k3.imageCore.listImages({});
    
    let filtered = images;
    
    // فیلتر بر اساس نام
    if (criteria.namePattern) {
      filtered = filtered.filter(img => 
        img.Name.includes(criteria.namePattern)
      );
    }
    
    // فیلتر بر اساس اندازه
    if (criteria.minSize) {
      filtered = filtered.filter(img => {
        const sizeNum = parseInt(img.Size);
        return sizeNum >= criteria.minSize;
      });
    }
    
    // فیلتر بر اساس تگ (regex)
    if (criteria.tagPattern) {
      filtered = filtered.filter(img => 
        new RegExp(criteria.tagPattern).test(img.Tag)
      );
    }
    
    return filtered;
  } catch (error) {
    console.log('فیلتر ناموفق:', error.message);
    return [];
  }
};

// استفاده
const largeImages = await advancedFilter({
  namePattern: 'node',
  minSize: 500,
  tagPattern: '^1[0-9]'
});

console.log('ایمیج‌های Node بزرگ:', largeImages);

الگو 5: نظارت بر تغییرات ایمیج‌ها

راهنمای حل:

class ImageMonitor {
  constructor(interval = 60000) {
    this.interval = interval;
    this.lastImages = [];
  }
  
  async start(k3) {
    console.log('شروع نظارت بر ایمیج‌ها...');
    
    this.intervalId = setInterval(async () => {
      try {
        const images = await k3.imageCore.listImages({});
        
        // بررسی تغییرات
        const added = images.filter(img => 
          !this.lastImages.some(old => 
            old.Name === img.Name && old.Tag === img.Tag
          )
        );
        
        const removed = this.lastImages.filter(img => 
          !images.some(newImg => 
            newImg.Name === img.Name && newImg.Tag === img.Tag
          )
        );
        
        if (added.length > 0) {
          console.log('ایمیج‌های جدید اضافه شدند:');
          added.forEach(img => {
            console.log(`  + ${img.Name}:${img.Tag} (${img.Size})`);
          });
        }
        
        if (removed.length > 0) {
          console.log('ایمیج‌های حذف شدند:');
          removed.forEach(img => {
            console.log(`  - ${img.Name}:${img.Tag}`);
          });
        }
        
        this.lastImages = images;
      } catch (error) {
        console.error('خطای نظارت:', error.message);
      }
    }, this.interval);
  }
  
  stop() {
    if (this.intervalId) {
      clearInterval(this.intervalId);
      console.log('نظارت بر ایمیج‌ها متوقف شد');
    }
  }
}

const monitor = new ImageMonitor(30000);
await monitor.start(k3);

---

نکات عملی

1. فیلتر:

   • اگر image و tag داده شود، هر دو باید match شوند
   • فیلتر case-sensitive است
   • بدون فیلتر، تمام ایمیج‌ها برگشت داده می‌شود

2. اندازه:

   • اندازه تقریبی است و برای مدیریت دیسک است
   • واحد می‌تواند MB، GB یا KB باشد

3. نام و Tag:

   • Name: نام کوتاه (alpine، nginx)
   • Tag: نسخه (latest، 18، 1.2.0)
   • Full ID: {Name}:{Tag}

4. Performance:

   • برای لیست بزرگ، فیلتر کردن سریع‌تر است
   • بدون فیلتر تمام registry scan می‌شود

5. Registry:

   • ایمیج‌ها محلی نیستند (pulling یا pushing required)
   • ایمیج‌های private registry نیاز به authentication دارند

6. Cleanup:

   • ایمیج‌های غیرضروری را removeImage() حذف کنید
   • pruneImages() ایمیج‌های orphaned را پاکسازی کند

---

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

1. Fetch ایمیج‌ها از ImageManager
2. اعتبارسنجی پاسخ (آرایه باشد)
3. استخراج پارامترهای فیلتر (image, tag)
4. اعمال فیلتر نام اگر مشخص شده
5. اعمال فیلتر تگ اگر مشخص شده
6. Logging عملیات موفق
7. بازگرداندن نتایج فیلتر شده

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	لیست دریافت شد
خالی	200	هیچ ایمیجی نیست
خطای سرویس	500	ListImagesFailure
پاسخی نامعتبر	422	InvalidImageListResponse
خطای عمومی	500	GenericFailure

---

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

Inventory Management

const images = await listImages({});
console.log(`کل ایمیج‌ها: ${images.length}`);

Validation before Run

const images = await listImages({ image: 'app', tag: 'latest' });
if (images.length > 0) await runContainer(...);

Cleanup Operations

const images = await listImages({ tag: 'dev' });
images.forEach(img => removeImage(img.Name, img.Tag));

Resource Planning

const images = await listImages({});
const totalSize = images.reduce((sum, img) => 
  sum + parseInt(img.Size), 0
);

---

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