کپی فایل‌ها بین میزبان و کانتینر

فایل‌ها و دایرکتوری‌ها را بین میزبان و کانتینر کپی می‌کند.

---

🧩 دستور کلی

async copyFilesToContainer(source, destination, options = {})

---

شرح عملکرد

این متد فایل یا دایرکتوری را از میزبان به کانتینر کپی می‌کند. شامل:

• تأیید مسیر مبدا موجود است
• تأیید مسیر مقصد معتبر است
• کپی فایل یا دایرکتوری
• حفظ اجازه‌های فایل
• logging عملیات

مهم: مسیر مبدا باید روی میزبان موجود باشد. مسیر مقصد باید در قالب containerId:path باشد.

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
source	String	بله	مسیر فایل/دایرکتوری روی میزبان
destination	String	بله	مسیر مقصد: containerId:path
options	Object	بله	گزینه‌های کپی (قابل توسعه)

---

خروجی

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

نمونه خروجی:

File copied successfully
Copied: /host/file.txt to container:/app/file.txt

---

استثناها (Errors)

CopyFailure (500)

پیام: "Failed to copy file to container."

زمان رخ دادن: خطا در عملیات کپی

جزئیات:

{
  "type": "CONTAINER_SERVICE_ERROR",
  "statusCode": 500,
  "source": "/host/file.txt",
  "destination": "container-id:/app/file.txt",
  "error": "Copy operation failed"
}

راهنمای حل:

• مسیر مبدا را بررسی کنید (آیا موجود است؟)
• مسیر مقصد را تأیید کنید
• اجازه‌های فایل را بررسی کنید
• فضای دیسک کانتینر را تأیید کنید
• کانتینر درحال اجرا است یا خیر؟

---

GenericFailure (500)

پیام: "Generic failure during copy operation."

زمان رخ دادن: خطای عمومی در فرآیند کپی

جزئیات:

{
  "type": "GENERIC_ERROR",
  "statusCode": 500,
  "destination": "container-id:/app/file.txt",
  "error": "Unknown error occurred"
}

راهنمای حل:

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

---

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

مثال 1: کپی فایل ساده

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.copyFilesToContainer(
      '/home/user/config.txt',
      'my-container:/app/config.txt',
      {}
    );
    console.log('File copied successfully');
    console.log(result);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 2: کپی دایرکتوری کامل

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.copyFilesToContainer(
      '/home/user/project',
      'web-server:/var/www/project',
      {}
    );
    console.log('Directory copied successfully');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: کپی فایل‌های متعدد با حلقه

