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

ایجاد شبکه جدید

شبکه جدیدی را با تنظیمات سفارشی ایجاد کرده و تمام واسط‌های شبکه و تنظیمات IP را مدیریت می‌کند.


🧩 دستور کلی

async createNetwork(configs, options = {})

شرح عملکرد

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

  • اعتبارسنجی پارامترهای شبکه (نام، driver، subnet، gateway)
  • بررسی عدم وجود شبکه با همین نام
  • تخصیص خودکار subnet و gateway در صورت نیاز
  • تنظیم IPAM (IP Address Management)
  • ایجاد واسط فیزیکی شبکه
  • تعیین قوانین Firewall (NFTable)
  • ثبت اطلاعات شبکه در دیتابیس
  • Logging عملیات

مهم: درایور شبکه (bridge، host، none، vlan و ...) و تنظیمات آن بسیار حائز اهمیت است.


ورودی‌ها

پارامترنوعاجباریتوضیح
configsObjectبلهپیکربندی شبکه (name, driver, options, subnet, gateway)
optionsObjectخیرگزینه‌های خاص (مثل isBootRestore برای restore در هنگام boot)

ساختار configs

{
name: "my-bridge", // نام شبکه (الزامی، منحصربه‌فرد)
driver: "bridge", // نوع درایور: bridge, host, none, vlan
options: { // گزینه‌های درایور (اختیاری)
// مثال برای VLAN
"parent": "eth0" // برای VLAN
},
subnet: "192.168.0.0/24", // محدوده آدرس (اختیاری - خودکار تخصیص می‌شود)
gateway: "192.168.0.1" // درگاه شبکه (اختیاری - خودکار تخصیص می‌شود)
}

خروجی

نوع: Object

پاسخ موفق:

{
id: "a279434eea2bb32a",
name: "my-br2",
driver: "bridge",
networkIF_name: "kb-a279434eea2b",
options: {},
IPAM: {
options: {},
configs: {
subnet: "192.168.0.0/24",
gateway: "192.168.0.79/24"
}
},
containers: {}
}

استثناها (Errors)

InvalidNetworkConfiguration (422)

پیام: "Invalid network configuration."

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

جزئیات:

{
"type": "VALIDATION_ERROR",
"statusCode": 422,
"name": "my-net",
"error": "Invalid subnet format or name contains special characters"
}

راهنمای حل:

  • نام شبکه: فقط حروف، اعداد، '-', '_' مجاز
  • Subnet: فرمت CIDR معتبر (مثل 192.168.0.0/24)
  • Gateway: IP معتبر در محدوده subnet

CheckNetworkExistenceFailure (500)

پیام: "Failed to check network existence in database."

زمان رخ دادن: خطا در بررسی وجود قبلی شبکه

جزئیات:

{
"type": "DB_ERROR",
"statusCode": 500,
"name": "my-bridge",
"error": "Database connection failed"
}

راهنمای حل:

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

NetworkAlreadyExists (409)

پیام: "Network already exists with this name."

زمان رخ دادن: شبکه‌ای با همین نام قبلاً ایجاد شده

جزئیات:

{
"type": "INVALID_STATE_ERROR",
"statusCode": 409,
"name": "my-bridge",
"error": "Network already exists"
}

راهنمای حل:

  • نام متفاوتی برای شبکه انتخاب کنید
  • شبکه قبلی را حذف کنید (removeNetwork)
  • نام شبکه موجود را بررسی کنید

SubnetAlreadyInUse (500)

پیام: "Subnet already in use by another network."

زمان رخ دادن: Subnet انتخاب‌شده توسط شبکه دیگری استفاده می‌شود

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"subnet": "192.168.0.0/24",
"error": "IP conflict: subnet already used"
}

راهنمای حل:

  • Subnet دیگری انتخاب کنید
  • شبکه‌های موجود را بررسی کنید (listNetworks)
  • شبکه‌های بلااستفاده را حذف کنید

NoAvailableSubnet (500)

پیام: "No available subnet for automatic assignment."

زمان رخ دادن: تمام Subnetهای آزاد تمام شده

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"error": "IP space exhausted"
}

راهنمای حل:

  • Subnet را به صورت دستی تعیین کنید
  • شبکه‌های بلااستفاده را حذف کنید
  • محدوده آدرس‌دهی را گسترش دهید

SetNetworkIPAMFailure (500)

پیام: "Failed to set network IPAM configuration."

زمان رخ دادن: خطا در تنظیم IPAM

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"name": "my-bridge",
"error": "IPAM configuration failed"
}

