VPS 搭建 NetBox（2026）：Docker、PostgreSQL、IPAM、DCIM、HTTPS 与备份

NetBox 本身不需要很高的 CPU，但 PostgreSQL、Redis、Gunicorn 和后台 worker 会共同占用内存。建议按管理规模选择：

域名可以使用 netbox.example.com。DNS 的 A/AAAA 记录先指向 VPS，数据库和 Redis 只加入 Docker 内网，不要在安全组中开放 5432 和 6379。部署前可参考 VPS 配置怎么选，把备份空间和日志增长算进磁盘预算。

sudo apt update
sudo apt install -y ca-certificates curl git openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker

sudo mkdir -p /opt/netbox
sudo chown -R "$USER":"$USER" /opt/netbox
cd /opt/netbox

NetBox 官方提供容器镜像和示例 compose 文件。生产环境不要使用浮动的 latest，应固定 NetBox、PostgreSQL、Redis 和插件版本，升级前记录当前镜像 digest。可以从官方仓库获取模板后复制一份项目配置：

git clone https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
cp env/netbox.env .env

不同版本的仓库文件名可能变化，执行 ls 和 git log -1 确认模板与镜像标签匹配。不要把包含密码的 .env 提交到公开 Git 仓库。

NetBox 需要 PostgreSQL 保存设备、地址、前缀和变更记录，Redis 用于缓存和后台队列。编辑环境变量时至少修改数据库密码、Redis 密码、站点密钥和超级用户配置：

DB_NAME=netbox
DB_USER=netbox
DB_PASSWORD=change-a-long-database-password
REDIS_PASSWORD=change-a-long-redis-password
SECRET_KEY=replace-with-a-random-secret-key
SUPERUSER_NAME=admin
[email protected]
SUPERUSER_PASSWORD=change-a-long-admin-password

使用 OpenSSL 生成随机值，避免直接使用示例字符串：

openssl rand -base64 48
openssl rand -hex 32
chmod 600 .env

正式启动前先渲染 Compose 配置，检查端口、卷挂载和变量是否为空：

docker compose config
docker compose pull
docker compose up -d
docker compose ps

首次启动需要等待 PostgreSQL 初始化和 NetBox migrate 完成。查看日志时优先关注 netbox、netbox-worker、netbox-housekeeping、postgres 和 redis：

docker compose logs --tail=200 netbox
docker compose logs --tail=200 netbox-worker
docker compose logs --tail=200 postgres

如果容器不断重启，先检查 .env 中的数据库凭据和 SECRET_KEY，不要在未定位原因前反复删除 volume。

容器健康后，可以进入 NetBox 容器创建超级用户或确认自动创建的管理员：

docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser
docker compose exec netbox /opt/netbox/netbox/manage.py check

登录后台后先完成以下基础对象：

• 创建 Site，并按机房、办公室、云区域划分层级。
• 创建 Tenant，将不同客户、部门或业务系统隔离。
• 创建 Manufacturer、Device Type、Role 和 Platform，统一设备命名。
• 创建 Prefix、IP Range、VLAN 和 VRF，明确地址的归属和用途。
• 创建 Rack、Device 和 Interface，记录端口、链路和电源关系。

不要一开始就把所有历史表格一次性导入。先选一个站点做字段映射，验证设备、接口、IP 和前缀的关联关系，再通过 CSV 或 REST API 批量导入。

NetBox 管理后台不应长期暴露在 HTTP 上。可以让 Caddy 监听 80/443，将请求转发到 Docker 发布的本地端口：

sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile

netbox.example.com {
    encode gzip zstd
    reverse_proxy 127.0.0.1:8080
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "SAMEORIGIN"
    }
}

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://netbox.example.com

Caddy 会自动申请和续期证书。反向代理配置可以参考 VPS 用 Caddy 反向代理完全指南。如果页面出现 CSRF、Host 或 HTTPS 重定向错误，检查 NetBox 的 ALLOWED_HOSTS、CSRF_TRUSTED_ORIGINS 和代理传递的协议头。

NetBox 的密码重置、通知和部分插件依赖 SMTP。建议先配置内部测试邮箱，再开放给全体用户，并同时设置 SPF、DKIM、DMARC。邮件发送失败时检查容器时间、DNS、SMTP 端口和服务商的出站策略。