(async () => {
  const k3 = new K3Core();
  
  try {
    const files = [
      '/host/file1.txt',
      '/host/file2.txt',
      '/host/file3.txt'
    ];
    
    for (const file of files) {
      await k3.containerCore.copyFilesToContainer(
        file,
        `app-container:/app/${file.split('/').pop()}`,
        {}
      );
      console.log(`Copied: ${file}`);
    }
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 4: کپی فایل‌های تنظیمات

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.copyFilesToContainer(
      '/etc/nginx/nginx.conf',
      'web-server:/etc/nginx/nginx.conf',
      {}
    );
    console.log('Config file copied');
    
    // Verify the copy
    const exec = await k3.containerCore.execInContainer(
      'web-server',
      ['cat', '/etc/nginx/nginx.conf'],
      { detach: false }
    );
    console.log('Config content verified');
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 5: کپی فایل‌های Node.js

(async () => {
  const k3 = new K3Core();
  
  try {
    // کپی package.json
    await k3.containerCore.copyFilesToContainer(
      '/home/dev/package.json',
      'node-app:/app/package.json',
      {}
    );
    
    // کپی دایرکتوری node_modules
    await k3.containerCore.copyFilesToContainer(
      '/home/dev/node_modules',
      'node-app:/app/node_modules',
      {}
    );
    
    console.log('Node.js dependencies copied');
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: کپی فایل اسکریپت شروع

(async () => {
  const k3 = new K3Core();
  
  try {
    // کپی اسکریپت شروع
    await k3.containerCore.copyFilesToContainer(
      '/home/user/start.sh',
      'app-container:/app/start.sh',
      {}
    );
    
    // اجرای اسکریپت
    const result = await k3.containerCore.execInContainer(
      'app-container',
      ['bash', '/app/start.sh'],
      { detach: false }
    );
    
    console.log('Script executed');
    console.log(result);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 7: کپی فایل‌های با بررسی قبلی

(async () => {
  const k3 = new K3Core();
  const sourceFile = '/home/user/data.json';
  const containerId = 'data-processor';
  
  try {
    // Step 1: بررسی کانتینر
    const inspect = await k3.containerCore.inspectContainer(containerId);
    
    if (!inspect) {
      console.log('Container not found');
      return;
    }
    
    if (!inspect.state?.running) {
      console.log('Container not running, starting...');
      await k3.containerCore.startContainer(containerId, {});
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
    
    // Step 2: کپی فایل
    console.log(`Copying ${sourceFile} to container...`);
    const result = await k3.containerCore.copyFilesToContainer(
      sourceFile,
      `${containerId}:/data/data.json`,
      {}
    );
    
    console.log('File copied successfully');
    
    // Step 3: تأیید کپی
    const verification = await k3.containerCore.execInContainer(
      containerId,
      ['ls', '-la', '/data/data.json'],
      { detach: false }
    );
    
    console.log('File verified in container:', verification);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 8: کپی فایل‌های Python

(async () => {
  const k3 = new K3Core();
  
  try {
    // کپی فایل اصلی
    await k3.containerCore.copyFilesToContainer(
      '/home/dev/main.py',
      'python-app:/app/main.py',
      {}
    );
    
    // کپی فایل requirements
    await k3.containerCore.copyFilesToContainer(
      '/home/dev/requirements.txt',
      'python-app:/app/requirements.txt',
      {}
    );
    
    console.log('Python files copied');
    
    // اجرای اسکریپت
    const result = await k3.containerCore.execInContainer(
      'python-app',
      ['python', '/app/main.py'],
      { detach: false }
    );
    
    console.log('Python script output:', result);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

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

الگو 1: فایل منبع یافت نشد

خطا: CopyFailure (500)

راهنمای حل:

const fs = require('fs');

try {
  const sourceFile = '/home/user/file.txt';
  
  // بررسی فایل قبل از کپی
  if (!fs.existsSync(sourceFile)) {
    throw new Error(`Source file not found: ${sourceFile}`);
  }
  
  const result = await k3.containerCore.copyFilesToContainer(
    sourceFile,
    'container:/app/file.txt',
    {}
  );
  
} catch (error) {
  console.log('File copy error:', error.message);
  
  // پیدا کردن فایل در دایرکتوری
  const dir = '/home/user';
  const files = fs.readdirSync(dir);
  console.log('Available files:', files);
}

الگو 2: مسیر مقصد نامعتبر

خطا: CopyFailure (500)

راهنمای حل:

try {
  const destination = 'container-id:/app/file.txt';
  
  // تأیید فرمت مسیر مقصد
  if (!destination.includes(':')) {
    throw new Error('Destination must be in format: containerId:path');
  }
  
  const [containerId, containerPath] = destination.split(':');
  
  if (!containerId || !containerPath) {
    throw new Error('Invalid destination format');
  }
  
  const result = await k3.containerCore.copyFilesToContainer(
    '/host/file.txt',
    destination,
    {}
  );
  
} catch (error) {
  console.log('Destination error:', error.message);
}

الگو 3: فضای دیسک کافی نیست

خطا: CopyFailure (500)

راهنمای حل:

const fs = require('fs');

try {
  const sourceFile = '/home/user/large-file.zip';
  const containerId = 'storage-container';
  
  // بررسی اندازه فایل
  const stats = fs.statSync(sourceFile);
  const fileSizeMB = stats.size / (1024 * 1024);
  
  console.log(`File size: ${fileSizeMB.toFixed(2)} MB`);
  
  // بررسی دیسک کانتینر
  const inspect = await k3.containerCore.inspectContainer(containerId);
  if (!inspect) {
    throw new Error('Container not found');
  }
  
  // اگر فایل خیلی بزرگ است، هشدار بدهید
  if (fileSizeMB > 1000) {
    console.warn('Large file detected, copy may take time');
  }
  
  const result = await k3.containerCore.copyFilesToContainer(
    sourceFile,
    `${containerId}:/data/file.zip`,
    {}
  );
  
} catch (error) {
  console.log('Copy error:', error.message);
}

الگو 4: کپی امن (safe copy)

راهنمای حل:

const fs = require('fs');
const path = require('path');

const safeCopyFilesToContainer = async (source, destination) => {
  try {
    // Step 1: تأیید منبع
    if (!fs.existsSync(source)) {
      throw new Error(`Source not found: ${source}`);
    }
    
    // Step 2: تأیید فرمت مقصد
    if (!destination.includes(':')) {
      throw new Error('Invalid destination format');
    }
    
    const [containerId, containerPath] = destination.split(':');
    
    // Step 3: بررسی کانتینر
    const inspect = await k3.containerCore.inspectContainer(containerId);
    if (!inspect) {
      throw new Error(`Container not found: ${containerId}`);
    }
    
    if (!inspect.state?.running) {
      console.log('Starting container...');
      await k3.containerCore.startContainer(containerId, {});
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
    
    // Step 4: اطلاعات فایل
    const stats = fs.statSync(source);
    const fileName = path.basename(source);
    console.log(`Copying ${fileName} (${(stats.size / 1024).toFixed(2)} KB)`);
    
    // Step 5: کپی
    const result = await k3.containerCore.copyFilesToContainer(
      source,
      destination,
      {}
    );
    
    console.log('Copy completed successfully');
    return result;
    
  } catch (error) {
    console.log(`Safe copy failed: ${error.message}`);
    throw error;
  }
};

// استفاده
await safeCopyFilesToContainer(
  '/home/user/file.txt',
  'app-container:/app/file.txt'
);

الگو 5: کپی دایرکتوری کامل

راهنمای حل:

const fs = require('fs');
const path = require('path');

const copyDirectoryToContainer = async (sourceDir, containerId, containerPath) => {
  try {
    // Step 1: بررسی دایرکتوری
    if (!fs.existsSync(sourceDir)) {
      throw new Error(`Directory not found: ${sourceDir}`);
    }
    
    const isDirectory = fs.statSync(sourceDir).isDirectory();
    if (!isDirectory) {
      throw new Error(`Not a directory: ${sourceDir}`);
    }
    
    // Step 2: بررسی کانتینر
    const inspect = await k3.containerCore.inspectContainer(containerId);
    if (!inspect?.state?.running) {
      throw new Error('Container not running');
    }
    
    // Step 3: ایجاد دایرکتوری داخل کانتینر
    await k3.containerCore.execInContainer(
      containerId,
      ['mkdir', '-p', containerPath],
      {}
    );
    
    // Step 4: کپی دایرکتوری
    console.log(`Copying directory: ${sourceDir}`);
    const result = await k3.containerCore.copyFilesToContainer(
      sourceDir,
      `${containerId}:${containerPath}`,
      {}
    );
    
    // Step 5: تأیید
    const verification = await k3.containerCore.execInContainer(
      containerId,
      ['ls', '-la', containerPath],
      { detach: false }
    );
    
    console.log('Directory copy verified');
    return result;
    
  } catch (error) {
    console.log(`Directory copy failed: ${error.message}`);
    throw error;
  }
};

// استفاده
await copyDirectoryToContainer(
  '/home/user/myproject',
  'app-container',
  '/app/myproject'
);

---

نکات عملی

1. Source Path Format:

   • مسیر کامل روی میزبان
   • مثال: /home/user/file.txt
   • مثال: /var/log/app.log
   • باید موجود باشد

2. Destination Format:

   • باید شامل شناسه کانتینر و مسیر باشد
   • فرمت: containerId:containerPath
   • مثال: my-container:/app/file.txt
   • مثال: 104:/var/www/html/index.html

3. File vs Directory:

   • می‌توانید فایل یا دایرکتوری کپی کنید
   • برای دایرکتوری‌ها، مسیر بدون / انتهایی باشد

4. Permissions:

   • اجازه‌های فایل حفظ می‌شوند
   • به کاربر root نیاز دارید برای دسترسی

5. Container State:

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

6. Large Files:

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

7. Verification:

   • بعد از کپی، فایل را تأیید کنید
   • از execInContainer با ls استفاده کنید

8. Error Handling:

   • همیشه فایل منبع را تأیید کنید
   • مسیر مقصد را بررسی کنید
   • اجازه‌های فایل را بررسی کنید

---

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

1. Validate source path
2. Validate destination format
3. Resolve container ID
4. Check container state (اختیاری)
5. Build copy options
6. Execute copy via container manager
7. Return result
8. Log operation

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	فایل کپی شد
منبع یافت نشد	500	CopyFailure
مقصد نامعتبر	500	CopyFailure
فضای ناکافی	500	CopyFailure
اجازه رد شد	500	CopyFailure
خطای عمومی	500	GenericFailure

---

مثال‌های واقعی

سناریو 1: استقرار برنامه

// کپی کدهای برنامه
await copyFilesToContainer('/home/dev/app/src', 'web-app:/app/src', {});
await copyFilesToContainer('/home/dev/app/package.json', 'web-app:/app/package.json', {});

سناریو 2: کپی فایل‌های پیکربندی

// کپی فایل‌های تنظیمات
await copyFilesToContainer('/etc/app/config.json', 'app:/config/config.json', {});
await copyFilesToContainer('/etc/app/database.yml', 'app:/config/database.yml', {});

سناریو 3: کپی فایل‌های دیتابیس

// کپی فایل seed database
await copyFilesToContainer('/home/user/seed.sql', 'db:/docker-entrypoint-initdb.d/seed.sql', {});

---

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