پرش به مطلب اصلی

وارد کردن ایمیج از فایل TAR

ایمیج را از فایل TAR وارد کرده و در رجیستری ثبت می‌کند.

🧩 دستور کلی​

async importImage(imageId, tagName = "latest", filePath)

شرح عملکرد​

این متد ایمیج را از فایل TAR وارد کرده و در رجیستری ثبت می‌کند. شامل:

  • اعتبارسنجی پارامترهای وارد‌کردن
  • بررسی وجود فایل TAR
  • بررسی عدم وجود ایمیج قبلی
  • ایجاد نام موقت برای پردازش
  • وارد کردن tarball به موقعیت موقت
  • خواندن پیکربندی برای یافتن بیس ایمیج
  • افزودن filesystem layer
  • کپی به مسیر نهایی
  • پیوند blob‌های ایمیج
  • تمیزکاری دایرکتوری موقت
  • ثبت در دیتابیس
  • logging عملیات

مهم: فایل TAR باید معتبر باشد. وارد‌کردن خودکار تمام لایه‌های ایمیج را مدیریت می‌کند.

ورودی‌ها​

پارامترنوعاجباریپیش‌فرضتوضیح
imageIdStringبله-شناسه ایمیج (مثلاً myapp, myrepo/myapp)
tagNameStringخیر"latest"تگ ایمیج (مثلاً v1.0, stable, alpine)
filePathStringبله-مسیر کامل فایل TAR (مثلاً /tmp/myapp.tar, /import/image.tar.gz)

خروجی​

نوع: String

پیام موفقیت:

myapp:latest has imported successfully

یا:

myrepo/myapp:v1.0 has imported successfully

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

InvalidImportImageParameters (422)​

پیام: "Invalid import image parameters."

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

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "imageId": "invalid@image",
  "tagName": "latest",
  "filePath": "/tmp/image.tar",
  "error": "Image ID contains invalid characters"
}

راهنمای حل:

  • شناسه ایمیج: فقط حروف، اعداد، '-', '_', '/' مجاز
  • تگ: فقط حروف، اعداد، '.', '-' مجاز
  • مسیر فایل باید معتبر باشد

ImportTarfileNotFound (404)​

پیام: "Import tarfile not found."

زمان رخ دادن: فایل TAR موجود نیست

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "filePath": "/tmp/nonexistent.tar",
  "error": "File not found"
}

راهنمای حل:

  • مسیر فایل را بررسی کنید
  • فایل واقعاً موجود است؟
  • مسیر مطلق استفاده کنید

FetchImageState (500)​

پیام: "Failed to check image state in database."

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

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "tagName": "latest",
  "error": "Database query failed"
}

راهنمای حل:

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

ImageAlreadyExists (409)​

پیام: "Image already exists in local registry."

زمان رخ دادن: ایمیج با همین شناسه و تگ قبلاً موجود است

جزئیات:

{
  "type": "INVALID_STATE_ERROR",
  "statusCode": 409,
  "imageId": "myapp",
  "tagName": "latest",
  "error": "Image already exists"
}

راهنمای حل:

  • تگ متفاوتی استفاده کنید
  • ایمیج قبلی را حذف کنید
  • شناسه ایمیج را تغییر دهید

ImportTarballFailure (500)​

پیام: "Failed to import tarball."

زمان رخ دادن: خطا در وارد کردن فایل TAR

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "filePath": "/tmp/myapp.tar",
  "error": "Tarball import failed"
}

راهنمای حل:

  • فایل TAR معتبر است؟
  • فرمت فایل صحیح است؟
  • فضای دیسک کافی است؟

ReadImportedConfigFailure (500)​

پیام: "Failed to read imported config."

زمان رخ دادن: خطا در خواندن پیکربندی ایمیج وارد‌شده

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "tempName": "abc123def456",
  "error": "Config file not found"
}

راهنمای حل:

  • فایل TAR صحیح است؟
  • config.json موجود است؟

AddFsLayerFailure (500)​