راهنمای حل:

  • Subnet و gateway معتبر هستند؟
  • NetworkManager را بررسی کنید
  • لاگ‌های سیستم را بررسی کنید

InvalidNetworkDriver (422)

پیام: "Invalid network driver."

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

جزئیات:

{
"type": "VALIDATION_ERROR",
"statusCode": 422,
"driver": "unknown-driver",
"error": "Driver not supported"
}

راهنمای حل:

  • درایورهای معتبر: bridge, host, none, vlan
  • درایور صحیح را انتخاب کنید

InvalidNetworkOption (422)

پیام: "Invalid option for this driver."

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

جزئیات:

{
"type": "VALIDATION_ERROR",
"statusCode": 422,
"driver": "bridge",
"option": "invalid-opt",
"error": "Driver doesn't have any option named invalid-opt"
}

راهنمای حل:

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

MissingRequiredNetworkOption (422)

پیام: "Missing required option for this driver."

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

جزئیات:

{
"type": "VALIDATION_ERROR",
"statusCode": 422,
"driver": "vlan",
"option": "parent",
"error": "Option parent is required for vlan driver"
}

راهنمای حل:

  • گزینه الزامی را اضافه کنید
  • برای VLAN: parent interface مشخص کنید

NetworkInterfaceCreationFailure (500)

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

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

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"name": "my-bridge",
"error": "Error in creating interface: ip link add failed"
}

راهنمای حل:

  • اجازه‌های root را بررسی کنید
  • نام واسط منحصربه‌فرد است؟
  • سیستم فایل /proc و /sys دسترسی دارند؟

AssignIPToInterfaceFailure (500)

پیام: "Failed to assign IP to network interface."

زمان رخ دادن: خطا در اختصاص IP به واسط

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"name": "my-bridge",
"gateway": "192.168.0.1",
"error": "Error in assigning IP: ip addr add failed"
}

راهنمای حل:

  • IP و subnet معتبر هستند؟
  • IP قبلاً در دستگاه استفاده نمی‌شود؟
  • اجازه‌های root را بررسی کنید

BringNetworkInterfaceUpFailure (500)

پیام: "Failed to bring network interface up."

زمان رخ دادن: خطا در فعال‌سازی واسط

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"name": "my-bridge",
"error": "Error in bringing interface UP: ip link set failed"
}

راهنمای حل:

  • واسط قبلی موجود نیست؟
  • اجازه‌های سیستم را بررسی کنید
  • دستگاه مجازی است؟

SetNFTableRulesFailure (500)

پیام: "Failed to set NFTable firewall rules."

زمان رخ دادن: خطا در تنظیم قوانین Firewall

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"name": "my-bridge",
"subnet": "192.168.0.0/24",
"error": "NFTable operation failed: nft add failed"
}

راهنمای حل:

  • NFTable نصب و فعال است؟
  • قوانین قبلی تضارع دارند؟
  • iptables/nftables چک کنید

VLANConfigurationFailure (500)

پیام: "Failed to configure VLAN network."

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

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"name": "my-vlan",
"error": "VLAN configuration failed"
}

راهنمای حل:

  • واسط parent وجود دارد؟
  • VLAN ID معتبر است؟
  • سوئیچ VLAN را پشتیبانی می‌کند؟

CreateNetworkFailure (500)

پیام: "Failed to create network."

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

جزئیات:

{
"type": "NETWORK_ERROR",
"statusCode": 500,
"name": "my-bridge",
"driver": "bridge",
"error": "Generic network creation error"
}

راهنمای حل:

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

ApplyNetworkCreate (500)

پیام: "Failed to save network record in database."

زمان رخ دادن: خطا در ثبت اطلاعات شبکه در DB

جزئیات:

{
"type": "DB_ERROR",
"statusCode": 500,
"name": "my-bridge",
"error": "Database write failed"
}

راهنمای حل:

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

GenericFailure (500)

پیام: "Generic failure during network creation."

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

جزئیات:

{
"type": "GENERIC_ERROR",
"statusCode": 500,
"error": "Unknown error occurred"
}

راهنمای حل:

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

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

مثال 1: ایجاد شبکه Bridge ساده

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

(async () => {
const k3 = new K3Core();

try {
const result = await k3.networkCore.createNetwork({
name: 'my-bridge',
driver: 'bridge'
// subnet و gateway خودکار تخصیص می‌شود
});

console.log('Success:', result);
// Output:
// {
// id: 'a279434eea2bb32a',
// name: 'my-bridge',
// driver: 'bridge',
// networkIF_name: 'kb-a279434eea2b',
// IPAM: { configs: { subnet: '192.168.0.0/24', gateway: '192.168.0.1' } }
// }
} catch (error) {
console.log('ERROR:', error.message);
}
})();

