راه‌اندازی مجدد کانتینر

کانتینر مشخص شده را متوقف کرده و سپس دوباره راه‌اندازی می‌کند.

🧩 دستور کلی

async restartContainer(containerId, options = {})

شرح عملکرد

این متد کانتینر را راه‌اندازی مجدد می‌کند. شامل:

انتظار برای مدت زمان مشخص (grace period)
حذف کانتینر فعلی
بازیابی اطلاعات کانتینر
ایجاد veth pair اگر لازم باشد
ایجاد کانتینر جدید
بروزرسانی منابع (اگر تغییر یافته)
شروع کانتینر

مهم: این عملیات شامل حذف و ایجاد مجدد است، بنابراین تمام connections قطع می‌شود.

ورودی‌ها

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

خروجی

نوع: String (پیام نتیجه عملیات)

خروجی:

Container Restarted Successfully

استثناها (Errors)

ContainerRecord (404)

پیام: "Container record not found in database."

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

جزئیات:

{
  "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"
}

راهنمای حل:

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

BuildRemoveDTO (422)

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

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

جزئیات:

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

راهنمای حل:

شناسه کانتینر را بررسی کنید

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

راهنمای حل:

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

CreateVethFail (500)

پیام: "Failed to create veth pair or set container IP."

زمان رخ دادن: خطا در تنظیم شبکه

جزئیات:

{
  "type": "NETWORK_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Veth pair creation failed"
}

راهنمای حل:

شبکه را بررسی کنید
IP configuration را تأیید کنید

❌ CreateFailure (500)

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

زمان رخ دادن: خطا در ایجاد کانتینر جدید

جزئیات:

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

راهنمای حل:

لاگ‌های runtime را بررسی کنید
منابع سیستم را تأیید کنید

❌ PIDNotFound (404)

پیام: "No process found for the specified container."

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

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "containerId": "abc123def456",
  "error": "PID not found"
}

راهنمای حل:

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

RestartAttemptsUpdate (500)

پیام: "Failed to update restart attempts."

زمان رخ دادن: خطا در ثبت تلاش‌های راه‌اندازی مجدد

جزئیات:

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

راهنمای حل:

دیتابیس را بررسی کنید
فضای دیسک را تأیید کنید

UpdateStateDuringRestart (500)

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

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

جزئیات:

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

راهنمای حل:

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

UpdateResourcesFailure (500)

پیام: "Failed to update container resources."

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

جزئیات:

{
  "type": "CONTAINER_SERVICE_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Resource update failed"
}

راهنمای حل:

منابع درخواستی را بررسی کنید
سرویس را دوباره شروع کنید

BuildStartDTO (422)

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

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

جزئیات:

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

راهنمای حل:

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

StartFailure (500)

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

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

جزئیات:

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

راهنمای حل:

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

OptionConflict (422)

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

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

جزئیات:

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

راهنمای حل:

گزینه‌های ورودی را بررسی کنید
time باید Number باشد
debug باید Boolean باشد

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

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

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

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

مثال 2: راه‌اندازی مجدد کانتینر با زمان انتظار

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.restartContainer('web-server', {
      time: 20  // 20 ثانیه انتظار قبل از راه‌اندازی مجدد
    });
    console.log('Web server restarted');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: راه‌اندازی مجدد کانتینر با debug mode

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

مثال 4: راه‌اندازی مجدد فوری

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.restartContainer('fast-restart', {
      time: 0  // راه‌اندازی مجدد فوری بدون انتظار
    });
    console.log('Container restarted immediately');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 5: راه‌اندازی مجدد با بررسی قبلی