پیام: "Failed to add filesystem layer."

زمان رخ دادن: خطا در افزودن filesystem layer

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "tagName": "latest",
  "error": "Layer addition failed"
}

راهنمای حل:

  • ImageManager را بررسی کنید
  • فضای دیسک کافی است؟

CopyImportedImageFailure (500)​

پیام: "Failed to copy imported image."

زمان رخ دادن: خطا در کپی ایمیج وارد‌شده

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "fromImage": "base:temp",
  "toImage": "myapp:latest",
  "error": "Image copy failed"
}

راهنمای حل:

  • RegistryManager را بررسی کنید
  • فضای دیسک کافی است؟

LinkBlobsFailure (500)​

پیام: "Failed to link image blobs."

زمان رخ دادن: خطا در پیوند blob‌های ایمیج

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "error": "Blob linking failed"
}

راهنمای حل:

  • دایرکتوری blob‌ها موجود است؟
  • فایل‌های blob معتبر هستند؟

FindBlobsFailure (500)​

پیام: "Failed to find image blobs."

زمان رخ دادن: خطا در یافتن blob‌های ایمیج

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "tagName": "latest",
  "error": "Blob scanning failed"
}

راهنمای حل:

  • دایرکتوری ایمیج موجود است؟
  • فایل‌های blob معتبر هستند؟

CreateImageBlobFailure (500)​

پیام: "Failed to create blob record in database."

زمان رخ دادن: خطا در ایجاد رکورد blob در DB

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "tagName": "latest",
  "error": "Database write failed"
}

راهنمای حل:

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

CalculateImageSizeFailure (500)​

پیام: "Failed to calculate image size."

زمان رخ دادن: خطا در محاسبه اندازه ایمیج

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "tagName": "latest",
  "error": "Size calculation failed"
}

راهنمای حل:

  • دایرکتوری ایمیج موجود است؟
  • اجازه‌های خواندن موجود است؟

FetchImageHistoryFailure (500)​

پیام: "Failed to fetch image history."

زمان رخ دادن: خطا در دریافت تاریخچه ایمیج

جزئیات:

{
  "type": "IMAGE_SERVICE_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "tagName": "latest",
  "error": "History fetch failed"
}

راهنمای حل:

  • ImageManager را بررسی کنید
  • metadata ایمیج موجود است؟

CreateImageRecordFailure (500)​

پیام: "Failed to create image record in database."

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

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "imageId": "myapp",
  "tagName": "latest",
  "error": "Database write failed"
}

راهنمای حل:

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

GenericFailure (500)​

پیام: "Generic failure during image import."

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

جزئیات:

{
  "type": "GENERIC_ERROR",
  "statusCode": 500,
  "error": "Image import failed"
}

راهنمای حل:

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

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

مثال 1: وارد کردن ایمیج ساده​

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.imageCore.importImage(
      'myapp',
      'latest',
      '/tmp/myapp.tar'
    );
    console.log('Success:', result);
    // Output: myapp:latest has imported successfully
  } catch (error) {
    console.log('ERROR:', error.createFullMessage());
  }
})();

مثال 2: وارد کردن با تگ خاص​

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.imageCore.importImage(
      'nginx',
      'v1.0',
      '/home/user/nginx-v1.0.tar'
    );
    console.log('Import result:', result);
    console.log('Image nginx:v1.0 imported successfully');
  } catch (error) {
    console.log('ERROR: Failed to import image');
    console.log(error.message);
  }
})();

مثال 3: وارد کردن و verify​

(async () => {
  const k3 = new K3Core();
  
  try {
    // Step 1: Import
    console.log('Importing image...');
    const importResult = await k3.imageCore.importImage(
      'alpine',
      'latest',
      '/tmp/alpine-latest.tar'
    );
    console.log('Import result:', importResult);
    
    // Step 2: Verify
    console.log('Verifying image...');
    const imageList = await k3.imageCore.listImages({ image: 'alpine' });
    
    console.log('Image verified:');
    console.log(`  Total tags: ${imageList.length}`);
    imageList.forEach(img => {
      console.log(`  - ${img.Name}:${img.Tag}`);
    });
  } catch (error) {
    console.log('ERROR:', error.message);
  }
})();

