مشاهده اطلاعات کانتینر

کانتینر مشخص شده را برای دریافت اطلاعات سطح پایین و جامع کوئری می‌کند.

---

🧩 دستور کلی

async inspectContainer(containerId, options = {})

---

شرح عملکرد

این متد اطلاعات دقیق و کامل درباره کانتینر مشخص شده را برمی‌گرداند. شامل وضعیت، پیکربندی، تنظیمات شبکه، محدودیت‌های منابع، capabilities، mounts و سایر جزئیات سطح پایین است.

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

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
containerId	String	✅ بله	شناسه یا نام کانتینر برای دریافت اطلاعات
options	Object	خیر	گزینه‌های اختیاری (فعلاً بدون گزینه)

---

خروجی

نوع: Object (شامل تمامی اطلاعات کانتینر)

خروجی شامل اطلاعات جامع کانتینر:

{
  "id": "f1ecea48de222c5c",
  "created": "2025-11-30T06:55:35.814Z",
  "args": "tail -f /dev/null",
  "state": {
    "running": true,
    "paused": false,
    "restartPolicy": null,
    "oomKilled": true,
    "failed": false,
    "pid": 24006,
    "exitCode": "none",
    "error": ""
  },
  "image": "alpine:latest",
  "name": "111",
  "config": {
    "hostname": "K3",
    "user": { "uid": 0, "gid": 0 },
    "env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
    "cmd": "tail -f /dev/null",
    "workingDir": "/"
  },
  "hostConfig": {
    "resources": {
      "memory": {
        "limit": 6228119552,
        "reservation": 6228119552,
        "swap": 6228119552
      },
      "cpu": {
        "shares": 1024,
        "quota": 1000000,
        "period": 500000
      }
    }
  },
  "networkSettings": {
    "networks": [
      {
        "network": "kb0",
        "IPv4Address": "192.168.100.2/24",
        "MacAddress": "F2:EC:EA:48:DE:22"
      }
    ]
  },
  "mounts": [],
  "capabilities": {},
  "namespaces": []
}

فیلدهای اصلی:

State (وضعیت)

• running - آیا کانتینر در حال اجرا است
• paused - آیا کانتینر متوقف موقتی است
• pid - Process ID اصلی کانتینر
• oomKilled - آیا کانتینر توسط OOM Killer کشته شده است
• exitCode - کد خروج کانتینر

Config (پیکربندی)

• hostname - نام میزبان کانتینر
• user - UID و GID کاربر
• env - متغیرهای محیطی
• cmd - دستور شروع
• image - نام تصویر

HostConfig (پیکربندی میزبان)

• resources.memory - محدودیت‌های حافظه
• resources.cpu - محدودیت‌های CPU

NetworkSettings (تنظیمات شبکه)

• networks - شبکه‌های متصل
• IPv4Address - آدرس IP
• MacAddress - آدرس MAC

Mounts (نقاط اتصال)

• destination - مسیر داخل کانتینر
• source - مسیر در میزبان
• type - نوع mount (bind, tmpfs, proc، ...)

Capabilities (توانایی‌ها)

• bounding - Capabilities محدود شده
• effective - Capabilities موثر
• permitted - Capabilities مجاز
• inheritable - Capabilities موروثی
• ambient - Capabilities محیطی

Namespaces (فضای نام)

• type - نوع namespace (pid, ipc, uts, mount, user, network)

---

استثناها (Errors)

ContainerNotFound / ContainerRecord (404)

پیام: "Container record not found"

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

جزئیات:

{
  "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 inspect options."

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

جزئیات:

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

راهنمای حل:

• گزینه‌های ورودی را بررسی کنید
• از schema صحیح استفاده کنید

---

ContainerService (500)

پیام: "Container service error."

زمان رخ دادن: خطا در سرویس کانتینر یا Runtime

جزئیات:

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

راهنمای حل:

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

---

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

مثال 1: دریافت اطلاعات کانتینر ساده

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const inspect = await k3.containerCore.inspectContainer('my-container');
    
    if (!inspect) {
      console.log('Container inspect returned null');
      return;
    }
    
    console.log('Container Information:');
    console.log(`Name: ${inspect.name}`);
    console.log(`ID: ${inspect.id}`);
    console.log(`Running: ${inspect.state.running}`);
    console.log(`PID: ${inspect.state.pid}`);
    console.log(`Image: ${inspect.image}`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 2: بررسی وضعیت و محدودیت‌های منابع

(async () => {
  const k3 = new K3Core();
  
  try {
    const inspect = await k3.containerCore.inspectContainer('monitored-container');
    
    if (!inspect) {
      console.log('Container not found');
      return;
    }
    
    // Container state
    console.log('Container State:');
    console.log(`  Running: ${inspect.state.running}`);
    console.log(`  Paused: ${inspect.state.paused}`);
    console.log(`  OOM Killed: ${inspect.state.oomKilled}`);
    console.log(`  Exit Code: ${inspect.state.exitCode}`);
    
    // Resource limits
    const memLimit = inspect.hostConfig?.resources?.memory?.limit;
    const cpuQuota = inspect.hostConfig?.resources?.cpu?.quota;
    
    console.log('Resource Limits:');
    console.log(`  Memory: ${(memLimit / 1024 / 1024 / 1024).toFixed(2)}GB`);
    console.log(`  CPU Quota: ${cpuQuota}`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: بررسی تنظیمات شبکه

(async () => {
  const k3 = new K3Core();
  
  try {
    const inspect = await k3.containerCore.inspectContainer('network-container');
    
    if (!inspect) return;
    
    console.log('Network Configuration:');
    inspect.networkSettings?.networks?.forEach(net => {
      console.log(`  Network: ${net.network}`);
      console.log(`  IPv4: ${net.IPv4Address}`);
      console.log(`  MAC: ${net.MacAddress}`);
    });
    
    // Hostname and DNS
    console.log('Host Settings:');
    console.log(`  Hostname: ${inspect.config?.hostname}`);
    console.log(`  Domain: ${inspect.config?.domainname || 'N/A'}`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 4: بررسی Capabilities و Namespaces

(async () => {
  const k3 = new K3Core();
  
  try {
    const inspect = await k3.containerCore.inspectContainer('security-container');
    
    if (!inspect) return;
    
    console.log('Security Configuration:');
    
    // Capabilities
    const caps = inspect.capabilities;
    console.log('Capabilities:');
    console.log(`  Effective: ${caps?.effective?.length || 0} capabilities`);
    console.log(`  Permitted: ${caps?.permitted?.length || 0} capabilities`);
    
    if (caps?.effective?.length > 0) {
      console.log('  First 5 effective:');
      caps.effective.slice(0, 5).forEach(cap => {
        console.log(`    - ${cap}`);
      });
    }
    
    // Namespaces
    console.log('Namespaces:');
    inspect.namespaces?.forEach(ns => {
      console.log(`  - ${ns.type}`);
    });
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 5: بررسی نقاط اتصال (Mounts)

(async () => {
  const k3 = new K3Core();
  
  try {
    const inspect = await k3.containerCore.inspectContainer('volume-container');
    
    if (!inspect) return;
    
    console.log('Mount Points:');
    inspect.mounts?.forEach(mount => {
      console.log(`  Destination: ${mount.destination}`);
      console.log(`  Source: ${mount.source}`);
      console.log(`  Type: ${mount.type}`);
      console.log(`  Options: ${mount.options?.join(', ') || 'none'}`);
      console.log('---');
    });
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: بررسی محیط و متغیرهای کانتینر

(async () => {
  const k3 = new K3Core();
  
  try {
    const inspect = await k3.containerCore.inspectContainer('app-container');
    
    if (!inspect) return;
    
    console.log('Container Configuration:');
    console.log(`Name: ${inspect.name}`);
    console.log(`Image: ${inspect.image}`);
    console.log(`Created: ${new Date(inspect.created).toLocaleString()}`);
    
    console.log('Command:');
    console.log(`  ${inspect.config?.cmd}`);
    
    console.log('Environment Variables:');
    inspect.config?.env?.forEach(envVar => {
      const [key, value] = envVar.split('=');
      console.log(`  ${key}: ${value}`);
    });
    
    console.log('User:');
    console.log(`  UID: ${inspect.config?.user?.uid}`);
    console.log(`  GID: ${inspect.config?.user?.gid}`);
    
    console.log('Working Directory:');
    console.log(`  ${inspect.config?.workingDir}`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

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

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

خطا: ContainerNotFound / ContainerRecord (404)

راهنمای حل:

try {
  const inspect = await k3.containerCore.inspectContainer('invalid-container');
} 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 the correct container
    const container = allContainers.find(c => c.name.includes('my'));
    if (container) {
      const inspect = await k3.containerCore.inspectContainer(container.id);
      console.log('Inspect successful');
    }
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 2: اطلاعات خالی

راهنمای حل:

try {
  const inspect = await k3.containerCore.inspectContainer('my-container');
  
  if (!inspect) {
    console.log('Container inspect returned null');
    console.log('This may indicate the container record is incomplete');
    return;
  }
  
  // Process inspect data
  console.log(`Container: ${inspect.name}`);
  
} catch (error) {
  console.log(error.createFullMessage());
}

الگو 3: بررسی و تحلیل اطلاعات

راهنمای حل:

const analyzeContainer = async (containerId) => {
  try {
    const inspect = await k3.containerCore.inspectContainer(containerId);
    
    if (!inspect) {
      console.log('Container not found');
      return null;
    }
    
    // Safely access nested properties
    const analysis = {
      isRunning: inspect.state?.running || false,
      isPaused: inspect.state?.paused || false,
      hasOOMKilled: inspect.state?.oomKilled || false,
      memoryLimit: inspect.hostConfig?.resources?.memory?.limit || 'unlimited',
      cpuLimit: inspect.hostConfig?.resources?.cpu?.quota || 'unlimited',
      networks: inspect.networkSettings?.networks?.length || 0,
      mounts: inspect.mounts?.length || 0,
      capabilities: inspect.capabilities?.effective?.length || 0
    };
    
    return analysis;
    
  } catch (error) {
    console.log(error.createFullMessage());
    throw error;
  }
};

const analysis = await analyzeContainer('my-container');
console.log('Analysis:', analysis);

الگو 4: مقایسه اطلاعات چند کانتینر

راهنمای حل:

const compareContainers = async (containerIds) => {
  const inspects = [];
  
  for (const id of containerIds) {
    try {
      const inspect = await k3.containerCore.inspectContainer(id);
      if (inspect) {
        inspects.push({
          name: inspect.name,
          running: inspect.state?.running,
          memoryLimit: inspect.hostConfig?.resources?.memory?.limit,
          cpuShares: inspect.hostConfig?.resources?.cpu?.shares
        });
      }
    } catch (error) {
      console.log(`Failed to inspect ${id}: ${error.message}`);
    }
  }
  
  return inspects;
};

const comparison = await compareContainers(['c1', 'c2', 'c3']);
console.table(comparison);

---

نکات عملی

1. Null Response:

   • ممکن است inspect نتیجه خالی بازگرداند
   • این می‌تواند نشان‌دهنده مشکل در record کانتینر باشد

2. Nested Properties:

   • بسیاری از فیلدها nested هستند
   • از optional chaining (?.) استفاده کنید

3. State Checking:

   • برای اطلاعات state از field state استفاده کنید
   • برای PID از state.pid استفاده کنید

4. Resource Limits:

   • Memory در بایت است (تقسیم بر 1024³ برای GB)
   • CPU quota و period در microseconds هستند

5. Security Info:

   • Capabilities و namespaces برای security assessment مهم‌اند
   • برای محدود کردن امکانات بررسی کنید

6. Network Info:

   • آدرس IP و MAC در networkSettings است
   • می‌توانید متصل شدن به شبکه‌های مختلف بررسی کنید

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	اطلاعات دریافت شدند
یافت نشد	404	ContainerRecord
گزینه نامعتبر	422	OptionConflict
خطای عمومی	500	ContainerService

---

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