企业官网建设流程全解析

• 后端
• 网络
• 数据建模

导读

本文基于 NetBox 官方安装文档中的 HTTP 服务器部署章节，系统讲解如何为生产环境中的 NetBox 配置 nginx 或 Apache 反向代理，实现 HTTPS 加密访问、静态文件托管以及与 gunicorn/uWSGI 的对接。完成本文的实操后，你将能够独立签发 SSL 证书、正确部署两种主流通用 HTTP 服务器、定位 502 Bad Gateway 等常见故障，并理解 NetBox 与反向代理之间的请求头约定与安全边界。

NetBox 请求链路中 HTTP 服务器的定位

NetBox 是一个基于 Django 的 WSGI 应用，自身不直接对外提供 HTTP 服务，而是运行在 WSGI 服务器（gunicorn 或 uWSGI）之后，再由一层通用 HTTP 服务器（nginx 或 Apache）作为对外入口。整个应用栈的请求流向如下（见 安装总览）：

客户端 │ HTTPS (443) ▼ nginx / Apache ← 本文部署的对象：HTTP 反向代理、TLS 终结、静态文件服务 │ HTTP (127.0.0.1:8001) ▼ gunicorn / uWSGI ← WSGI HTTP 服务器，默认监听 127.0.0.1:8001 │ ▼ NetBox (Django) ──► PostgreSQL / Redis / rqworker

在这一架构中，nginx 或 Apache 承担三项职责：终结 TLS 加密连接、将动态请求反向代理给本机 WSGI 进程、直接托管/static/静态资源（CSS、JavaScript、图片等，由collectstatic收集到<NETBOX_ROOT>/static，对应源码 settings.py 中的STATIC_ROOT与STATIC_URL）。

以下配置以 Ubuntu 24.04 为例，但步骤本身不依赖特定发行版，迁移到其他发行版时只需将包管理器命令替换为对应平台的命令。部署前请先确认 gunicorn 或 uWSGI 已按 Gunicorn 部署 / uWSGI 部署 安装并运行（systemctl status netbox应显示 active）。

第一步：获取 SSL 证书

要对 NetBox 启用 HTTPS 访问，必须先准备一份 SSL 证书。证书有三种来源：

1. 商业机构购买：从受信任的商业 CA 购买；
2. Let's Encrypt 免费签发：适合大多数公网部署，可自动续期；
3. 自签名证书：仅用于测试环境，浏览器一般会给出不受信任的警告。

无论来源如何，公钥证书与私钥文件都必须安装在 NetBox 服务器上，且路径对netbox用户可读（nginx/Apache 工作进程需要读取它们）。注意区分两者：证书（netbox.crt）对外发布，私钥（netbox.key）必须始终保密。

测试环境可用以下命令生成 365 天有效期的自签名证书：

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout /etc/ssl/private/netbox.key \ -out /etc/ssl/certs/netbox.crt

命令中的参数含义：

执行后命令会交互式询问证书的详细信息（国家、地区、组织等），这些字段全部可选，直接回车跳过即可。生产环境强烈建议使用受信任 CA 签发的证书。

方案 A：使用 nginx

1. 安装 nginx

sudo apt install -y nginx

2. 部署 NetBox 自带的参考配置

NetBox 仓库在 contrib/nginx.conf 提供了一份完整可用的 nginx 配置，将其复制到 nginx 的站点目录：

sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox

然后编辑该文件，将server_name替换为你实际的域名或 IP 地址。该值必须与configuration.py中配置的ALLOWED_HOSTS保持一致（见下文"源码视角"一节）。

gunicorn vs. uWSGI 注意事项：参考配置默认假设使用 gunicorn。如果改用 uWSGI，需要删除以proxy_pass和proxy_set_header开头的 gunicorn 专属配置行，并取消注释下方的 uWSGI 段落（uwsgi_pass 127.0.0.1:8001;等），两种方式监听端口均默认为 8001。

3. 配置逐段详解

仓库中的 contrib/nginx.conf 包含两个server块，完整解读如下：

