ARTICLE · 1152900

NetBox 部署文档(Ubuntu 22.04)

发布时间：2026-10-10 20:54:11 最近访问：2026-10-10 20:54:11

主机：ggbond-virtual-machine

部署方式：源码安装 + gunicorn + nginx 反向代理

1. 环境信息

组件	版本/路径
操作系统	Ubuntu 22.04 LTS
Python	3.12.15（虚拟环境 /opt/netbox/venv）
NetBox	/opt/netbox/netbox（源码目录）
数据库	PostgreSQL
缓存/队列	Redis
数据库驱动	psycopg 3.3.4 / psycopg-c 3.3.4 / psycopg-pool 3.3.3
Web 服务	gunicorn（监听 127.0.0.1:8001）
反向代理	nginx（监听 8080）
应用服务	netbox.service（systemd）

端口规划

端口	服务	说明
80	apache2（保留）	原有服务，未卸载仅共存
8080	nginx → NetBox	对外访问入口
8001	gunicorn	内部 WSGI，不对公网暴露

2. 部署步骤

2.1 系统依赖

sudo apt update
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 postgresql redis nginx

2.2 数据库准备（PostgreSQL）

sudo -u postgres psql

CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD '强密码';
GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;
\c netbox
GRANT ALL ON SCHEMA public TO netbox;   -- PG 15+ 必需
\q

2.3 下载源码与虚拟环境

sudo mkdir -p /opt/netbox/
cd /opt/netbox
sudo git clone -b master --depth 1 https://github.com/netbox-community/netbox.git
sudo cp netbox/netbox/configuration.example.py netbox/netbox/configuration.py
sudo python3 -m venv /opt/netbox/venv

2.4 安装 Python 依赖

source /opt/netbox/venv/bin/activate
pip install -r /opt/netbox/requirements.txt

注意：psycopg-c 需本地编译 C 扩展，耗时较长且必须有 build-essential、libpq-dev。若编译失败可先装 psycopg[binary]，但 C 版性能更优。

2.5 核心配置文件

编辑 /opt/netbox/netbox/netbox/configuration.py：

ALLOWED_HOSTS = ['192.168.1.100', 'localhost']       # 实际IP，不带端口

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'netbox',
        'USER': 'netbox',
        '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 = '生成的50位随机串'
# 生成方法: python3 -c "import secrets; print(secrets.token_urlsafe(50))"

CSRF_TRUSTED_ORIGINS = ['http://192.168.1.100:8080']
# 非标准端口必须配置，带协议带端口，否则登录报 403

2.6 初始化与升级

sudo PYTHON=/usr/bin/python3.12 /opt/netbox/upgrade.sh

该脚本自动完成：虚拟环境依赖安装、数据库迁移 migrate、静态文件收集 collectstatic。

2.7 创建超级用户

source /opt/netbox/venv/bin/activate
python3 /opt/netbox/netbox/manage.py createsuperuser
deactivate

2.8 systemd 服务

sudo cp /opt/netbox/contrib/gunicorn.service /etc/systemd/system/netbox.service
sudo cp /opt/netbox/contrib/netbox-housekeeping.service /etc/systemd/system/
sudo cp /opt/netbox/contrib/netbox-housekeeping.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now netbox netbox-housekeeping.timer

2.9 nginx 反向代理（8080 端口）

sudo tee /etc/nginx/sites-available/netbox > /dev/null <<'EOF'
server {
    listen 8080;
    server_name 192.168.1.100;      # 改为实际IP

    client_max_body_size 25m;

    location /static/ {
        alias /opt/netbox/netbox/static/;
    }

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header X-Forwarded-Host $server_name;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300;
    }
}
EOF

sudo ln -sf /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl restart nginx

3. 踩坑记录（本次部署实际问题）

坑 1：HTTPS 证书缺失导致 nginx 无法启动

现象：nginx -t 报 cannot load certificate “/etc/ssl/certs/netbox.crt”: No such file or directory
原因：官方模板 contrib/nginx.conf 默认含 443 HTTPS 段，引用未生成的证书

