ایجاد شبکه جدید
شبکه جدیدی را با تنظیمات سفارشی ایجاد کرده و تمام واسطهای شبکه و تنظیمات IP را مدیریت میکند.
🧩 دستور کلی
async createNetwork(configs, options = {})
شرح عملکرد
این متد شبکه جدیدی میسازد و به سیستم اضافه میکند. شامل:
- اعتبارسنجی پارامترهای شبکه (نام، driver، subnet، gateway)
- بررسی عدم وجود شبکه با همین نام
- تخصیص خودکار subnet و gateway در صورت نیاز
- تنظیم IPAM (IP Address Management)
- ایجاد واسط فیزیکی شبکه
- تعیین قوانین Firewall (NFTable)
- ثبت اطلاعات شبکه در دیتابیس
- Logging عملیات
مهم: درایور شبکه (bridge، host، none، vlan و ...) و تنظیمات آن بسیار حائز اهمیت است.
ورودیها
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
configs | Object | بله | پیکربندی شبکه (name, driver, options, subnet, gateway) |
options | Object | خیر | گزینههای خاص (مثل 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();
نکات عملی
-
نام شبکه:
- منحصربهفرد باشد
- فقط حروف، اعداد، '-', '_' مجاز
- 64 کاراکتر حداکثر
-
Subnet و Gateway:
- فرمت CIDR استفاده کنید (192.168.0.0/24)
- Gateway باید در محدوده subnet باشد
- خودکار تخصیص میشود اگر مشخص نشود
-
درایور Bridge:
- درایور پیشفرض
- کانتینرها میتوانند با هم ارتباط برقرار کنند
- سریعترین برای ارتباط کانتینرها
-
درایور Host:
- کانتینر از شبکه میزبان استفاده میکند
- Subnet و gateway 'null' است
- بهتر performance
-
درایور VLAN:
- نیاز به واسط parent دارد
- برای تقسیمبندی شبکههای enterprise
- تنظیمات پیچیدهتر
-
Performance:
- Bridge driver سریعتر
- Host driver بهترین برای معیار
- NFTable rules سرعت را کاهش میدهد
-
Best Practices:
- برای هر tier شبکه جداگانه بسازید
- Subnet range کافی انتخاب کنید
- نامهای معنادار استفاده کنید
دنباله عملیات
- اعتبارسنجی پارامترهای configs
- بررسی عدم وجود شبکه با این نام
- تنظیم IPAM (gateway و subnet)
- ایجاد واسط شبکه (NetworkManager)
- تعیین قوانین Firewall (NFTable)
- ثبت اطلاعات در دیتابیس
- Logging عملیات
- بازگشت اطلاعات شبکه
مرجع سریع
| وضعیت | کد | توضیح |
|---|---|---|
| موفق | 200 | شبکه ایجاد شد |
| پارامتر نامعتبر | 422 | InvalidNetworkConfiguration |
| درایور نامعتبر | 422 | InvalidNetworkDriver |
| گزینه نامعتبر | 422 | InvalidNetworkOption |
| گزینه الزامی | 422 | MissingRequiredNetworkOption |
| شبکه موجود | 409 | NetworkAlreadyExists |
| خطای DB | 500 | CheckNetworkExistenceFailure |
| Subnet استفاده شده | 500 | SubnetAlreadyInUse |
| Subnet کافی نیست | 500 | NoAvailableSubnet |
| IPAM خطا | 500 | SetNetworkIPAMFailure |
| واسط خطا | 500 | NetworkInterfaceCreationFailure |
| IP assignment خطا | 500 | AssignIPToInterfaceFailure |
| Interface up خطا | 500 | BringNetworkInterfaceUpFailure |
| NFTable خطا | 500 | SetNFTableRulesFailure |
| VLAN خطا | 500 | VLANConfigurationFailure |
| عمومی خطا | 500 | CreateNetworkFailure |
| DB save خطا | 500 | ApplyNetworkCreate |
موارد استفاده
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