(async () => {
  const k3 = new K3Core();
  const containerId = 'target-container';
  
  try {
    // Step 1: بررسی وضعیت کانتینر
    const inspect = await k3.containerCore.inspectContainer(containerId);
    
    if (!inspect) {
      console.log('Container not found');
      return;
    }
    
    console.log(`Container state: ${inspect.state?.running ? 'running' : 'stopped'}`);
    console.log(`Uptime: ${inspect.state?.pid}`);
    
    // Step 2: راه‌اندازی مجدد
    console.log(`Restarting container: ${inspect.name}`);
    const result = await k3.containerCore.restartContainer(containerId, {
      time: 25
    });
    
    console.log('Container restarted successfully');
    
    // Step 3: بررسی وضعیت جدید
    const newInspect = await k3.containerCore.inspectContainer(containerId);
    console.log(`New PID: ${newInspect.state?.pid}`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: راه‌اندازی مجدد چند کانتینر

(async () => {
  const k3 = new K3Core();
  
  try {
    const containers = ['app-1', 'app-2', 'app-3'];
    
    for (const containerId of containers) {
      try {
        console.log(`Restarting ${containerId}...`);
        await k3.containerCore.restartContainer(containerId, { time: 15 });
        console.log(`${containerId} restarted`);
      } catch (error) {
        console.log(`Failed to restart ${containerId}: ${error.message}`);
      }
    }
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 7: راه‌اندازی مجدد و انتظار برای آمادگی

(async () => {
  const k3 = new K3Core();
  const containerId = 'service-container';
  
  try {
    console.log('Restarting container...');
    
    // راه‌اندازی مجدد
    await k3.containerCore.restartContainer(containerId, {
      time: 20
    });
    
    console.log('Container restarted, waiting for startup...');
    
    // انتظار برای startup
    await new Promise(resolve => setTimeout(resolve, 3000));
    
    // بررسی وضعیت نهایی
    const inspect = await k3.containerCore.inspectContainer(containerId);
    console.log(`Final state: ${inspect.state?.running ? 'running' : 'stopped'}`);
    console.log(`New PID: ${inspect.state?.pid}`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 8: راه‌اندازی مجدد با بررسی منابع

(async () => {
  const k3 = new K3Core();
  const containerId = 'resource-container';
  
  try {
    // Step 1: بررسی منابع قبل
    const inspect = await k3.containerCore.inspectContainer(containerId);
    console.log('Before restart:');
    console.log(`Memory limit: ${inspect.hostConfig?.memory}`);
    console.log(`CPU shares: ${inspect.hostConfig?.cpuShares}`);
    
    // Step 2: راه‌اندازی مجدد
    const result = await k3.containerCore.restartContainer(containerId, {
      time: 15,
      debug: true
    });
    
    console.log('Restart output:', result);
    
    // Step 3: بررسی منابع بعد
    const newInspect = await k3.containerCore.inspectContainer(containerId);
    console.log('After restart:');
    console.log(`Memory limit: ${newInspect.hostConfig?.memory}`);
    console.log(`CPU shares: ${newInspect.hostConfig?.cpuShares}`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

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

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

خطا: ContainerRecord (404)

راهنمای حل:

try {
  await k3.containerCore.restartContainer('invalid-container', { time: 10 });
} catch (error) {
  if (error.type === 'NOT_FOUND') {
    const allContainers = await k3.containerCore.listContainers({ all: true });
    console.log('Available containers:', allContainers.map(c => c.name));
    
    const container = allContainers.find(c => c.name.includes('target'));
    if (container) {
      await k3.containerCore.restartContainer(container.id, { time: 10 });
    }
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 2: راه‌اندازی مجدد محتاط

راهنمای حل:

const safeRestartContainer = async (containerId, timeoutSeconds = 40) => {
  try {
    // Step 1: بررسی وضعیت
    const inspect = await k3.containerCore.inspectContainer(containerId);
    
    if (!inspect) {
      console.log(`Container ${containerId} not found`);
      return false;
    }
    
    console.log(`Restarting container: ${inspect.name}`);
    console.log(`Current PID: ${inspect.state?.pid}`);
    
    // Step 2: راه‌اندازی مجدد
    const result = await k3.containerCore.restartContainer(containerId, {
      time: timeoutSeconds
    });
    
    console.log('Restart signal sent');
    
    // Step 3: انتظار برای startup
    await new Promise(resolve => setTimeout(resolve, 2000));
    
    // Step 4: بررسی وضعیت نهایی
    const finalInspect = await k3.containerCore.inspectContainer(containerId);
    
    if (finalInspect.state?.running) {
      console.log(`Container restarted successfully with new PID: ${finalInspect.state?.pid}`);
    } else {
      console.log('Container not running after restart');
    }
    
    return true;
    
  } catch (error) {
    console.log(`Failed to restart container: ${error.message}`);
    return false;
  }
};

await safeRestartContainer('my-container', 30);

الگو 3: راه‌اندازی مجدد با timeout

راهنمای حل:

const restartWithTimeout = async (containerId, maxWaitTime = 60000) => {
  return Promise.race([
    (async () => {
      const result = await k3.containerCore.restartContainer(containerId, {
        time: Math.floor(maxWaitTime / 1000)
      });
      console.log('Container restarted within timeout');
      return result;
    })(),
    
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error('Restart operation timeout')), maxWaitTime)
    )
  ]);
};

try {
  await restartWithTimeout('my-container', 60000);
} catch (error) {
  if (error.message === 'Restart operation timeout') {
    console.log('Restart operation timed out');
  } else {
    console.log(error.message);
  }
}

نکات عملی

Time Parameter:
- time: 0 - راه‌اندازی مجدد فوری
- time: 15 - 15 ثانیه انتظار
- time: 30 - 30 ثانیه انتظار برای graceful shutdown
Grace Period:
- کانتینر فرصت دارد تا خودش را مرتب ببند
- منابع تمیز می‌شوند
- connections بسته می‌شوند
دنباله عملیات:
- Remove → Create → Update Resources → Start
- تمام اتصالات قطع می‌شوند
- فایل‌های موقتی حفظ می‌شوند
وضعیت دیتابیس:
- PID جدید ثبت می‌شود
- RestartAttempts بروزرسانی می‌شود
- تمام flags بروزرسانی می‌شوند
منابع:
- منابع قبلی بروزرسانی می‌شوند اگر تغییر یافته باشند
- UpdatedResources بررسی می‌شود
Webhooks:
- event: "container restarted" ارسال می‌شود

مراحل راه‌اندازی مجدد

Validation options
Resolve container name/ID
Wait for grace period (time)
Remove container
Fetch container details
Create veth pair if needed
Create container
Get new PID
Update restart attempts
Update container state
Update resources if changed
Start container
Send webhook notification

مرجع سریع

وضعیت	کد	توضیح
موفق	200	کانتینر دوباره شروع شد
یافت نشد	404	ContainerRecord
گزینه نامعتبر	422	OptionConflict
خطای دیتابیس	500	ResolveContainerName
خطای remove	500	RemoveFailure
خطای create	500	CreateFailure
خطای start	500	StartFailure
خطای منابع	500	UpdateResourcesFailure

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

🧩 دستور کلی​

شرح عملکرد​

ورودی‌ها​

خروجی​

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

ContainerRecord (404)​

ResolveContainerName (500)​

BuildRemoveDTO (422)​

RemoveFailure (500)​

FetchContainerState (500)​

CreateVethFail (500)​

❌ CreateFailure (500)​

❌ PIDNotFound (404)​

RestartAttemptsUpdate (500)​

UpdateStateDuringRestart (500)​

UpdateResourcesFailure (500)​

BuildStartDTO (422)​

StartFailure (500)​

OptionConflict (422)​

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

مثال 1: راه‌اندازی مجدد کانتینر ساده​

مثال 2: راه‌اندازی مجدد کانتینر با زمان انتظار​

مثال 3: راه‌اندازی مجدد کانتینر با debug mode​

مثال 4: راه‌اندازی مجدد فوری​

مثال 5: راه‌اندازی مجدد با بررسی قبلی​

مثال 6: راه‌اندازی مجدد چند کانتینر​

مثال 7: راه‌اندازی مجدد و انتظار برای آمادگی​

مثال 8: راه‌اندازی مجدد با بررسی منابع​

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

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

الگو 2: راه‌اندازی مجدد محتاط​

الگو 3: راه‌اندازی مجدد با timeout​

نکات عملی​

مراحل راه‌اندازی مجدد​

مرجع سریع​

🧩 دستور کلی

شرح عملکرد

ورودی‌ها

خروجی

استثناها (Errors)

ContainerRecord (404)

ResolveContainerName (500)

BuildRemoveDTO (422)

RemoveFailure (500)

FetchContainerState (500)

CreateVethFail (500)

❌ CreateFailure (500)

❌ PIDNotFound (404)

RestartAttemptsUpdate (500)

UpdateStateDuringRestart (500)

UpdateResourcesFailure (500)

BuildStartDTO (422)

StartFailure (500)

OptionConflict (422)

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

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

مثال 2: راه‌اندازی مجدد کانتینر با زمان انتظار

مثال 3: راه‌اندازی مجدد کانتینر با debug mode

مثال 4: راه‌اندازی مجدد فوری

مثال 5: راه‌اندازی مجدد با بررسی قبلی

مثال 6: راه‌اندازی مجدد چند کانتینر

مثال 7: راه‌اندازی مجدد و انتظار برای آمادگی

مثال 8: راه‌اندازی مجدد با بررسی منابع

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

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

الگو 2: راه‌اندازی مجدد محتاط

الگو 3: راه‌اندازی مجدد با timeout

نکات عملی

مراحل راه‌اندازی مجدد

مرجع سریع