مثال 2: ایجاد شبکه با Subnet مشخص

(async () => {
const k3 = new K3Core();

try {
const result = await k3.networkCore.createNetwork({
name: 'custom-net',
driver: 'bridge',
subnet: '10.0.0.0/24',
gateway: '10.0.0.1'
});

console.log('Network created:');
console.log(` Name: ${result.name}`);
console.log(` Subnet: ${result.IPAM.configs.subnet}`);
console.log(` Gateway: ${result.IPAM.configs.gateway}`);
} catch (error) {
console.log('ERROR:', error.message);
}
})();

مثال 3: ایجاد شبکه Host

(async () => {
const k3 = new K3Core();

try {
const result = await k3.networkCore.createNetwork({
name: 'host-net',
driver: 'host'
// برای host driver نیازی به subnet نیست
});

console.log('Host network created:');
console.log(` Driver: ${result.driver}`);
console.log(` Gateway: ${result.IPAM.configs.gateway}`); // null
} catch (error) {
console.log('ERROR:', error.message);
}
})();

مثال 4: ایجاد شبکه VLAN

(async () => {
const k3 = new K3Core();

try {
const result = await k3.networkCore.createNetwork({
name: 'vlan-net',
driver: 'vlan',
options: {
'parent': 'eth0',
'com.docker.network.driver.mtu': 1500,
'vlan_id': '100'
},
subnet: '172.16.0.0/24',
gateway: '172.16.0.1'
});

console.log('VLAN network created:');
console.log(` Name: ${result.name}`);
console.log(` Interface: ${result.networkIF_name}`);
} catch (error) {
if (error.statusCode === 422) {
console.log('ERROR: گزینه‌های نامعتبر');
} else {
console.log('ERROR:', error.message);
}
}
})();

مثال 5: ایجاد شبکه با مدیریت خطا

(async () => {
const k3 = new K3Core();

const createNetworkSafely = async (config) => {
try {
// Step 1: Validate name
if (!config.name || config.name.length === 0) {
throw new Error('نام شبکه الزامی است');
}

// Step 2: Check if network exists
const networks = await k3.networkCore.listNetworks();
const exists = networks.find(n => n.name === config.name);

if (exists) {
return { success: false, error: 'شبکه قبلاً موجود است' };
}

// Step 3: Create network
const result = await k3.networkCore.createNetwork(config);
return { success: true, network: result };
} catch (error) {
if (error.statusCode === 409) {
return { success: false, error: 'شبکه قبلاً موجود است' };
} else if (error.statusCode === 422) {
return { success: false, error: 'پارامترهای نامعتبر' };
} else if (error.statusCode === 500) {
return { success: false, error: 'خطای سیستم' };
}
return { success: false, error: error.message };
}
};

const result = await createNetworkSafely({
name: 'app-net',
driver: 'bridge'
});

console.log(result);
})();

مثال 6: ایجاد چند شبکه

(async () => {
const k3 = new K3Core();

const networksConfig = [
{ name: 'frontend-net', driver: 'bridge', subnet: '192.168.1.0/24' },
{ name: 'backend-net', driver: 'bridge', subnet: '192.168.2.0/24' },
{ name: 'db-net', driver: 'bridge', subnet: '192.168.3.0/24' }
];

const results = [];

for (const config of networksConfig) {
try {
const network = await k3.networkCore.createNetwork(config);
results.push({
name: config.name,
status: 'success',
subnet: network.IPAM.configs.subnet
});
console.log(`${config.name} created`);
} catch (error) {
results.push({
name: config.name,
status: 'failed',
error: error.message
});
console.log(`✗ Failed to create ${config.name}`);
}
}

console.log('\n=== Network Creation Summary ===');
console.table(results);
})();

مثال 7: ایجاد شبکه و اتصال کانتینر

(async () => {
const k3 = new K3Core();

try {
// Step 1: Create network
console.log('Step 1: Creating network...');
const network = await k3.networkCore.createNetwork({
name: 'app-network',
driver: 'bridge',
subnet: '172.20.0.0/24'
});
console.log(`✓ Network created: ${network.name}`);

// Step 2: Create containers
console.log('Step 2: Creating containers...');
const container1 = await k3.containerCore.createContainer({
containerId: 'web-server',
imageName: 'nginx',
imageTag: 'latest',
networkId: network.id
});
console.log(`✓ Container created: web-server`);

const container2 = await k3.containerCore.createContainer({
containerId: 'app-server',
imageName: 'node',
imageTag: 'latest',
networkId: network.id
});
console.log(`✓ Container created: app-server`);

// Step 3: Verify
console.log('Step 3: Verifying network...');
const networkInfo = await k3.networkCore.inspectNetwork({
networkId: network.id
});

console.log(`\n✓ Network setup complete:`);
console.log(` Network: ${network.name}`);
console.log(` Containers connected: ${Object.keys(networkInfo.containers).length}`);
} catch (error) {
console.log('ERROR:', error.message);
}
})();

