مقدمه

NetBox یک پلتفرم متن‌باز برای مدل‌سازی و مستندسازی زیرساخت شبکه است که نقش Source of Truth را برای IPAM، DCIM، Rack، Device، Cable، VLAN، Prefix، Virtualization و سایر منابع زیرساختی ایفا می‌کند. این راهنما نصب Production-ready نسخه 4.7.x روی Ubuntu 24.04 را از صفر تا API و Import کتابخانه تجهیزات پوشش می‌دهد.

در زمان تهیه این راهنما آخرین نسخه پایدار NetBox، نسخه 4.7.1 منتشرشده در 15 سپتامبر 2026 است. برای محیط Production بهتر است همیشه آخرین Patch همان شاخه پایدار را نصب کنید و قبل از Upgrade یادداشت‌های Release را بررسی کنید.

فهرست مطالب

معماری NetBox

NetBox یک برنامه Django/Python است که در Production معمولاً پشت Gunicorn و Nginx اجرا می‌شود. PostgreSQL دیتابیس اصلی است و Redis برای Cache و صف Background Jobها استفاده می‌شود. سرویس netbox-rq پردازش Jobهای پس‌زمینه را انجام می‌دهد.

  • Nginx: Reverse Proxy، TLS و ارائه Static Files
  • Gunicorn: اجرای WSGI Application
  • NetBox/Django: منطق اصلی برنامه
  • PostgreSQL 15+: پایگاه داده اصلی
  • Redis 6+: Cache و Queue
  • netbox-rq: Worker پردازش Background Jobs

چه سروری برای NetBox نیاز داریم؟

مستندات رسمی NetBox حداقل CPU/RAM مشخصی تعیین نمی‌کنند و ظرفیت مناسب به تعداد کاربران، Deviceها، Pluginها و حجم Automation بستگی دارد. جدول زیر یک پیشنهاد عملی برای شروع است، نه الزام رسمی NetBox.

EnvironmentvCPURAMDiskUse
Lab / Test24 GB30 GB SSDآزمایش و آموزش
Small Production48 GB60 GB SSDچند هزار Object و کاربران محدود
Medium Production816 GB100+ GB SSDAutomation، Plugin و API پرترافیک
  • برای Production از SSD استفاده کنید و PostgreSQL را روی Storage پایدار قرار دهید.
  • در محیط‌های بزرگ می‌توانید PostgreSQL و Redis را روی سرورهای جداگانه اجرا کنید.
  • پورت‌های عمومی موردنیاز معمولاً 80/443 هستند؛ PostgreSQL و Redis را عمومی نکنید.

پیش‌نیازهای رسمی

  • Ubuntu Server 24.04 LTS؛ مستندات نصب رسمی NetBox روی این نسخه تست شده‌اند.
  • Python 3.12، 3.13 یا 3.14
  • PostgreSQL 15 یا بالاتر؛ MySQL پشتیبانی نمی‌شود.
  • Redis 6.0 یا بالاتر
  • کاربر دارای sudo، اینترنت، DNS/FQDN و ترجیحاً SSL معتبر
Ubuntu Terminal
sudo apt update && sudo apt upgrade -y
sudo timedatectl set-timezone Asia/Tehran
hostnamectl
ip a

اگر سرور شما در منطقه زمانی دیگری قرار دارد، مقدار timezone را متناسب با محیط خود تغییر دهید.

نصب و راه‌اندازی PostgreSQL

Ubuntu Terminal
sudo apt update
sudo apt install -y postgresql
psql -V
systemctl status postgresql --no-pager

NetBox 4.7 به PostgreSQL 15 یا بالاتر نیاز دارد. سپس Database و User اختصاصی بسازید. رمز مثال زیر را حتماً تغییر دهید.

PostgreSQL
sudo -u postgres psql

CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD 'CHANGE_THIS_STRONG_PASSWORD';
ALTER DATABASE netbox OWNER TO netbox;
\connect netbox;
GRANT CREATE ON SCHEMA public TO netbox;
\q

اتصال دیتابیس را قبل از ادامه تست کنید:

Ubuntu Terminal
psql --username netbox --password --host localhost netbox
# سپس در psql:
\conninfo
\q

