لیست کانتینرها

لیست کردن کانتینرها بر اساس فیلترهای اختیاری.

---

🧩 دستور کلی

async listContainers(options = {})

---

شرح عملکرد

این متد کانتینرها را لیست می‌کند. می‌توان از فیلترهایی مانند وضعیت، تاریخ ایجاد، شناسه کانتینر یا ایمیج کانتینر استفاده کرد. گزینه all برای لیست کردن همه‌ی کانتینرها (صرف‌نظر از وضعیت) موجود است، ولی نمی‌توان همزمان آن را با سایر فیلترها فعال کرد. در صورت بروز تناقض خطا ایجاد می‌شود.

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
all	Boolean	خیر	اگر true باشد، تمام کانتینرها (چه فعال و چه غیرفعال) لیست می‌شوند
status	String	خیر	فیلتر بر اساس وضعیت: created, running, stopped, paused
containerId	String	خیر	فیلتر بر اساس شناسه کانتینر
image	String	خیر	فیلتر بر اساس نام ایمیج
created	String	خیر	فیلتر بر اساس تاریخ ایجاد (فرمت: YYYY-MM-DD)

⚠️ محدودیت فیلترها

اگر options.all فعال باشد، نمی‌توان همزمان از موارد زیر استفاده کرد:

• status
• created
• image
• containerId

در صورت تناقض، خطای OptionConflict ایجاد می‌شود.

---

خروجی

نوع: Array<Object>

آرایه‌ای از کانتینرها با ساختار زیر:

[
  {
    id: '111',
    pid: 24006,
    status: 'running',
    bundle: '/var/lib/k3/overlays/f1ecea48de222c5c',
    created: 2025-11-30T06:55:35.814Z,
    owner: 'root',
    cmd: 'tail -f /dev/null',
    image: 'alpine:latest',
    ip: '192.168.100.2/24',
    mac: 'F2:EC:EA:48:DE:22'
  }
]

فیلدهای خروجی:

• id - شناسه کانتینر
• name - نام کانتینر
• status - وضعیت فعلی کانتینر
• created - تاریخ و زمان ایجاد
• cmd - دستور پیش‌فرض کانتینر
• image - نام ایمیج
• ip - آدرس IP تخصیص‌یافته
• mac - آدرس MAC تخصیص‌یافته

---

استثناها (Errors)

OptionConflict (400)

پیام: "all cannot be used with status, created, image"

زمان رخ دادن: وقتی all=true و یکی از فیلترهای دیگر بیک‌وقت فعال باشند

جزئیات:

{
  type: 'VALIDATION_ERROR',
  statusCode: 400,
  field: "all",
  conflictWith: ["status", "created", "image"]
}

راهنمای حل: یا all را فعال کنید یا فیلترهای دیگر را استفاده کنید، نه هردو

---

ListFailure (500)

پیام: "Failed to list containers through ContainerManager."

زمان رخ دادن: هنگام اتصال به ContainerManager یا خواندن لیست کانتینرها

جزئیات:

{
  type: 'CONTAINER_SERVICE_ERROR',
  statusCode: 500,
  filters: { status: "running" },
  error: "Internal service error"
}

راهنمای حل:

• بررسی کنید که سرویس K3 فعال است
• لاگ‌های سرویس را بررسی کنید
• اتصال دیتابیس را تأیید کنید

---

NoContainers (404)

پیام: "No containers found matching the provided filters."

زمان رخ دادن: هنگامی‌که فیلترهای اعمال شده نتیجه‌ای برنگرداند

جزئیات:

{
  type: 'NOT_FOUND',
  statusCode: 404,
  filters: { status: "running" }
}

راهنمای حل:

• فیلترهای خود را بررسی کنید
• all: true استفاده کنید تا تمام کانتینرها را ببینید
• مطمئن شوید کانتینرهایی با این مشخصات وجود دارند

---

ContainerRecord (404)

پیام: "Container record not found for ID: {containerId}"

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

جزئیات:

{
  type: 'NOT_FOUND',
  statusCode: 404,
  containerId: "abc123def456"
}

راهنمای حل:

• دیتابیس را تأیید کنید
• کانتینر را دوباره ایجاد کنید