server { listen [::]:443 ssl ipv6only=off; # 同时监听 IPv4/IPv6 的 443 端口 # CHANGE THIS TO YOUR SERVER'S NAME server_name netbox.example.com; # ← 改为你的域名/IP ssl_certificate /etc/ssl/certs/netbox.crt; # 公钥证书 ssl_certificate_key /etc/ssl/private/netbox.key; # 私钥 client_max_body_size 25m; # 允许的最大请求体 25MB location /static/ { alias /opt/netbox/netbox/static/; # 静态文件由 nginx 直接返回 } location / { # Remove these lines if using uWSGI instead of Gunicorn proxy_pass http://127.0.0.1:8001; # 动态请求转发给 WSGI 进程 proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; # Uncomment these lines if using uWSGI instead of Gunicorn # include uwsgi_params; # uwsgi_pass 127.0.0.1:8001; # uwsgi_param Host $host; # uwsgi_param X-Real-IP $remote_addr; # uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for; # uwsgi_param X-Forwarded-Proto $http_x_forwarded_proto; } } server { # Redirect HTTP traffic to HTTPS listen [::]:80 ipv6only=off; # 80 端口只做跳转 server_name _; return 301 https://$host$request_uri; # 全部 HTTP 请求 301 到 HTTPS }

关键点说明：

• proxy_pass http://127.0.0.1:8001;：与 gunicorn 的监听地址对应。仓库自带的 contrib/gunicorn.py 中bind = '127.0.0.1:8001'，两者必须一致；若修改了 gunicorn 绑定端口，此处也要同步修改。
• client_max_body_size 25m：限制客户端请求体大小。NetBox 允许通过DATA_UPLOAD_MAX_MEMORY_SIZE（默认 2621440 字节，约 2.5MB，见 settings.py）调整 Django 侧上限，nginx 的 25m 为图片上传等场景预留了更大空间，按需调整。
• location /static/的alias：直接由 nginx 提供静态文件，避免把静态请求转发给 gunicorn 消耗 WSGI 资源。
• X-Forwarded-Proto $scheme：把客户端实际使用的协议（http/https）透传给后端，NetBox 依赖它判断请求是否为 HTTPS（见下文SECURE_PROXY_SSL_HEADER）。

4. 启用站点并重启

sudo rm /etc/nginx/sites-enabled/default sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox sudo systemctl restart nginx

第一条命令删除默认站点（其server_name通配会抢占流量），第二条在sites-enabled中建立指向刚创建配置的软链接，第三条加载新配置。

方案 B：使用 Apache

1. 安装 Apache

sudo apt install -y apache2

2. 部署 NetBox 自带的参考配置

仓库在 contrib/apache.conf 提供了完整的 Apache 虚拟主机配置，复制到站点目录并修改ServerName参数：

sudo cp /opt/netbox/contrib/apache.conf /etc/apache2/sites-available/netbox.conf

3. 配置逐段详解

contrib/apache.conf 同样包含两个VirtualHost块：

<VirtualHost *:80> # CHANGE THIS TO YOUR SERVER'S NAME ServerName netbox.example.com RewriteEngine On RewriteCond %{HTTPS} !=on RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L] # HTTP 全部重定向到 HTTPS </VirtualHost> <VirtualHost *:443> ProxyPreserveHost On # 将原始 Host 头传给后端 # CHANGE THIS TO YOUR SERVER'S NAME ServerName netbox.example.com SSLEngine on SSLCertificateFile /etc/ssl/certs/netbox.crt SSLCertificateKeyFile /etc/ssl/private/netbox.key Alias /static /opt/netbox/netbox/static <Directory /opt/netbox/netbox/static> Options FollowSymLinks MultiViews AllowOverride None Require all granted </Directory> <Location /static> ProxyPass ! # /static 不进入反向代理，由 Apache 直接服务 </Location> RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME} ProxyPass / http://127.0.0.1:8001/ ProxyPassReverse / http://127.0.0.1:8001/ </VirtualHost>

关键点说明：

• ProxyPreserveHost On：保留客户端原始Host请求头，确保 NetBox 生成的重定向与绝对 URL 使用正确域名。
• ProxyPass !（配合Alias）：/static/路径由 Apache 直接返回磁盘上的静态文件，其余请求全部经ProxyPass /转发给127.0.0.1:8001的 WSGI 进程。
• RequestHeader set "X-Forwarded-Proto"：与 nginx 配置中X-Forwarded-Proto $scheme作用相同，用于通知 NetBox 客户端使用的是 HTTPS。
• 需要 Apache 启用headers模块（RequestHeader指令依赖它），见下面的模块启用命令。

4. 启用模块与站点并重启

sudo a2enmod ssl proxy proxy_http headers rewrite sudo a2ensite netbox sudo systemctl restart apache2

其中a2enmod一次启用六个模块：ssl（HTTPS 支持）、proxy与proxy_http（反向代理）、headers（RequestHeader指令）、rewrite（HTTP→HTTPS 跳转规则）；a2ensite netbox启用刚复制到sites-available的站点。

确认连通性

完成上述任一方案后，即可通过配置的域名或 IP 访问 HTTPS 服务。可在服务器本地做快速验证：

curl -I https://netbox.example.com

预期返回HTTP/2 200（或301于跳转后最终到达 200）。若返回 301，说明 HTTP→HTTPS 跳转生效，属正常现象。

重要安全警告：NetBox 的部分组件（例如机架立面图 rack elevation diagrams 的展示）依赖嵌入式对象（embed）渲染。务必确保 HTTP 服务器配置没有覆盖 NetBox 设置X-Frame-Options响应头。NetBox 在 settings.py 中显式设置了X_FRAME_OPTIONS = 'SAMEORIGIN'，用于允许同源页面内的 iframe 嵌入，同时抵御点击劫持。若在反向代理层强行改写该头（如统一设置为DENY），机架图等内嵌视图将无法正常显示。仓库提供的两份参考配置均未触碰该头，可直接使用。

说明：文档提供的两份配置是让 NetBox 跑起来所需的最小配置，生产环境建议根据实际需求调整（如限制访问来源、调优 SSL 套件、开启 HTTP/2 等）。

故障排查指南

场景一：完全无法连接

逐项检查：

1. nginx/Apache 是否运行、是否监听正确端口：

   systemctl status nginx # 或 apache2 sudo ss -tlnp | grep -E ':(80|443)\s'

2. 防火墙是否拦截：检查沿途所有防火墙规则（UFW、iptables、云安全组等）。最快的判断方法是在服务器本机执行curl https://localhost测试——本机能通而外部不通，基本可断定问题出在防火墙或安全组。

场景二：能连接但返回 502 Bad Gateway

502 表示反向代理已收到请求，但无法与后端 WSGI 进程建立连接。依次排查：

1. gunicorn/uWSGI 工作进程是否存活：

   systemctl status netbox

   应显示active (running)。若服务启动失败，用journalctl -eu netbox查看日志定位原因。

2. 代理端口是否匹配：nginx/Apache 配置中代理目标是127.0.0.1:8001（默认），确认与 gunicorn 的bind一致（默认 8001，见 contrib/gunicorn.py）。若修改过任一侧端口，必须同步修改另一侧。
3. SELinux 是否拦截代理连接（仅限启用 SELinux 的发行版如 RHEL/Fedora）：允许 HTTP 网络连接：

   setsebool -P httpd_can_network_connect 1

   -P使策略永久生效，重启后仍保留。

源码视角：NetBox 对反向代理的依赖约定

理解下面几个来自 NetBox 源码的约定，能帮你更准确地排查代理层问题：

此外，configuration_example.py 对ALLOWED_HOSTS有详细注释：它是 NetBox 服务器合法完全限定域名（FQDN）列表，列表第一项被视为首选名称，任何其他主机名访问都被拒绝写入。配置示例形如：

ALLOWED_HOSTS = ['netbox.example.com', 'netbox.internal.local']

部署完成后的下一步：扩展插件

NetBox 运行起来后，可通过安装插件扩展能力——插件是可选的组件，为 NetBox 核心增添新模型、视图、集成等功能。安装一个插件通常分三步：

1. 将插件 Python 包追加到/opt/netbox/local_requirements.txt；
2. 在configuration.py的PLUGINS列表中启用该插件；
3. 运行 NetBox 的升级脚本：

sudo sh -c "echo '<package>' >> /opt/netbox/local_requirements.txt" sudo /opt/netbox/upgrade.sh

升级脚本会重建虚拟环境、安装requirements.txt与local_requirements.txt中的全部依赖、应用数据库迁移、收集静态文件并清理过期会话（完整动作清单见 升级指南）。每个插件可能还有额外的配置或安装步骤，动手前务必同时阅读插件自身文档以及 NetBox 官方的 插件安装指南。

小结

本文完整覆盖了 NetBox 生产部署中对外 HTTP 层的全部关键环节：SSL 证书的准备、nginx 与 Apache 两套参考配置的逐行解读与部署步骤、连通性验证与安全注意事项、502 等典型故障的排查路径，以及 NetBox 源码层面对反向代理请求头与ALLOWED_HOSTS的约定。将 contrib/nginx.conf 或 contrib/apache.conf 正确落地，并保持与 Gunicorn / uWSGI 监听端口一致，即可让 NetBox 以 HTTPS 方式稳定对外提供服务。

• 后端
• 网络
• 数据建模