مثال 4: وارد کردن چند ایمیج​

(async () => {
  const k3 = new K3Core();
  
  const tarFiles = [
    { id: 'alpine', tag: 'latest', path: '/tmp/alpine.tar' },
    { id: 'nginx', tag: 'stable', path: '/tmp/nginx.tar' },
    { id: 'node', tag: '18', path: '/tmp/node.tar' }
  ];
  
  const results = [];
  
  for (const tar of tarFiles) {
    try {
      const result = await k3.imageCore.importImage(tar.id, tar.tag, tar.path);
      results.push({
        image: `${tar.id}:${tar.tag}`,
        status: 'success',
        message: result
      });
      console.log(`✓ ${tar.id}:${tar.tag} imported`);
    } catch (error) {
      results.push({
        image: `${tar.id}:${tar.tag}`,
        status: 'failed',
        error: error.message
      });
      console.log(`✗ Failed to import ${tar.id}:${tar.tag}`);
    }
  }
  
  console.log('\nImport Summary:');
  console.table(results);
})();

مثال 5: وارد کردن با مدیریت خطاهای مختلف​

(async () => {
  const k3 = new K3Core();
  const fs = require('fs');
  
  const importWithErrorHandling = async (imageId, tagName, filePath) => {
    try {
      // Check file exists
      if (!fs.existsSync(filePath)) {
        return { success: false, error: 'File not found' };
      }
      
      // Check file size
      const stats = fs.statSync(filePath);
      console.log(`Importing ${imageId}:${tagName} (${(stats.size / 1024 / 1024).toFixed(2)} MB)...`);
      
      const result = await k3.imageCore.importImage(imageId, tagName, filePath);
      return { success: true, message: result };
    } catch (error) {
      if (error.statusCode === 404) {
        console.log(`ERROR: File ${filePath} not found`);
        return { success: false, error: 'File not found' };
      } else if (error.statusCode === 409) {
        console.log(`ERROR: Image ${imageId}:${tagName} already exists`);
        return { success: false, error: 'Image already exists' };
      } else if (error.statusCode === 422) {
        console.log('ERROR: Invalid parameters');
        return { success: false, error: 'Invalid parameters' };
      } else {
        console.log(`ERROR: Import failed - ${error.message}`);
        return { success: false, error: error.message };
      }
    }
  };
  
  const result = await importWithErrorHandling('myapp', 'v1.0', '/tmp/myapp.tar');
  console.log('Result:', result);
})();

مثال 6: وارد کردن و استفاده فوری​

(async () => {
  const k3 = new K3Core();
  
  try {
    // Step 1: Import
    console.log('Step 1: Importing image...');
    const importResult = await k3.imageCore.importImage(
      'myapp',
      'v1.0',
      '/tmp/myapp-latest.tar'
    );
    console.log('✓ Image imported:', importResult);
    
    // Step 2: Verify
    console.log('Step 2: Verifying image...');
    const imageInfo = await k3.imageCore.inspectAnImage('myapp', {
      imageName: 'myapp',
      imageTag: 'v1.0'
    });
    console.log('✓ Image verified');
    console.log(`  Size: ${(imageInfo.LayersData.reduce((s, l) => s + l.Size, 0) / 1024 / 1024).toFixed(2)} MB`);
    
    // Step 3: Create container (optional)
    console.log('Step 3: Creating container from imported image...');
    const containerResult = await k3.containerCore.createContainer({
      imageName: 'myapp',
      imageTag: 'v1.0',
      containerId: 'myapp-instance-001',
      containerPort: 3000,
      hostPort: 8080
    });
    console.log('✓ Container created');
    
    console.log('\n✓ Successfully imported and deployed');
  } catch (error) {
    console.log('ERROR:', error.message);
  }
})();

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

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