مثال 8: ایجاد شبکه برای Microservices

(async () => {
const k3 = new K3Core();

try {
const serviceNetworks = {
'api-tier': { subnet: '10.1.0.0/24', services: ['gateway', 'auth', 'users'] },
'app-tier': { subnet: '10.2.0.0/24', services: ['api', 'worker', 'cache'] },
'db-tier': { subnet: '10.3.0.0/24', services: ['postgres', 'redis', 'elasticsearch'] }
};

const networks = {};

for (const [tier, config] of Object.entries(serviceNetworks)) {
console.log(`Creating ${tier} network...`);

networks[tier] = await k3.networkCore.createNetwork({
name: tier,
driver: 'bridge',
subnet: config.subnet,
gateway: config.subnet.replace('0/24', '1')
});

console.log(`${tier} network created`);
console.log(` Subnet: ${networks[tier].IPAM.configs.subnet}`);
}

console.log('\n✓ All tier networks created successfully');
console.log('Available networks:', Object.keys(networks));
} catch (error) {
console.log('ERROR:', error.message);
}
})();

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

الگو 1: شبکه قبلاً موجود است

خطا: NetworkAlreadyExists (409)

راهنمای حل:

const createOrUseNetwork = async (name, driver = 'bridge') => {
try {
const result = await k3.networkCore.createNetwork({ name, driver });
return { created: true, network: result };
} catch (error) {
if (error.statusCode === 409) {
console.log(`شبکه ${name} قبلاً موجود است. استفاده از آن...`);

// Get existing network
const networks = await k3.networkCore.listNetworks();
const existing = networks.find(n => n.name === name);

return { created: false, network: existing };
}
throw error;
}
};

const result = await createOrUseNetwork('my-net');

الگو 2: Subnet تضارع دارد

خطا: SubnetAlreadyInUse (500)

راهنمای حل:

const createNetworkWithRetry = async (baseConfig) => {
let subnet = baseConfig.subnet;
const maxRetries = 5;

for (let i = 0; i < maxRetries; i++) {
try {
const result = await k3.networkCore.createNetwork({
...baseConfig,
subnet: subnet
});
return result;
} catch (error) {
if (error.statusCode === 500 && error.message.includes('Subnet')) {
// Generate new subnet
const octet = 100 + i;
subnet = `192.168.${octet}.0/24`;
console.log(`Retrying with subnet: ${subnet}`);
continue;
}
throw error;
}
}

throw new Error('Failed to create network after retries');
};

await createNetworkWithRetry({
name: 'app-net',
driver: 'bridge',
subnet: '192.168.100.0/24'
});

الگو 3: درایور نامعتبر

خطا: InvalidNetworkDriver (422)

راهنمای حل:

const validDrivers = ['bridge', 'host', 'none', 'vlan', 'macvlan'];

const createNetworkWithValidation = async (config) => {
if (!validDrivers.includes(config.driver)) {
throw new Error(`درایور نامعتبر. درایورهای معتبر: ${validDrivers.join(', ')}`);
}

return await k3.networkCore.createNetwork(config);
};

try {
await createNetworkWithValidation({
name: 'my-net',
driver: 'unknown'
});
} catch (error) {
console.log('ERROR:', error.message);
}

الگو 4: VLAN Configuration

راهنمای حل:

const createVLANNetwork = async (name, parentInterface, vlanId) => {
try {
const result = await k3.networkCore.createNetwork({
name: name,
driver: 'vlan',
options: {
'parent': parentInterface,
'vlan_id': String(vlanId),
'com.docker.network.driver.mtu': 1500
},
subnet: `172.16.${vlanId}.0/24`,
gateway: `172.16.${vlanId}.1`
});

console.log(`✓ VLAN ${vlanId} created on ${parentInterface}`);
return result;
} catch (error) {
if (error.statusCode === 422) {
console.log('ERROR: VLAN options missing');
console.log('Required: parent interface must be specified');
} else {
console.log('ERROR:', error.message);
}
throw error;
}
};

await createVLANNetwork('vlan-100', 'eth0', 100);

