01-NetBox部署实战：在 Ubuntu 上完成 v4.4.7 安装与基础配置
- 这篇文章是整个 NetBox实战 系列的起点，覆盖 Ubuntu 环境下从依赖安装到 Web 服务启动的完整落地过程。 - 重点说明 NetBox 为什么适合作为基础设施 Source of Truth，以及 PostgreSQL、Gunicorn、Nginx 这几段最容易出错的部署。
摘要
- 这篇文章是整个
NetBox实战系列的起点，覆盖 Ubuntu 环境下从依赖安装到 Web 服务启动的完整落地过程。 - 重点说明 NetBox 为什么适合作为基础设施 Source of Truth，以及 PostgreSQL、Gunicorn、Nginx 这几段最容易出错的部署环节。
- 如果你后面还要继续做 Orb、Diode、IP 审计和资产建模，这篇建议先读完再往下走。
一、背景与选型分析：告别 Excel 时代
1.1 现状痛点：IP 地址管理混乱
在许多企业中，IT 基础设施管理（如 IP 地址分配、设备位置、线缆连接等）仍然依赖 Excel、Wiki 或手工记录，主要问题包括：
- 数据分散且不准确：缺乏统一管理，版本混乱
- 缺乏拓扑关联：无法直观查看设备、机架、接口关系
- 无法集成自动化：无法提供结构化 API 数据
- IP 冲突风险高：缺乏校验机制，易重复分配
1.2 NetBox 的角色与优势
NetBox 定位为：
基础设施的真实之源（Source of Truth）
用于建模网络“预期状态”，而非依赖设备发现。
NetBox vs PHP-IPAM 对比
| 特性 | NetBox | PHP-IPAM | 优势 |
|---|---|---|---|
| 核心定位 | DCIM + IPAM | 纯 IPAM | NetBox 支持完整网络建模 |
| 数据模型 | 强约束（设备/接口/机架） | 灵活但松散 | NetBox 避免 IP 浮空 |
| 自动化 | 强 REST API | 基础 API | NetBox 更适合自动化 |
| 线缆管理 | 支持 | 不支持 | NetBox 可追踪物理连接 |
| 技术栈 | Python / PostgreSQL | PHP / MySQL | 均成熟 |
结论
NetBox 不仅是 IP 管理工具，更是：
网络基础设施数据建模平台 + 自动化驱动核心
二、第一阶段：环境准备
部署流水线
sudo apt update && sudo apt upgrade -y
sudo apt install -y postgresql postgresql-contrib redis-server git \
python3 python3-pip python3-venv python3-dev build-essential \
libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev unzip
三、第二阶段：配置 PostgreSQL
3.1 进入数据库
sudo -u postgres psql
若出现
could not change directory可忽略
3.2 创建数据库与用户
CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD 'admin';
GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;
\q
四、第三阶段：获取代码与基础配置
4.1 获取 NetBox
方法一（推荐）
sudo git clone -b master https://github.com/netbox-community/netbox.git /opt/netbox
方法二（备用）
cd /tmp
sudo unzip netbox-master.zip
sudo mv /tmp/netbox-netbox-main /opt/netbox
4.2 创建用户与权限
sudo adduser --system --group netbox
sudo chown -R netbox:netbox /opt/netbox
4.3 配置主文件
基础配置
cd /opt/netbox/netbox/netbox/
sudo cp configuration_example.py configuration.py
sudo /opt/netbox/netbox/generate_secret_key.py
编辑配置：
sudo nano configuration.py
关键配置：
SECRET_KEY：填入生成值DATABASE：填写数据库信息ALLOWED_HOSTS：建议['*']或服务器 IP
五、第四阶段：初始化与管理员
5.1 执行安装
sudo /opt/netbox/upgrade.sh
成功标志：
Upgrade complete!
5.2 创建管理员
cd /opt/netbox/netbox/
source ../venv/bin/activate
python3 manage.py createsuperuser
六、第五阶段：配置服务（Gunicorn）
6.1 复制服务文件
sudo cp /opt/netbox/contrib/*.service /etc/systemd/system/
6.2 修改服务文件
sudo nano /etc/systemd/system/netbox.service
修改为：
ExecStart=/opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox netbox.wsgi
6.3 启动服务
sudo systemctl daemon-reload
sudo systemctl start netbox netbox-rq
sudo systemctl enable netbox netbox-rq
检查状态：
sudo systemctl status netbox
七、第六阶段：配置 Nginx
7.1 安装
sudo apt install -y nginx
7.2 配置站点
sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
编辑：
sudo nano /etc/nginx/sites-available/netbox
修改1：端口
proxy_pass http://127.0.0.1:8000;
修改2：禁用 HTTPS
注释以下内容：
- listen 443
- ssl_certificate
- https 重定向
7.3 启用配置
sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/
sudo nginx -t
sudo service nginx restart
八、访问验证
访问：
http://服务器IP
即可登录 NetBox。
九、常见问题与排错
9.1 HTTPS
- 生产环境建议启用 HTTPS
- 推荐使用 Certbot
9.2 502 Bad Gateway
原因：
- Gunicorn 未运行
- 端口不一致
排查：
sudo systemctl status netbox
9.3 登录失败
python3 manage.py createsuperuser
9.4 升级 NetBox
cd /opt/netbox/
sudo git pull
sudo ./upgrade.sh
sudo systemctl restart netbox netbox-rq
十、总结
NetBox 的核心价值在于：
- 统一数据源（Source of Truth）
- 支撑自动化运维
- 构建完整网络拓扑模型
部署完成后，可进一步：
- 对接自动化工具（Ansible / Python）
- 集成监控系统（Zabbix / ELK）
- 构建网络自动化平台