حذف کانتینر

کانتینری که درخواست شده را برای حذف کامل (شامل فایل‌سیستم و حجم‌ها) حذف می‌کند.

---

🧩 دستور کلی

async removeContainer(containerId, options = {})

---

شرح عملکرد

این متد کانتینر مشخص شده را به‌طور کامل حذف می‌کند. می‌توانید:

• کانتینرهای در حال اجرا را با گزینه force حذف کنید
• حجم‌های مرتبط را نیز حذف کنید
• فایل‌سیستم کانتینر را حذف کنید
• چند کانتینر را با الگوی regex حذف کنید

مهم: این عملیات غیرقابل برگشت است.

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
containerId	String	بله	شناسه/نام کانتینر یا الگوی regex
options	Object	بله	گزینه‌های حذف
options.force	Boolean	خیر	حذف اجباری کانتینرهای در حال اجرا (پیش‌فرض: false)
options.volume	Boolean	خیر	حذف حجم‌های مربوط به کانتینر (پیش‌فرض: false)
options.regex	Boolean	خیر	حذف چند کانتینر بر اساس regex (پیش‌فرض: false)
options.deleteFileSystem	Boolean	خیر	حذف فایل‌سیستم کانتینر (پیش‌فرض: true)
options.debug	Boolean	خیر	فعال کردن حالت debug

---

خروجی

نوع: String یا Array<Object> (تک کانتینر یا چند کانتینر)

خروجی برای تک کانتینر:

Using debug verbosity
Loading container from config file: `/run/crun/111/config.json`
Opening hooks output

خروجی برای چند کانتینر (regex):

[
  {
    "containerId": "container-1",
    "result": "Container removed"
  },
  {
    "containerId": "container-2",
    "result": "Container removed"
  }
]

---

استثناها (Errors)

ContainerNotFound (404)

پیام: "No container exists with the specified name or ID prefix."

زمان رخ دادن: کانتینری با شناسه/نام درخواستی یافت نشود

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "containerId": "invalid-id"
}

راهنمای حل:

• شناسه کانتینر را بررسی کنید
• listContainers() استفاده کنید تا تمام کانتینرها را ببینید
• نام یا ID صحیح را وارد کنید

---

ResolveContainerName (500)

پیام: "Database error occurred while resolving container name or ID."

زمان رخ دادن: خطای دیتابیس در تطابق شناسه/نام کانتینر

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "input": "container-id",
  "error": "Database connection lost"
}

راهنمای حل:

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

---

OptionConflict (422)

پیام: "Failed to validate remove options."

زمان رخ دادن: گزینه‌های ورودی نامعتبر باشند

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "error": "Invalid schema"
}

راهنمای حل:

• گزینه‌های ورودی را بررسی کنید
• تمام گزینه‌ها باید Boolean باشند
• regex را صحیح تعریف کنید

---

BuildRemoveDTO (422)

پیام: "Failed to build remove container DTO options."

زمان رخ دادن: خطا در ساخت دستورات remove

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "containerId": "abc123def456",
  "error": "DTO construction failed"
}

راهنمای حل:

• شناسه کانتینر را بررسی کنید
• گزینه force را تأیید کنید

---

RemoveFailure (500)

پیام: "Failed to remove container through ContainerManager."

زمان رخ دادن: خطا در حذف کانتینر

جزئیات:

{
  "type": "CONTAINER_SERVICE_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Runtime error"
}

راهنمای حل:

• سرویس K3 فعال است یا خیر؟
• لاگ‌های سرویس را مطالعه کنید
• اطمینان حاصل کنید کانتینر متوقف شده است

---

FetchContainerState (500)

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

زمان رخ دادن: خطا در حذف اطلاعات دیتابیس

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Delete failed"
}

راهنمای حل:

• دیتابیس را بررسی کنید
• اتصال را تأیید کنید

---

ContainerService (500)

پیام: "Container service error."

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

جزئیات:

{
  "type": "GENERIC_ERROR",
  "statusCode": 500,
  "error": "Unknown error"
}

راهنمای حل:

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

