شروع کانتینر

کانتینری که دارای وضعیت "created" یا "stopped" است را آغاز می‌کند.

---

🧩 دستور کلی

async startContainer(containerId, options = {})

---

شرح عملکرد

این متد کانتینری را با شناسه مشخص شروع می‌کند. کانتینر می‌تواند در دو وضعیت شروع شود:

• وضعیت "created": کانتینر مستقیماً شروع می‌شود
• وضعیت "stopped": کانتینر حذف، دوباره ایجاد و سپس شروع می‌شود

اگر کانتینر در وضعیت دیگری باشد، خطا ایجاد می‌شود.

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
containerId	String	بله	شناسه یا نام کانتینر برای شروع
options	Object	خیر	گزینه‌های اختیاری
options.time	Number	خیر	زمان انتظار قبل از شروع (به ثانیه)
options.debug	Boolean	خیر	فعال کردن حالت debug برای لاگ‌های تفصیلی

---

خروجی

نوع: String

خروجی شامل پیام‌های تفصیلی از فرآیند شروع کانتینر:

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

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

• Using debug verbosity - حالت debug فعال شده
• Loading container from config file - مسیر فایل پیکربندی کانتینر
• Opening hooks output - hooks سیستم در حال اجرا

---

استثناها (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"
}

راهنمای حل:

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

---

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": "Query timeout"
}

راهنمای حل:

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

---

NotInCreatedOrStopped (400)

پیام: "Container is not in 'created' or 'stopped' state."

زمان رخ دادن: کانتینر در وضعیت دیگری باشد (مثلاً running، paused)

جزئیات:

{
  "type": "INVALID_STATE",
  "statusCode": 400,
  "containerId": "abc123def456",
  "currentState": "running"
}

راهنمای حل:

• اگر کانتینر در حال اجرا است، نیاز به شروع ندارد
• اگر paused است، resumeContainer() استفاده کنید
• تنها کانتینرهای created یا stopped قابل شروع هستند

---

BuildRemoveDTO (422)

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

زمان رخ دادن: هنگام ساخت دستورات حذف (فقط برای stopped containers)

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "containerId": "abc123def456",
  "error": "Invalid options structure"
}

راهنمای حل:

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

---

RemoveFailure (500)

پیام: "Failed to remove stopped container."

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

جزئیات:

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

راهنمای حل:

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

---

BuildRestartDTO (422)

پیام: "Failed to prepare restart command options."

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

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "containerId": "abc123def456",
  "error": "Invalid configuration"
}

راهنمای حل:

• پیکربندی کانتینر را بررسی کنید

---

CreateVethFail (500)

پیام: "Failed to create container virtual network interface."

زمان رخ دادن: خطا در ایجاد رابط شبکه مجازی (فقط برای stopped containers)

جزئیات:

{
  "type": "NETWORK_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Network interface creation failed"
}

راهنمای حل:

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

---

PIDNotFound (404)

پیام: "Failed to retrieve PID: {response}"

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

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "containerId": "abc123def456",
  "response": "Process not found"
}

راهنمای حل:

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

---

FailedToUpdateStateAfterRestart (500)

پیام: "Failed to update container state during restart."

زمان رخ دادن: خطا در بروزرسانی وضعیت دیتابیس بعد از شروع مجدد

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "pid": 5678,
  "error": "Database write failed"
}

راهنمای حل:

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

---

BuildStartDTO (422)

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

زمان رخ دادن: هنگام ساخت دستورات شروع

جزئیات:

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

---

StartFailure (500)

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

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

جزئیات:

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

راهنمای حل:

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

---

UpdateContainerStateFailure (500)

پیام: "Database update failed while saving container state."

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

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "pid": 5678,
  "error": "Database error"
}

---

ApplyUpdatedResources (500)

پیام: "Failed to apply updated resource configuration."

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

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Cannot apply resource limits"
}

راهنمای حل:

• تنظیمات منابع را بررسی کنید
• مجوزهای سیستم را تأیید کنید

---

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

مثال 1: شروع ساده

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.startContainer('my-container');
    console.log('کانتینر با موفقیت شروع شد');
    console.log(result);
  } catch (error) {
    if (error.statusCode === 404) {
      console.log('کانتینر یافت نشد');
    } else if (error.statusCode === 400) {
      console.log(`کانتینر در وضعیت ${error.detail.currentState} است`);
    } else {
      console.error('خطا:', error.message);
    }
  }
})();

مثال 2: شروع با زمان انتظار

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.startContainer('app-container', {
      time: 5  
    });
    console.log('کانتینر شروع شد:', result);
  } catch (error) {
    console.error('خطا در شروع:', error.message);
  }
})();

مثال 3: شروع با debug

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.startContainer('web-server', {
      debug: true,  // نمایش لاگ‌های تفصیلی
      time: 3
    });
    console.log('خروجی Debug:', result);
  } catch (error) {
    console.error('خطا:', error.message);
  }
})();

مثال 4: مدیریت تمام حالات