خطا: ImportTarfileNotFound (404)

راهنمای حل:

const importWithFileCheck = async (imageId, tagName, filePath) => {
  const fs = require('fs');
  
  try {
    // Check file exists
    if (!fs.existsSync(filePath)) {
      console.log(`File not found: ${filePath}`);
      console.log('Available files in directory:');
      const dir = filePath.substring(0, filePath.lastIndexOf('/'));
      const files = fs.readdirSync(dir).filter(f => f.endsWith('.tar'));
      files.forEach(f => console.log(`  - ${f}`));
      throw new Error(`File ${filePath} does not exist`);
    }
    
    console.log(`Importing from: ${filePath}`);
    const result = await k3.imageCore.importImage(imageId, tagName, filePath);
    return result;
  } catch (error) {
    console.log('ERROR:', error.message);
    throw error;
  }
};

await importWithFileCheck('myapp', 'latest', '/tmp/myapp.tar');

الگو 2: ایمیج قبلاً موجود است​

خطا: ImageAlreadyExists (409)

راهنمای حل:

const importOrReplace = async (imageId, tagName, filePath, replace = false) => {
  try {
    const result = await k3.imageCore.importImage(imageId, tagName, filePath);
    return { success: true, message: result };
  } catch (error) {
    if (error.statusCode === 409 && replace) {
      console.log(`Image ${imageId}:${tagName} already exists. Removing...`);
      
      try {
        await k3.imageCore.removeAnImage(imageId, tagName);
        console.log('Old image removed');
        
        // Retry import
        const retryResult = await k3.imageCore.importImage(imageId, tagName, filePath);
        return { success: true, message: retryResult, replaced: true };
      } catch (removeError) {
        return { success: false, error: `Failed to remove old image: ${removeError.message}` };
      }
    } else if (error.statusCode === 409) {
      console.log(`Image ${imageId}:${tagName} already exists`);
      console.log('Use replace=true to overwrite');
      return { success: false, error: 'Image already exists' };
    }
    throw error;
  }
};

await importOrReplace('myapp', 'latest', '/tmp/myapp.tar', true);

الگو 3: فایل TAR نامعتبر​

خطا: ImportTarballFailure (500)

راهنمای حل:

const importWithValidation = async (imageId, tagName, filePath) => {
  const fs = require('fs');
  
  try {
    // Step 1: Validate file
    console.log('Step 1: Validating tar file...');
    const stats = fs.statSync(filePath);
    console.log(`  File size: ${(stats.size / 1024 / 1024).toFixed(2)} MB`);
    console.log(`  File type: ${filePath.endsWith('.gz') ? 'gzip' : 'uncompressed'}`);
    
    // Step 2: Check if tar
    if (!filePath.endsWith('.tar') && !filePath.endsWith('.tar.gz')) {
      throw new Error('File must be .tar or .tar.gz format');
    }
    
    // Step 3: Try to import
    console.log('Step 2: Importing image...');
    const result = await k3.imageCore.importImage(imageId, tagName, filePath);
    
    console.log('✓ Import successful');
    return { success: true, message: result };
  } catch (error) {
    if (error.statusCode === 500) {
      console.log('ERROR: Failed to import tar file');
      console.log('Possible causes:');
      console.log('  - File is corrupted');
      console.log('  - Format is not valid');
      console.log('  - Insufficient disk space');
    }
    return { success: false, error: error.message };
  }
};

await importWithValidation('myapp', 'latest', '/tmp/myapp.tar');

الگو 5: وارد کردن و استفاده​

راهنمای حل:

class ImageImportAndDeploy {
  constructor(k3) {
    this.k3 = k3;
  }
  