---

FetchContainerState (500)

پیام: "Database error occurred while fetching container state."

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

جزئیات:

{
  type: 'DB_ERROR',
  statusCode: 500,
  containerId: "abc123def456",
  error: "Database connection lost"
}

راهنمای حل:

• اتصال دیتابیس را بررسی کنید
• دیتابیس را راه‌اندازی کنید
• لاگ‌های دیتابیس را مطالعه کنید

---

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

مثال 1: لیست کانتینرهای در حال اجرا

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const runningContainers = await k3.containerCore.listContainers({
      status: 'running'
    });
    
    console.log(`تعداد کانتینرهای فعال: ${runningContainers.length}`);
    runningContainers.forEach(container => {
      console.log(`- ${container.name} (${container.image})`);
    });
  } catch (error) {
    if (error.statusCode === 404) {
      console.log('هیچ کانتینر فعالی وجود ندارد');
    } else {
      console.error('خطا:', error.message);
    }
  }
})();

مثال 2: لیست تمام کانتینرها

(async () => {
  const k3 = new K3Core();
  
  try {
    const allContainers = await k3.containerCore.listContainers({
      all: true
    });
    
    const byStatus = {};
    allContainers.forEach(container => {
      if (!byStatus[container.status]) {
        byStatus[container.status] = [];
      }
      byStatus[container.status].push(container.name);
    });
    
    console.log('کانتینرها بر اساس وضعیت:');
    Object.entries(byStatus).forEach(([status, names]) => {
      console.log(`${status}: ${names.join(', ')}`);
    });
  } catch (error) {
    console.error('خطا:', error.message);
  }
})();

مثال 3: فیلتر کردن بر اساس ایمیج

(async () => {
  const k3 = new K3Core();
  
  try {
    const ubuntuContainers = await k3.containerCore.listContainers({
      image: 'ubuntu'
    });
    
    console.log(`کانتینرهای Ubuntu: ${ubuntuContainers.length}`);
    ubuntuContainers.forEach(container => {
      console.log(`- ${container.name} (وضعیت: ${container.status})`);
    });
  } catch (error) {
    if (error.statusCode === 404) {
      console.log('کانتینری با ایمیج Ubuntu یافت نشد');
    } else {
      console.error('خطا:', error.message);
    }
  }
})();

---

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

الگو 1: بدون نتیجه

خطا: NoContainers (404)

علل احتمالی:

1. فیلترهای بیش از حد محدود
2. کانتینری با مشخصات درخواستی وجود ندارد
3. تمام کانتینرها متوقف شده‌اند

راهنمای حل:

const all = await k3.containerCore.listContainers({ all: true });

const stopped = await k3.containerCore.listContainers({ status: 'stopped' });

if (result.length === 0) {
  console.log('هیچ کانتینری یافت نشد - نیاز به ایجاد دارد');
}

الگو 2: تناقض فیلترها

خطا: OptionConflict (400)

علت: استفاده همزمان all و فیلترهای دیگر

راهنمای حل:

await k3.containerCore.listContainers({
  all: true,
  status: 'running' 
});

await k3.containerCore.listContainers({
  status: 'running' 
});

await k3.containerCore.listContainers({
  all: true  
});

نکات عملی

1. مرتب‌سازی: کانتینرها بر اساس تاریخ ایجاد مرتب می‌شوند (قدیم‌تر به جدیدتر)

2. اطلاعات شبکه: فقط اولین رابط شبکه برگردانده می‌شود:

   • اگر چند شبکه متصل باشد، فقط Network[0] استفاده می‌شود

3. فیلتر تصویر: فیلتر image حتی نام بخشی را نیز پیدا می‌کند:

4. بدون نتیجه: اگر فیلترها نتیجه ندهند خطای 404 برگردانده می‌شود، نه آرایه خالی

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	لیست کانتینرها برگردانده شد
تناقض فیلتر	400	OptionConflict
بدون نتیجه	404	NoContainers
ثبت یافت نشد	404	ContainerRecord
خطای دیتابیس	500	FetchContainerState
خطای سرویس	500	ListFailure

---

نسخه: 1.3
تاریخ آپدیت: ۹ آذرماه ۱‍۴۰۴