(async () => {
  const k3 = new K3Core();
  const containerId = 'my-app';
  
  try {
    const result = await k3.containerCore.startContainer(containerId, {
      time: 5,
      debug: true
    });
    console.log(' شروع موفق');
    console.log(result);
  } catch (error) {
    // کانتینر یافت نشد
    if (error.type === 'NOT_FOUND') {
      console.log(' کانتینر وجود ندارد');
    }
    // وضعیت نامناسب
    else if (error.type === 'INVALID_STATE') {
      console.log(` وضعیت فعلی: ${error.detail.currentState}`);
    }
    // خطای دیتابیس
    else if (error.type === 'DB_ERROR') {
      console.log(' مشکل دیتابیس');
    }
    // سایر خطاها
    else {
      console.log(' خطا:', error.message);
    }
  }
})();

مثال 5: پولینگ برای اطمینان از شروع

(async () => {
  const k3 = new K3Core();
  
  const startAndWait = async (containerId) => {
    try {
      const result = await k3.containerCore.startContainer(containerId);
      console.log('شروع شروع شد:', result);
      
      // منتظر بمانید تا کانتینر به‌طور کامل شروع شود
      await new Promise(resolve => setTimeout(resolve, 2000));
      
      // بررسی وضعیت نهایی
      const [container] = await k3.containerCore.listContainers({ 
        containerId: containerId 
      });
      
      if (container.status === 'running') {
        console.log('✅ کانتینر با موفقیت در حال اجرا است');
      }
    } catch (error) {
      console.error(' خطا:', error.message);
    }
  };
  
  await startAndWait('my-container');
})();

---

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

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

خطا: ContainerNotFound (404)

راهنمای حل:

// راهکار 1: لیست کانتینرها را ببینید
const allContainers = await k3.containerCore.listContainers({ all: true });
console.log('دسترس‌پذیر کانتینرها:', allContainers.map(c => c.name));

// راهکار 2: ID صحیح را استفاده کنید
const container = allContainers.find(c => c.name.includes('my'));
if (container) {
  await k3.containerCore.startContainer(container.id);
}

الگو 2: وضعیت نامناسب

خطا: NotInCreatedOrStopped (400)

راهنمای حل:

// بررسی وضعیت فعلی
const [status] = await k3.containerCore.listContainers({ 
  containerId: 'my-container' 
});

if (status.status === 'running') {
  console.log('کانتینر از قبل در حال اجرا است');
} else if (status.status === 'paused') {
  // کانتینر pause شده است
  await k3.containerCore.resumeContainer('my-container');
} else if (status.status === 'stopped') {
  // کانتینر متوقف است
  await k3.containerCore.startContainer('my-container');
}

الگو 3: خطاهای دیتابیس

خطا: FetchContainerState (500)

راهنمای حل:

const checkAndStart = async (containerId) => {
  try {
    return await k3.containerCore.startContainer(containerId);
  } catch (error) {
    if (error.type === 'DB_ERROR') {
      console.log('منتظر باشید و دوباره تلاش کنید...');
      await new Promise(resolve => setTimeout(resolve, 2000));
      return await k3.containerCore.startContainer(containerId);
    }
    throw error;
  }
};

الگو 4: خطاهای شبکه (برای stopped containers)

خطا: CreateVethFail (500)

راهنمای حل:

(async () => {
  try {
    await k3.containerCore.startContainer('my-container');
  } catch (error) {
    if (error.type === 'NETWORK_ERROR') {
      console.log(' خطای شبکه - تلاش مجدد...');
      // اطمینان حاصل کنید که سرویس شبکه فعال است
      await new Promise(resolve => setTimeout(resolve, 3000));
      
      // تلاش دوباره
      await k3.containerCore.startContainer('my-container');
    }
  }
})();

---

نکات عملی

1. وضعیت‌های قابل‌قبول:

   • created - کانتینر جدید ایجاد شده
   • stopped - کانتینر متوقف شده

2. وقتی کانتینر stopped باشد:

   • خودکار حذف و دوباره‌ایجاد می‌شود
   • شبکه دوباره پیکربندی می‌شود
   • PID جدید تخصیص می‌یابد
   • منابع به‌روزرسانی شده (اگر موجود باشند) اعمال می‌شوند

3. پارامتر time:

   • مفید هنگام اجرای setup‌های طولانی
   • پیش‌فرض: ۰ ثانیه
   • برای کانتینرهای وابسته‌ای می‌تواند مفید باشد

4. حالت Debug:

   • خروجی تفصیلی از فرآیند شروع
   • مسیر فایل پیکربندی نمایش داده می‌شود
   • برای troubleshooting مفید است

5. Webhook:

   • رویداد "container started" ارسال می‌شود
   • ناموفق بودن webhook خطا نیست

6. فایل تنظیمات:

   • معمولاً در /run/crun/{containerId}/config.json قرار دارد
   • حاوی تمام تنظیمات runtime کانتینر

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	کانتینر شروع شد
یافت نشد	404	ContainerNotFound
وضعیت نامناسب	400	NotInCreatedOrStopped
ثبت یافت نشد	404	ContainerRecord
خطای دیتابیس	500	FetchContainerState
خطای شروع	500	StartFailure
خطای شبکه	500	CreateVethFail
خطای شروع مجدد	500	FailedToUpdateStateAfterRestart

---

نسخه: 1.3 تاریخ آپدیت: 9 آذر1404