权限设计应按职责拆分：

• 网络管理员可以管理设备、接口、前缀和 VLAN。
• 只读审计账号只允许查看对象和变更日志。
• 自动化脚本使用独立用户和 Token，不要复用管理员 Token。
• 第三方系统只授予需要的对象权限，并设置 Token 过期和轮换流程。

NetBox API 适合与 Ansible、Terraform、CMDB 或监控系统集成。请求 API 时使用 HTTPS，Token 放入密钥管理系统，不要写进 Shell 历史或公开的 CI 日志。

NetBox 的 Web 容器负责请求处理，worker 处理后台任务，housekeeping 执行清理和维护。三者都正常才算部署完成：

docker compose ps
docker compose logs --tail=200 netbox-worker
docker compose logs --tail=200 netbox-housekeeping

如果导入任务或邮件一直处于 pending，先确认 Redis 可连接、worker 没有 OOM，并检查 PostgreSQL 是否出现锁等待。不要直接清空 Redis，因为这可能丢失尚未处理的任务。长期运行时可以用 Prometheus、Beszel 或系统级监控观察内存和磁盘趋势。

NetBox 的可恢复备份至少包括 PostgreSQL 数据库、media 文件、插件配置、.env、Compose 文件和当前镜像版本。先导出数据库：

mkdir -p /opt/netbox/backups
docker compose exec -T postgres pg_dump -U "$DB_USER" "$DB_NAME" | gzip > /opt/netbox/backups/netbox-$(date +%F).sql.gz
docker compose cp netbox:/opt/netbox/netbox/media /opt/netbox/backups/media-$(date +%F)
cp .env docker-compose.yml /opt/netbox/backups/
docker compose config > /opt/netbox/backups/compose-$(date +%F).yaml

如果 .env 未导出到当前 Shell，使用与 compose 相同的数据库用户名和数据库名替换命令中的变量。备份完成后同步到另一台 VPS 或对象存储，并对包含密码的文件加密。可以结合 Restic、Rclone 与 Docker 数据库的恢复演练定期做恢复测试。

恢复时先在隔离域名启动同版本容器，再导入数据库和 media，运行迁移并验证登录、设备查询、API、附件下载和 worker。确认无误后再安排生产切换。

NetBox 升级通常涉及数据库迁移，插件也必须与主版本兼容。推荐流程如下：

1. 记录当前 Git commit、镜像 digest、插件版本和 docker compose config。
2. 做一份经过验证的数据库与 media 备份。
3. 在测试环境拉取目标版本，执行 migrate 和插件检查。
4. 维护窗口内停止写入，更新镜像并运行 manage.py migrate。
5. 检查后台、API、搜索、权限、附件和 worker，再恢复用户访问。

git fetch --tags
git checkout <tested-commit>
docker compose pull
docker compose up -d
docker compose exec netbox /opt/netbox/netbox/manage.py migrate
docker compose exec netbox /opt/netbox/netbox/manage.py check

如果升级失败，不要直接把新数据库接回旧容器。先恢复到旧版本的数据库备份和 media，在隔离环境确认回滚路径，再切换生产 DNS 或反向代理。

• NetBox、PostgreSQL、Redis、worker 和 housekeeping 均为 healthy。
• HTTPS、自动续期、ALLOWED_HOSTS 和 CSRF 域名配置正确。
• 已创建最小权限角色，管理员启用 MFA，API Token 可轮换。
• SMTP 测试成功，密码重置和通知邮件可送达。
• PostgreSQL、media、.env、Compose 和插件版本已异地备份。
• 至少完成一次隔离环境恢复演练，并记录恢复时间。
• 升级前固定版本，升级后验证 API、搜索、附件和后台任务。

NetBox 的价值不只是把 IP 地址搬进一个网页，而是让站点、设备、接口、VLAN、前缀和变更记录形成可查询的关系。先从一个站点建立可靠的数据模型，再逐步接入自动化和监控，VPS 上的 NetBox 才能真正成为网络团队的事实来源。

延伸阅读：

• VPS Docker Compose 生产环境怎么配
• VPS 用 Caddy 反向代理完全指南