نصب و راه‌اندازی Redis

Ubuntu Terminal
sudo apt install -y redis-server
redis-server -v
redis-cli ping
systemctl status redis-server --no-pager

خروجی redis-cli ping باید PONG باشد. Redis را روی localhost یا شبکه Trusted نگه دارید؛ Workerهای NetBox Jobها را از Redis دریافت می‌کنند و دسترسی Write غیرمجاز به Redis یک ریسک امنیتی جدی است.

نصب NetBox روی Ubuntu 24.04

برای Production از روش Release Archive یا Git استفاده کنید. نصب NetBox از Python package در شاخه 4.7 هنوز Experimental است. در این راهنما روش Git استفاده می‌شود تا Upgradeها ساده‌تر باشند.

Ubuntu Terminal
sudo apt install -y python3 python3-pip python3-venv python3-dev \
  build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev \
  libssl-dev zlib1g-dev git
python3 -V

Repository رسمی را Clone کرده و نسخه پایدار را Checkout کنید. در تاریخ این راهنما آخرین Patch، نسخه v4.7.1 است.

Ubuntu Terminal
sudo mkdir -p /opt/netbox
cd /opt/netbox
sudo git clone https://github.com/netbox-community/netbox.git .
sudo git checkout v4.7.1

سپس Service Account مخصوص NetBox را بسازید و مالکیت مسیرهای قابل نوشتن را تنظیم کنید.

Ubuntu Terminal
sudo adduser --system --group netbox
sudo chown --recursive netbox /opt/netbox/netbox/media/
sudo chown --recursive netbox /opt/netbox/netbox/reports/
sudo chown --recursive netbox /opt/netbox/netbox/scripts/

پیکربندی اصلی NetBox

Ubuntu Terminal
cd /opt/netbox/netbox/netbox
sudo cp configuration_example.py configuration.py
sudo nano configuration.py

در NetBox 4.7 پنج پارامتر اصلی برای نصب جدید ضروری هستند: ALLOWED_HOSTS، API_TOKEN_PEPPERS، DATABASES، REDIS و SECRET_KEY.

Generate Secrets
cd /opt/netbox/netbox
python3 generate_secret_key.py
python3 generate_secret_key.py

دو مقدار مستقل بسازید: یکی برای SECRET_KEY و دیگری برای API_TOKEN_PEPPERS. مقادیر زیر Placeholder هستند.

configuration.py
ALLOWED_HOSTS = ['netbox.example.com', '10.10.10.20']

API_TOKEN_PEPPERS = {
    1: 'PUT_A_RANDOM_50_PLUS_CHARACTER_VALUE_HERE',
}

DATABASES = {
    'default': {
        'NAME': 'netbox',
        'USER': 'netbox',
        'PASSWORD': 'CHANGE_THIS_STRONG_PASSWORD',
        'HOST': 'localhost',
        'PORT': '',
        'CONN_MAX_AGE': 300,
    }
}

REDIS = {
    'tasks': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 0,
        'SSL': False,
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,
        'SSL': False,
    }
}

SECRET_KEY = 'PUT_ANOTHER_RANDOM_50_PLUS_CHARACTER_VALUE_HERE'

حالا اسکریپت نصب/Upgrade را اجرا کنید؛ این اسکریپت Virtual Environment، Python dependencies، Migrationها، Documentation و Static Files را آماده می‌کند.

Ubuntu Terminal
sudo /opt/netbox/upgrade.sh

در پایان Superuser بسازید:

Ubuntu Terminal
source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox
python3 manage.py createsuperuser

راه‌اندازی Gunicorn و سرویس‌های systemd

Ubuntu Terminal
sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now netbox netbox-rq

سرویس netbox مربوط به Gunicorn و سرویس netbox-rq مربوط به Background Worker است. هر دو باید Active باشند.

Ubuntu Terminal
systemctl status netbox --no-pager
systemctl status netbox-rq --no-pager
ss -lntp | grep 8001

راه‌اندازی Nginx و HTTPS

Ubuntu Terminal
sudo apt install -y nginx
sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
sudo nano /etc/nginx/sites-available/netbox