解决：改用纯 HTTP 配置（本文 2.9 节），或自签证书：

sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/ssl/private/netbox.key -out /etc/ssl/certs/netbox.crt \
  -subj "/CN=192.168.1.100"

坑 2：80 端口被 apache2 占用

现象：nginx -t 语法通过，但 systemctl restart nginx 失败
日志：bind() to 0.0.0.0:80 failed (98: Address already in use)
关键区别：nginx -t 只查语法和文件引用，不检测端口占用
定位：sudo ss -tlnp | grep ':80 ’ → 显示 7 个 apache2 进程
解决：保留 apache2 共存，nginx 改监听 8080

坑 3：sed 修改 listen 未生效

现象：已执行 sed -i ‘s/listen 80;/listen 8080;/’，重启仍报绑 80 失败
原因：模板实际写的是 listen 80 default_server;（80 后非分号），sed 模式未匹配
解决：直接 tee 重写整个配置文件（本文 2.9 节），不依赖 sed 替换
教训：修改后务必复核 grep -rn “listen” /etc/nginx/sites-enabled/ /etc/nginx/conf.d/

坑 4：Ubuntu 与 CentOS 的 nginx 配置路径差异

教程写 /etc/nginx/conf.d/netbox.conf（CentOS 风格）
Ubuntu 正确位置：/etc/nginx/sites-available/ + 软链到 sites-enabled/
若按教程建过 conf.d 文件，注意删除避免双份配置同时加载

坑 5：非标准端口的 CSRF 403

现象：登录页能打开，提交登录时报 403 CSRF verification failed
原因：Django 4.0+ 校验 Origin 头需含端口，非 80/443 端口必须显式声明
解决：configuration.py 中 CSRF_TRUSTED_ORIGINS = [‘http://192.168.1.100:8080’]
注意：修改后需 sudo systemctl restart netbox（重启的是 netbox 不是 nginx）

4. 部署验证清单

# ① 配置自检
/opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py check    # 无 issues
/opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py migrate  # No migrations to apply

# ② 服务状态
systemctl status netbox    # active (running)
systemctl status nginx     # active (running)

# ③ 端口监听
ss -tlnp | grep -E ':80 |:8080 |:8001 '
# 80=apache2  8080=nginx  8001=gunicorn

# ④ HTTP 响应
curl -I http://127.0.0.1:8080/    # 200/302

# ⑤ 浏览器访问 http://<IP>:8080/ 登录验证

5. 故障排查速查表

现象	排查命令	常见原因
nginx restart 失败	journalctl -u nginx 过滤 emerg/bind	端口占用 / 残留 listen 80
页面 502	systemctl status netbox	gunicorn 未运行 / 端口不符
样式丢失、static 404	ls /opt/netbox/netbox/static/	未跑 collectstatic / alias 路径错
登录 403 CSRF	检查 CSRF_TRUSTED_ORIGINS	缺端口或未重启 netbox
Invalid HTTP_HOST	检查 ALLOWED_HOSTS	未加访问用的 IP
上传报 413	检查 nginx 配置	缺 client_max_body_size
psycopg 编译失败	apt install build-essential libpq-dev	缺编译工具链

6. 运维要点

# 日常升级
cd /opt/netbox && sudo git pull
sudo PYTHON=/usr/bin/python3.12 /opt/netbox/upgrade.sh
sudo systemctl restart netbox

# 数据备份
sudo -u postgres pg_dump netbox > netbox_$(date +%F).sql
sudo tar czf media_$(date +%F).tar.gz /opt/netbox/netbox/media/

# 日志查看
journalctl -u netbox -f
sudo tail -f /var/log/nginx/error.log

后续切 HTTPS：certbot 签发或自签证书后，nginx 增加 443 段
apache2 若确认废弃：sudo apt purge apache2 -y 后可将 nginx 改回 80 端口（同步更新 CSRF_TRUSTED_ORIGINS 为不带端口的地址）