---

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

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

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.removeContainer('my-container', {});
    console.log('Container removed successfully');
    console.log(result);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 2: حذف کانتینر در حال اجرا

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.removeContainer('running-container', {
      force: true
    });
    console.log('Running container removed with force');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: حذف کانتینر و حجم‌های آن

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.removeContainer('container-with-volumes', {
      force: true,
      volume: true 
    });
    console.log('Container and volumes removed');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 4: حذف کانتینر بدون حذف فایل‌سیستم

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.removeContainer('data-container', {
      deleteFileSystem: false  
    });
    console.log('Container removed but filesystem preserved');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 5: حذف چند کانتینر با regex

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.removeContainer('^test-.*', {
      regex: true,
      force: true
    });
    console.log('Multiple containers removed:');
    result.forEach(item => {
      console.log(`  ${item.containerId}: ${item.result}`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: حذف با debug mode

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.removeContainer('debug-container', {
      force: true,
      volume: true,
      debug: true
    });
    console.log('Debug output:');
    console.log(result);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 7: حذف محتاط با بررسی قبلی

(async () => {
  const k3 = new K3Core();
  
  try {
    const containerId = 'important-container';
    
    // Step 1: بررسی کانتینر قبل از حذف
    const inspect = await k3.containerCore.inspectContainer(containerId);
    
    if (!inspect) {
      console.log('Container not found');
      return;
    }
    
    console.log(`Removing container: ${inspect.name}`);
    console.log(`Running: ${inspect.state?.running}`);
    console.log(`Mounts: ${inspect.mounts?.length || 0}`);
    
    // Step 2: درخواست تایید
    const confirm = true; // در عمل از کاربر بخواهید
    
    if (!confirm) {
      console.log('Removal cancelled');
      return;
    }
    
    // Step 3: حذف
    const result = await k3.containerCore.removeContainer(containerId, {
      force: true,
      volume: false  // حجم‌ها حفظ شوند
    });
    
    console.log('Container removed successfully');
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

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

الگو 1: کانتینر یافت نشد

خطا: ContainerNotFound (404)

راهنمای حل:

try {
  await k3.containerCore.removeContainer('invalid-container', { force: true });
} catch (error) {
  if (error.type === 'NOT_FOUND') {
    // Get list of all containers
    const allContainers = await k3.containerCore.listContainers({ all: true });
    console.log('Available containers:', allContainers.map(c => c.name));
    
    // Find and remove the correct container
    const container = allContainers.find(c => c.name.includes('target'));
    if (container) {
      await k3.containerCore.removeContainer(container.id, { force: true });
    }
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 2: حذف کانتینر در حال اجرا

خطا: RemoveFailure (500) - هنگام تلاش برای حذف کانتینر فعال

راهنمای حل:

const safeRemove = async (containerId) => {
  try {
    // اول سعی کنید بدون force
    return await k3.containerCore.removeContainer(containerId, {});
  } catch (error) {
    // اگر در حال اجرا است، force استفاده کنید
    console.log('Container is running, using force...');
    return await k3.containerCore.removeContainer(containerId, {
      force: true
    });
  }
};

await safeRemove('my-container');

الگو 3: حذف regex multiple

راهنمای حل:

try {
  // حذف تمام کانتینرهای موقتی
  const results = await k3.containerCore.removeContainer('^temp-.*', {
    regex: true,
    force: true
  });
  
  console.log(`Removed ${results.length} containers`);
  
  // بررسی موارد ناموفق
  const failed = results.filter(r => r.result.includes('error'));
  if (failed.length > 0) {
    console.log('Failed removals:', failed);
  }
  
} catch (error) {
  console.log(error.createFullMessage());
}

الگو 4: حذف با حفظ حجم‌ها

راهنمای حل:

const removeButKeepData = async (containerId) => {
  try {
    // Get container info first
    const inspect = await k3.containerCore.inspectContainer(containerId);
    
    if (!inspect) {
      console.log('Container not found');
      return;
    }
    
    console.log(`Removing ${inspect.name}...`);
    console.log(`Volumes will be preserved`);
    
    // Remove without deleting volumes
    const result = await k3.containerCore.removeContainer(containerId, {
      force: true,
      volume: false, 
      deleteFileSystem: true
    });
    
    console.log('Container removed, data preserved');
    return result;
    
  } catch (error) {
    console.log(error.createFullMessage());
    throw error;
  }
};

await removeButKeepData('my-container');

---

نکات عملی

1. Force Parameter:

   • force: false (پیش‌فرض): فقط کانتینرهای متوقف
   • force: true: تمام کانتینرها شامل فعال‌ها

2. Volume Parameter:

   • volume: false (پیش‌فرض): حجم‌ها حفظ شوند
   • volume: true: حجم‌ها نیز حذف شوند

3. DeleteFileSystem Parameter:

   • deleteFileSystem: true (پیش‌فرض): فایل‌سیستم حذف شود
   • deleteFileSystem: false: فایل‌سیستم حفظ شود

4. Regex Pattern:

   • از regex معتبر استفاده کنید
   • ^test-.*: شروع با test-
   • .*-old$: پایان با -old
   • ^(tmp|temp)-: tmp یا temp شروع

5. بهترین شیوه:

   • قبل از حذف، اطلاعات کانتینر بررسی کنید
   • برای کانتینرهای اهم، از force نپرهیزید
   • حجم‌های مهم را حفظ کنید
   • regex را دقیق تعریف کنید

6. غیرقابل برگشت:

   • این عملیات حذف دائمی است
   • Backup بگیرید اگر لازم است
   • مطمئن شوید صحیح کانتینر را حذف می‌کنید

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	کانتینر حذف شد
یافت نشد	404	ContainerNotFound
گزینه نامعتبر	422	OptionConflict
DTO خطا	422	BuildRemoveDTO
خطای حذف	500	RemoveFailure
خطای دیتابیس	500	FetchContainerState

---

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