در فایل Nginx مقدار netbox.example.com را با FQDN یا IP خود جایگزین کنید. مقدار باید با ALLOWED_HOSTS هماهنگ باشد. فایل نمونه NetBox به‌طور پیش‌فرض Gunicorn را روی پورت 8001 Reverse Proxy می‌کند.

Ubuntu Terminal
sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
sudo nginx -t
sudo systemctl restart nginx
sudo systemctl enable nginx

برای Production از Certificate معتبر استفاده کنید. اگر DNS عمومی دارید می‌توانید Let’s Encrypt/Certbot را به‌کار ببرید؛ در شبکه داخلی می‌توانید Certificate سازمانی نصب کنید.

Ubuntu Terminal
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d netbox.example.com
sudo certbot renew --dry-run

تست نهایی و بالا آمدن NetBox

Ubuntu Terminal
curl -I http://127.0.0.1
curl -kI https://netbox.example.com
systemctl is-active postgresql redis-server netbox netbox-rq nginx

برای عیب‌یابی سریع وضعیت و Logها را بررسی کنید:

Ubuntu Terminal
journalctl -eu netbox --no-pager -n 100
journalctl -eu netbox-rq --no-pager -n 100
tail -n 100 /var/log/nginx/error.log
  • HTTP 502 معمولاً یعنی Nginx به Gunicorn روی 8001 دسترسی ندارد یا سرویس netbox Down است.
  • HTTP 400 Bad Request معمولاً ALLOWED_HOSTS اشتباه است.
  • خطاهای DB را با psql و journalctl بررسی کنید.

راه‌اندازی و تست REST API

تمام REST APIهای NetBox زیر مسیر /api/ قرار دارند و مستندات تعاملی Swagger روی /api/schema/swagger-ui/ در دسترس است. برای Automation از API Token استفاده کنید. در NetBox 4.5 به بعد توکن‌های v2 توصیه می‌شوند و v1 در 4.6 Deprecated شده است.

  • از UI وارد Profile → API Tokens شوید.
  • توکن Write-enabled را فقط برای Import/Automation نیازمند تغییر بسازید.
  • در صورت امکان Allowed IPs را به IP سرور Automation محدود کنید.
  • Token plaintext را همان لحظه امن ذخیره کنید؛ بعداً قابل بازیابی نیست.
Ubuntu Terminal
export NETBOX_URL='https://netbox.example.com'
export NETBOX_TOKEN='nbt_xxxxx.xxxxxxxxxxxxxxxxx'

curl -s \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Accept: application/json; indent=2" \
  "$NETBOX_URL/api/dcim/sites/"

برای ساخت یک Site آزمایشی از API:

Ubuntu Terminal
curl -s -X POST \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  "$NETBOX_URL/api/dcim/sites/" \
  --data '{"name":"HQ","slug":"hq","status":"active"}'

Import کردن Device Type Library با API

NetBox Community Device Type Library مجموعه بزرگی از تعریف‌های YAML برای Manufacturer، Device Type، Module Type، Interface Template، Power Port و سایر Componentهاست. برای Import خودکار می‌توان از پروژه Community به نام Device-Type-Library-Import استفاده کرد که به API NetBox متصل می‌شود، Duplicateها را بررسی می‌کند و امکان Import انتخابی Vendorها را دارد.

بهتر است Import Tool را داخل Virtual Environment جداگانه اجرا کنید و آن را داخل venv اصلی NetBox نصب نکنید.

Ubuntu Terminal
sudo mkdir -p /opt/netbox-tools
sudo chown $USER:$USER /opt/netbox-tools
cd /opt/netbox-tools
git clone https://github.com/netbox-community/Device-Type-Library-Import.git
cd Device-Type-Library-Import
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

فایل Environment را بسازید و URL و Token دارای Write Permission را وارد کنید:

.env
cp .env.example .env
nano .env

# نمونه:
NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=nbt_xxxxx.xxxxxxxxxxxxxxxxx

اول فقط Vendorهای موردنیاز را Import کنید. این کار هم زمان اجرا و هم حجم داده را کاهش می‌دهد.