  async importAndDeploy(imageId, tagName, filePath, deploymentOptions = {}) {
    try {
      // Step 1: Import
      console.log('Step 1: Importing image...');
      const importResult = await this.k3.imageCore.importImage(imageId, tagName, filePath);
      console.log(`✓ Image imported: ${imageId}:${tagName}`);
      
      // Step 2: Verify
      console.log('Step 2: Verifying image...');
      const imageInfo = await this.k3.imageCore.inspectAnImage(imageId, {
        imageName: imageId,
        imageTag: tagName
      });
      console.log(`✓ Image verified - Size: ${(imageInfo.LayersData.reduce((s, l) => s + l.Size, 0) / 1024 / 1024).toFixed(2)} MB`);
      
      // Step 3: Deploy
      console.log('Step 3: Deploying containers...');
      const replicas = deploymentOptions.replicas || 1;
      
      for (let i = 0; i < replicas; i++) {
        const contId = `${imageId}-replica-${i}`;
        
        await this.k3.containerCore.createContainer({
          imageName: imageId,
          imageTag: tagName,
          containerId: contId,
          ...deploymentOptions
        });
        
        console.log(`✓ Container created: ${contId}`);
      }
      
      console.log(`\n✓ Successfully deployed ${replicas} replicas`);
      return { success: true, image: `${imageId}:${tagName}`, replicas: replicas };
    } catch (error) {
      console.log('ERROR:', error.message);
      return { success: false, error: error.message };
    }
  }
}

const deployer = new ImageImportAndDeploy(k3);
await deployer.importAndDeploy('myapp', 'v1.0', '/tmp/myapp.tar', {
  replicas: 2,
  containerPort: 3000,
  hostPort: 8080
});

نکات عملی​

  1. فرمت فایل:

    • باید TAR یا TAR.GZ باشد
    • فرمت OCI یا Docker
    • فایل معتبر و دستخوری نشده

  2. مسیر فایل:

    • مسیر مطلق استفاده کنید
    • اجازه‌های خواندن موجود باشد
    • فایل موجود باشد

  3. فضای دیسک:

    • فایل TAR + extracted size نیاز است
    • حداقل 2x اندازه فایل TAR

  4. پیکربندی:

    • config.json باید موجود باشد
    • بیس ایمیج باید معتبر باشد

  5. Performance:

    • وارد‌کردن فایل‌های بزرگ زمان‌بر است
    • compression باعث کاهش سرعت می‌شود

  6. تمیزکاری:

    • دایرکتوری موقت خودکار تمیز می‌شود
    • اگر خطا رخ دهد cleanup انجام می‌شود

دنباله عملیات​

  1. اعتبارسنجی پارامترها
  2. بررسی وجود فایل TAR
  3. بررسی عدم وجود ایمیج
  4. ایجاد نام موقت
  5. وارد کردن tarball
  6. خواندن پیکربندی
  7. افزودن filesystem layer
  8. کپی به مسیر نهایی
  9. پیوند blob‌ها
  10. تمیزکاری موقت
  11. ثبت در دیتابیس
  12. Logging موفقیت

مرجع سریع​

وضعیتکدتوضیح
موفق200وارد‌کردن موفق
پارامتر نامعتبر422InvalidImportImageParameters
فایل یافت نشد404ImportTarfileNotFound
DB خطا500FetchImageState
ایمیج موجود409ImageAlreadyExists
tarball خطا500ImportTarballFailure
config خطا500ReadImportedConfigFailure
layer خطا500AddFsLayerFailure
copy خطا500CopyImportedImageFailure
blobs خطا500LinkBlobsFailure/FindBlobsFailure
اندازه خطا500CalculateImageSizeFailure
history خطا500FetchImageHistoryFailure
DB record خطا500CreateImageRecordFailure
خطای عمومی500GenericFailure

موارد استفاده​

Image Restoration​

const result = await importImage('myapp', 'latest', '/backups/myapp.tar');

Offline Migration​

const result = await importImage('app', 'v1.0', '/migration/app.tar');

Development Setup​

const result = await importImage('dev-env', 'latest', '/dev/environment.tar');

Batch Import​

const files = ['/imports/image1.tar', '/imports/image2.tar'];
for (const file of files) {
  await importImage('app', 'latest', file);
}

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