الگو 5: Network Setup Workflow

راهنمای حل:

class NetworkOrchestrator {
constructor(k3) {
this.k3 = k3;
this.networks = {};
}

async setupApplicationNetworks() {
try {
// Create base networks
console.log('Setting up application networks...');

this.networks.frontend = await this.k3.networkCore.createNetwork({
name: 'frontend-net',
driver: 'bridge',
subnet: '10.1.0.0/24'
});

this.networks.backend = await this.k3.networkCore.createNetwork({
name: 'backend-net',
driver: 'bridge',
subnet: '10.2.0.0/24'
});

this.networks.database = await this.k3.networkCore.createNetwork({
name: 'database-net',
driver: 'bridge',
subnet: '10.3.0.0/24'
});

console.log('✓ All networks created successfully');
return this.networks;
} catch (error) {
console.log('ERROR:', error.message);
throw error;
}
}

getNetworkId(tier) {
return this.networks[tier]?.id;
}

getNetworkInfo(tier) {
return this.networks[tier];
}
}

const orchestrator = new NetworkOrchestrator(k3);
await orchestrator.setupApplicationNetworks();

نکات عملی

  1. نام شبکه:

    • منحصربه‌فرد باشد
    • فقط حروف، اعداد، '-', '_' مجاز
    • 64 کاراکتر حداکثر
  2. Subnet و Gateway:

    • فرمت CIDR استفاده کنید (192.168.0.0/24)
    • Gateway باید در محدوده subnet باشد
    • خودکار تخصیص می‌شود اگر مشخص نشود
  3. درایور Bridge:

    • درایور پیش‌فرض
    • کانتینرها می‌توانند با هم ارتباط برقرار کنند
    • سریعترین برای ارتباط کانتینرها
  4. درایور Host:

    • کانتینر از شبکه میزبان استفاده می‌کند
    • Subnet و gateway 'null' است
    • بهتر performance
  5. درایور VLAN:

    • نیاز به واسط parent دارد
    • برای تقسیم‌بندی شبکه‌های enterprise
    • تنظیمات پیچیده‌تر
  6. Performance:

    • Bridge driver سریعتر
    • Host driver بهترین برای معیار
    • NFTable rules سرعت را کاهش می‌دهد
  7. Best Practices:

    • برای هر tier شبکه جداگانه بسازید
    • Subnet range کافی انتخاب کنید
    • نام‌های معنادار استفاده کنید

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

  1. اعتبارسنجی پارامترهای configs
  2. بررسی عدم وجود شبکه با این نام
  3. تنظیم IPAM (gateway و subnet)
  4. ایجاد واسط شبکه (NetworkManager)
  5. تعیین قوانین Firewall (NFTable)
  6. ثبت اطلاعات در دیتابیس
  7. Logging عملیات
  8. بازگشت اطلاعات شبکه

مرجع سریع

وضعیتکدتوضیح
موفق200شبکه ایجاد شد
پارامتر نامعتبر422InvalidNetworkConfiguration
درایور نامعتبر422InvalidNetworkDriver
گزینه نامعتبر422InvalidNetworkOption
گزینه الزامی422MissingRequiredNetworkOption
شبکه موجود409NetworkAlreadyExists
خطای DB500CheckNetworkExistenceFailure
Subnet استفاده شده500SubnetAlreadyInUse
Subnet کافی نیست500NoAvailableSubnet
IPAM خطا500SetNetworkIPAMFailure
واسط خطا500NetworkInterfaceCreationFailure
IP assignment خطا500AssignIPToInterfaceFailure
Interface up خطا500BringNetworkInterfaceUpFailure
NFTable خطا500SetNFTableRulesFailure
VLAN خطا500VLANConfigurationFailure
عمومی خطا500CreateNetworkFailure
DB save خطا500ApplyNetworkCreate

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

Application Network

const network = await createNetwork({
name: 'app-net',
driver: 'bridge'
});

Microservices Setup

const frontend = await createNetwork({ name: 'frontend', driver: 'bridge', subnet: '10.1.0.0/24' });
const backend = await createNetwork({ name: 'backend', driver: 'bridge', subnet: '10.2.0.0/24' });

VLAN Segmentation

const vlan100 = await createNetwork({
name: 'vlan-100',
driver: 'vlan',
options: { parent: 'eth0', vlan_id: '100' }
});

Host Network (Best Performance)

const hostNet = await createNetwork({
name: 'host-performance',
driver: 'host'
});


نسخه: 1.0
تاریخ آپدیت: 1 دسامبر 2025
تیم توسعه: K3 Development Team