Ubuntu Terminal
./nb-dt-import.py --vendors cisco,hpe,mikrotik,ubiquiti

برای Import همه Vendorها می‌توانید ابزار را بدون --vendors اجرا کنید، ولی در Production بهتر است ابتدا روی Test/Staging بررسی شود. Repository کتابخانه هنگام اجرا Clone یا Pull می‌شود.

Ubuntu Terminal
./nb-dt-import.py

برای تست API قبل از Import و مشاهده Manufacturerها:

Ubuntu Terminal
curl -s \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  "$NETBOX_URL/api/dcim/manufacturers/?limit=5"
  • خطای 401/403: Token، Permission و Allowed IPs را بررسی کنید.
  • خطای SSL: Certificate chain را اصلاح کنید؛ غیرفعال‌کردن Verify فقط برای تست توصیه می‌شود.
  • قبل از Import انبوه از دیتابیس Backup بگیرید.
  • Device Typeهای Community را قبل از استفاده عملی با مدل واقعی سخت‌افزار Verify کنید.

Backup، Upgrade و نگهداری

مهم‌ترین بخش Backup، دیتابیس PostgreSQL است. علاوه بر آن configuration.py، media و در صورت استفاده scripts/reports سفارشی را نگه دارید.

Ubuntu Terminal
sudo -u postgres pg_dump -Fc netbox > /var/backups/netbox-$(date +%F).dump
sudo cp /opt/netbox/netbox/netbox/configuration.py /var/backups/configuration.py
sudo tar -czf /var/backups/netbox-media-$(date +%F).tar.gz /opt/netbox/netbox/media

برای Upgrade در نصب Git، ابتدا Release Notes و سازگاری Pluginها را بررسی کنید، Backup بگیرید و سپس Tag جدید را Checkout کنید.

Ubuntu Terminal
cd /opt/netbox
sudo git fetch --tags
sudo git checkout v4.7.1
sudo /opt/netbox/upgrade.sh
sudo systemctl restart netbox netbox-rq
systemctl status netbox netbox-rq --no-pager

چک‌لیست امنیت Production

  • NetBox، PostgreSQL و Redis را با آخرین Patchهای امنیتی نگه دارید.
  • PostgreSQL 5432 و Redis 6379 را Public نکنید.
  • از HTTPS معتبر استفاده کنید و HTTP را Redirect کنید.
  • برای API از Token v2 با حداقل Permission و Allowed IPs استفاده کنید.
  • SECRET_KEY، API_TOKEN_PEPPERS و Database Password را در Repository ذخیره نکنید.
  • Backupها را Encrypt و Restore آن‌ها را دوره‌ای تست کنید.
  • برای کاربران عادی Role/Permission محدود تعریف کنید و Superuser را برای کار روزمره استفاده نکنید.

عیب‌یابی رایج

خطابررسیراه‌حل معمول
502 Bad Gatewaysystemctl status netboxGunicorn/port 8001 و Nginx proxy_pass را بررسی کنید.
400 Bad RequestALLOWED_HOSTSFQDN/IP صحیح را در configuration.py قرار دهید.
DB connection failedpsql -h localhost -U netbox netboxUser/Password/HOST و PostgreSQL service را بررسی کنید.
Redis errorredis-cli pingRedis service و تنظیم Database IDهای 0 و 1 را بررسی کنید.
API 403Token permissionWrite enabled، User permissions و Allowed IPs را بررسی کنید.
Static/CSS مشکل داردsudo /opt/netbox/upgrade.shcollectstatic و Nginx static path را بررسی کنید.
Ubuntu Terminal
sudo nginx -t
sudo systemctl restart netbox netbox-rq nginx
journalctl -eu netbox -n 150 --no-pager
journalctl -eu netbox-rq -n 150 --no-pager
tail -f /var/log/nginx/error.log

نتیجه‌گیری

با این معماری، NetBox روی Ubuntu 24.04 با PostgreSQL، Redis، Gunicorn و Nginx به‌صورت Production-ready اجرا می‌شود. پس از بالا آمدن سرویس، REST API و Device Type Library پایه مناسبی برای Automation و مستندسازی استاندارد زیرساخت شبکه ایجاد می‌کنند.

پرسش‌های متداول

NetBox دقیقاً چه کاری انجام می‌دهد؟

NetBox یک Source of Truth برای مدل‌سازی IPAM، DCIM، Rack، Device، Cable، VLAN، Prefix، Circuit، Virtualization و سایر منابع زیرساختی است؛ ابزار Monitoring مستقیم نیست.

آیا NetBox جای Zabbix یا PRTG را می‌گیرد؟

خیر. NetBox وضعیت مطلوب و مستندات زیرساخت را نگه می‌دارد؛ Zabbix/PRTG وضعیت عملیاتی و Metrics را مانیتور می‌کنند. این ابزارها می‌توانند با API به NetBox متصل شوند.

برای NetBox 4.7 چه نسخه‌هایی لازم است؟

Python 3.12 تا 3.14، PostgreSQL 15 یا بالاتر و Redis 6.0 یا بالاتر.

آیا MySQL یا SQL Server پشتیبانی می‌شود؟

خیر. NetBox به PostgreSQL نیاز دارد.

آیا می‌توان PostgreSQL و Redis را روی سرور جدا نصب کرد؟

بله. در محیط‌های بزرگ یا HA این معماری رایج است؛ HOST و Credentialها را در configuration.py تغییر دهید و Firewall را فقط بین Hostهای موردنیاز باز کنید.

آیا پورت 8000 یا 8001 باید از اینترنت باز باشد؟

خیر. در Production فقط Nginx روی 80/443 در دسترس باشد. Gunicorn روی 8001 باید داخلی باشد و runserver روی 8000 فقط برای تست است.

خطای 502 Bad Gateway یعنی چه؟

معمولاً Nginx نمی‌تواند به Gunicorn متصل شود. وضعیت netbox.service، پورت 8001 و proxy_pass را بررسی کنید.

خطای DisallowedHost یا 400 را چطور حل کنم؟

FQDN یا IP مورد استفاده را به ALLOWED_HOSTS اضافه کرده و سرویس NetBox را Restart کنید.

چطور API Token بسازم؟

از Profile → API Tokens یک Token v2 بسازید. مقدار plaintext را همان لحظه ذخیره کنید؛ بعداً قابل بازیابی نیست.

برای Import کتابخانه تجهیزات چه Permission لازم است؟

Token باید Write-enabled باشد و User آن روی Manufacturer، Device Type، Module Type و Componentهای مرتبط Permission ایجاد/تغییر داشته باشد.

آیا Device Type Library رسمی خود NetBox است؟

این Library در NetBox Community نگهداری می‌شود و تعریف‌ها Community-sourced هستند. قبل از استفاده Production مشخصات را با سخت‌افزار واقعی Verify کنید.

بهتر است همه Vendorها را Import کنم؟

معمولاً نه. Import انتخابی Vendorهای موردنیاز Database را تمیزتر نگه می‌دارد و زمان Import را کاهش می‌دهد.

چطور از NetBox Backup بگیرم؟

حداقل PostgreSQL dump، configuration.py و media را Backup کنید. اگر Custom Script/Report دارید آن‌ها را هم نگه دارید و Restore را دوره‌ای تست کنید.

Upgrade NetBox چگونه انجام می‌شود؟

Release Notes و Plugin compatibility را بررسی کنید، Backup بگیرید، Tag جدید را Checkout کنید، upgrade.sh را اجرا کرده و netbox/netbox-rq را Restart کنید.

آیا می‌توان NetBox را بدون Nginx اجرا کرد؟

برای تست می‌توان از runserver استفاده کرد، اما برای Production توصیه رسمی استفاده از یک HTTP Server مثل Nginx یا Apache در جلوی WSGI است.

Swagger API کجاست؟

روی هر Instance مسیر /api/schema/swagger-ui/ مستندات تعاملی OpenAPI را نمایش می‌دهد.

چطور وضعیت همه سرویس‌ها را سریع بررسی کنم؟

از systemctl is-active postgresql redis-server netbox netbox-rq nginx استفاده کنید و برای خطا journalctl -eu netbox را ببینید.

منابع رسمی و مرجع

Share