02-NetBox Docker Compose 部署指南

上一篇采用传统 Linux 服务方式部署 NetBox。本篇改用社区维护的 netbox-community/netbox-docker 项目，把 NetBox、PostgreSQL、Redis 和 worker 编排为一套 Docker Compose 应用。目标不是只让首页出现，而是得到一套版本明确、秘密受控、数据持久、可监控、可备份、可升级和可回退的容器化部署。

netbox-docker 是 NetBox 社区维护的容器项目，不等同于 NetBox 核心仓库。它定期构建镜像，并提供 Compose、配置和入口脚本。官方仓库当前 quickstart 使用 release 分支、示例 override、docker compose pull 和 docker compose up。生产环境必须让仓库中的支持文件版本与镜像 tag 匹配，不能从不同教程拼接一份 Compose 后长期依赖 latest。

本文以单主机 Docker Compose 为范围，适合试点、中小型生产、实验和灾备副本。若需要跨主机调度、自动故障转移和平台级存储，应评估 Kubernetes、NetBox Enterprise 或组织已有容器平台，而不是把单机 Compose 包装成集群。

什么情况下选择 Compose

Compose 的优势是封装应用依赖、快速重建、版本化配置和明确容器边界。团队可以在测试环境使用与生产相同的镜像和 Compose 版本，通过更新 tag 完成发布，回滚时恢复旧镜像和数据库。它也便于在隔离主机上快速建立升级验证副本。

Compose 不是“免运维”。PostgreSQL 数据、媒体、配置和秘密仍需要治理；Docker Engine、网络、卷、日志和镜像供应链成为新的运维对象。容器重启成功不代表数据库迁移、后台 worker 和 API 正常。

适合优先使用 Compose 的情况：

• 团队已有 Docker Engine、Compose、镜像仓库和容器监控能力。
• 希望快速建立可重复的测试与生产环境。
• NetBox 插件和配置可以通过镜像或挂载统一管理。
• 接受单主机故障后通过备份和备用主机恢复。
• 希望用明确镜像 tag 完成升级和回退。

不适合直接选择 Compose 的情况：

• 团队没有容器安全、卷备份和日志经验。
• 需要跨节点高可用却只准备一台 Docker 主机。
• 企业要求数据库由独立平台团队托管。
• 插件和自定义代码仍依赖大量宿主机手工修改。
• 计划频繁进入容器直接改文件，无法形成可重复镜像。

理解官方项目的组成

默认项目通常包含 NetBox Web 应用、worker、housekeeping、PostgreSQL、Redis 与 Redis cache 等服务，具体名称和结构以所用 release 分支为准。多个 NetBox 相关容器使用同一镜像，但启动命令不同：Web 处理 HTTP，worker 执行队列任务，housekeeping 执行计划维护。

Compose 文件描述基础服务，docker-compose.override.yml 用于现场差异。环境配置通常位于 env/ 或配置目录，secrets 可以通过文件方式传入。不要假设旧教程中的文件名永远不变，克隆后先阅读当前 README、Wiki、Compose 文件和示例 override。

仓库版本和镜像有两层版本。官方仓库说明，类似 vX.Y.Z-a.b.c 的 tag 同时包含 NetBox 版本和 netbox-docker 支持文件版本；生产推荐使用明确的 vX.Y.Z-a.b.c 或 vX.Y-a.b.c。若只写 vX.Y.Z，仍要确认它对应的支持文件。latest 会移动，不适合作为长期可重复发布基线。

镜像、Compose 和配置相互配套。仅修改 VERSION 指向任意镜像而不更新仓库，可能出现入口脚本、变量或健康检查不兼容。升级时应切换到目标 netbox-docker release，再按其说明选择镜像，而不是保留多年未更新的 Compose。

主机前提与安全边界

准备一台受支持 Linux 主机，安装受维护的 Docker Engine 和 Compose plugin。官方仓库 README 当前列出 Docker、containerd 和 Compose 的最低要求，但这些最低值不是生产推荐值。应使用供应商仍提供安全更新的版本，并再次核对目标 netbox-docker release。

验证：

docker version
docker compose version
containerd --version

Docker daemon 权限接近宿主机 root。只把 docker 组授予受信管理员，不让普通 NetBox 数据维护者登录容器主机。使用防火墙限制 SSH 和对外端口，启用时间同步、磁盘和日志监控。

规划目录，例如：

/srv/netbox/
├── repository/
├── secrets/
├── backups/
└── operations/

仓库保存 Compose 与非敏感配置；secrets 目录只允许管理员和部署服务读取；backups 放短期本地备份并复制到独立存储；operations 保存运行手册。不要把数据库备份和数据卷放在同一故障域。

确认主机有足够磁盘。容器镜像、PostgreSQL 卷、媒体、容器日志、构建缓存和备份都会增长。生产应为 Docker 数据目录和数据库建立容量告警，定期清理无引用镜像，但不能误删正在用于回退的版本。

获取官方 release

官方 quickstart 当前使用：

sudo install -d -m 0750 /srv/netbox
sudo chown "$USER":"$USER" /srv/netbox
cd /srv/netbox
git clone -b release https://github.com/netbox-community/netbox-docker.git repository
cd repository
cp docker-compose.override.yml.example docker-compose.override.yml

生产环境应记录当前 Git commit 或 release tag：

git status
git rev-parse HEAD
git describe --tags --always

更严格的环境可以从内部 Git 和镜像仓库部署。将官方 release 审核后镜像到内部源，保留上游 commit、镜像 digest 和安全扫描结果。生产主机不必在发布窗口直接访问 GitHub 或公共 Docker Hub。

不要在克隆后的主 Compose 文件中直接做大量本地修改。尽量使用 override 和外部配置，升级时更容易比较上游变化。若确实修改入口脚本或基础 Compose，应形成自己的派生仓库和测试流程。

固定镜像版本

先阅读当前仓库的版本变量和 compose 引用：

grep -R "VERSION" -n docker-compose.yml docker-compose.override.yml env 2>/dev/null
docker compose config --images

按照目标 release 的说明，将版本固定为明确 tag。不要在本文中把某个 2026 年的版本写成永久推荐，因为 NetBox 与 netbox-docker 都会持续发布。你的部署记录必须保存“NetBox 版本、netbox-docker 版本、镜像 digest、插件版本”四类信息。

拉取后记录 digest：

docker compose pull
docker image inspect netboxcommunity/netbox:REPLACE_WITH_TAG \
  --format '{{json .RepoDigests}}'

命令中的镜像名和 tag 按当前 Compose 输出替换。若使用内部镜像仓库，镜像同步后也要验证 digest 与批准制品一致。

管理秘密

不要在 docker-compose.override.yml 中提交数据库密码、超级管理员密码、SECRET_KEY 或 token pepper。官方项目支持从环境或文件读取多类配置，具体变量名以当前 env/*.env、configuration/ 和 Wiki 为准。

建立 secrets 目录：

sudo install -d -m 0700 /srv/netbox/secrets

使用安全随机生成器创建独立秘密，不复用同一个值。示意：

umask 077
openssl rand -base64 48 > /srv/netbox/secrets/secret_key
openssl rand -base64 32 > /srv/netbox/secrets/postgres_password

是否需要其他 secret 文件以及文件名，必须按当前项目示例配置。不要因为变量读取失败就把秘密重新写回 Git。Compose secrets 在单机模式下主要改善文件挂载与权限管理，不等同于专业密钥系统；企业环境可以在部署时从 Vault 或其他密钥平台渲染临时文件。

首次管理员建议在容器启动后交互创建，而不是把长期有效的超级管理员密码写入环境。只有频繁重建空环境的自动化测试才考虑 SUPERUSER_*，并确保秘密不会进入镜像、日志或版本库。

轮换数据库或 Redis 密码要同时修改服务端和 NetBox 配置，并安排维护窗口。SECRET_KEY 和 token 相关秘密的轮换影响更大，应查当前 NetBox 文档和在副本演练。

编写最小 override

复制示例 override 后，先理解当前项目提供的默认项，再保留必要差异。一个概念性片段如下，字段和服务名以实际 release 为准：

services:
  netbox:
    ports:
      - "127.0.0.1:8000:8080"

只绑定 127.0.0.1 表示由宿主机反向代理访问，避免 NetBox 容器端口直接暴露所有网络。若反向代理在另一个主机或容器网络，应按架构调整并使用防火墙。不要照抄 0.0.0.0:8000 到公网生产。

Compose override 还可以设置重启策略、日志、资源、外部网络、额外挂载和代理。不要一开始覆盖上游所有配置，否则后续无法判断哪些是本地差异。每个 override 项都写明目的和验证方式。

使用：

docker compose config

渲染后的配置会合并变量，输出可能包含敏感信息，不要上传工单或共享日志。重点检查服务、镜像、端口、卷、网络、环境和依赖。语法通过后仍要做功能验证。

数据持久化

容器可以删除和重建，数据必须独立持久化。核心范围包括 PostgreSQL 数据、媒体、配置、秘密和必要 Redis 数据。当前官方 Compose 使用命名卷或配置的具体方式以 release 为准。

列出卷：

docker compose config --volumes
docker volume ls

不要通过备份 Docker 容器可写层保护数据。容器可写层随删除消失，也不适合作为数据库一致性备份。PostgreSQL 应使用 pg_dump、物理备份或数据库平台支持的方式。

媒体卷保存上传附件等内容。若恢复数据库却不恢复媒体，记录仍在但文件丢失。配置与秘密决定实例能否正确启动，也要与数据库版本配套备份。

Redis 是否需要持久化取决于项目默认配置和任务恢复要求。即使允许缓存丢失，也要理解队列中任务会发生什么。不能把 Redis 卷一概视为无关。

生产可以将卷映射到独立数据盘，但 bind mount 权限必须匹配容器运行用户。不要使用 chmod 777。先通过镜像文档和 docker inspect 确认 UID/GID，再授予最小权限。

首次启动

拉取并启动：

cd /srv/netbox/repository
docker compose pull
docker compose up -d

第一次启动需要创建数据库 schema、执行迁移、收集静态文件和启动依赖，时间可能长于普通重启。不要十秒后看到 unhealthy 就反复重建。观察：

docker compose ps
docker compose logs -f netbox

需要时分别查看 PostgreSQL、Redis、worker 和 housekeeping 服务日志，服务名称以 docker compose ps 为准：

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

如果进程以 137 退出，通常先检查主机或容器内存，不要误判为数据库 schema 错误。首次迁移可能需要明显资源，尤其在受限虚拟机中。

确认 Web 容器健康后，从宿主机测试：

curl -I http://127.0.0.1:8000/

端口按 override 替换。测试通过再配置正式反向代理。

创建管理员

官方仓库当前 quickstart 给出的方式是：

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

交互创建时使用独立管理员账号和强密码。完成权限与 SSO 配置后，超级管理员仅用于平台治理和紧急处理。

若是自动化测试环境，可按当前项目文档使用 SUPERUSER_*。生产不应把固定初始密码保留在 override 或 Git 中。自动创建后立即轮换或禁用临时凭据。

配置正式入口

一种简单做法是在宿主机 Nginx 终止 HTTPS，再代理到 127.0.0.1:8000。也可以使用 Traefik、Caddy 或外部负载均衡，但职责相同：提供正式域名、证书、Host 和协议头，限制后端暴露。

反向代理配置必须与 NetBox ALLOWED_HOSTS 和其他 URL 相关设置一致。若外部访问出现 DisallowedHost、重定向到 HTTP、静态资源失败或 CSRF 错误，先检查代理头、域名和 NetBox 配置，不要永久关闭安全检查。

验证：

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

浏览器确认登录、静态文件和证书。API 消费者从自己的运行环境测试 DNS 和 TLS，管理员笔记本可访问不代表自动化主机可访问。

若直接用 Compose 内的 Nginx 或其他网关，仍要固定其镜像、配置、证书挂载和日志。入口组件也属于部署制品，不能在宿主机临时手改而没有记录。

安装插件和自定义代码

生产不应进入正在运行的容器执行 pip install 后就结束。容器重建会丢失修改，不同服务副本也可能不一致。正确做法是建立派生镜像，在 Dockerfile 中安装固定插件版本和复制受控自定义代码。

概念性 Dockerfile：

FROM netboxcommunity/netbox:REPLACE_WITH_PINNED_TAG

COPY plugin_requirements.txt /opt/netbox/
RUN /opt/netbox/venv/bin/pip install --no-cache-dir \
    -r /opt/netbox/plugin_requirements.txt

具体基础镜像、用户和路径以目标 netbox-docker release 为准。构建后执行安全扫描，推送内部仓库，使用明确 tag 和 digest。所有 NetBox、worker 和 housekeeping 服务必须使用同一派生镜像。

插件还需要 NetBox 配置和数据库迁移。先在恢复副本验证，确认支持的 NetBox 版本和卸载方案。若插件升级失败，回退不仅是镜像，还可能需要恢复数据库。

Custom scripts、reports、模板和配置可以在镜像中复制或通过只读挂载提供。选择一条一致路线，不要一部分在镜像、一部分在运行容器内手改。所有代码进入版本控制和评审。

监控容器化 NetBox

监控分三层。宿主机层关注 CPU、内存、磁盘、inode、Docker daemon、网络和时间；容器层关注状态、重启次数、健康检查、资源和日志；应用层关注 HTTPS、API、后台任务、PostgreSQL、Redis、备份与数据消费。

docker compose ps 只能人工查看，生产应由监控系统持续采集。容器处于 running 不代表应用可用，健康检查也可能只覆盖部分链路。外部 HTTPS 检查和低权限 API 查询更接近用户体验。

日志可以使用 Docker logging driver、宿主机文件或集中平台。必须配置轮转，避免 JSON 日志耗尽磁盘。过滤数据库密码、token 和请求中的敏感字段。调试完成后恢复正常级别。

PostgreSQL 与 Redis 容器也需要专门监控。数据库卷空间、连接、锁、备份和恢复比容器 CPU 更重要。Redis 要看内存、连接、延迟和任务队列。worker 停止时 Web 仍可能正常，因此必须单独告警。

记录每次部署的 Compose commit、镜像 digest 和启动时间。发生故障时，能确认当前真正运行的版本，而不是只看 Git 工作区。

容器网络与入口设计

Compose 默认会为项目创建网络，服务通过 Compose 服务名通信。NetBox 容器访问 postgres 或 redis 时，名称由 Docker DNS 解析；容器里的 127.0.0.1 只表示当前容器，不是宿主机或其他服务。很多连接失败都来自把传统单机配置中的 localhost 原样带入容器。

数据库和 Redis 不需要发布到宿主机端口时，就不要添加 ports。同一 Compose 网络中的应用可以通过内部端口访问。对外只发布反向代理或 NetBox入口，减少攻击面。运维临时访问数据库可以使用 docker compose exec 或受控管理网络，而不是长期暴露 5432 和 6379。

默认 Compose 网络提供基本隔离，但不是完整安全策略。宿主机 root 或 Docker 管理员仍可访问容器和挂载秘密。高安全环境要限制 daemon、镜像、主机登录和出站网络，并使用企业容器平台的网络策略与密钥能力。

如果使用宿主机 Nginx，NetBox 端口绑定到 loopback 最清晰。如果反向代理也是容器，则建立专用入口网络，让代理连接 NetBox，数据库和 Redis 留在后端网络。不要把所有服务放入一个被多个项目共享的公共网络。

服务发现依赖项目名和网络。复制同一 Compose 到测试与生产时，显式设置不同项目名或目录，避免容器、网络和卷名称冲突。恢复演练尤其要确认测试实例不会意外连接生产数据库或 Redis。

代理头必须受信。只有由受控反向代理设置的 X-Forwarded-Proto、Host 和客户端地址才可用于应用判断。若后端端口被普通用户直接访问，攻击者可能伪造头。通过网络和防火墙保证后端只接受代理流量。

使用外部 PostgreSQL 或 Redis

组织已有托管 PostgreSQL 时，可以让 Compose 只运行 NetBox 应用和 worker。这样数据库备份、高可用和监控由平台承担，但应用配置、网络和版本兼容仍由 NetBox 团队负责。

切换外部数据库前确认 PostgreSQL 版本在目标 NetBox 支持范围，数据库使用 UTF-8，应用用户拥有目标数据库和 schema 所需权限。连接地址应是稳定的读写入口，不要指向可能变为只读副本的单个节点。

跨主机数据库连接必须关注延迟、DNS、TLS、连接限制和维护窗口。NetBox Web、worker 和 housekeeping 都会建立连接，数据库团队需要看到总连接模型。连接池或代理只有在经过验证并受支持时使用，不能用来掩盖数据库容量问题。

外部 Redis 同样需要明确任务和缓存的实例或逻辑数据库。若 Redis 平台启用集群、哨兵、TLS 或特殊认证，先确认当前 NetBox 与 netbox-docker 配置支持方式。无法验证的组合不要直接用于生产。

Compose 中移除本地 PostgreSQL/Redis 服务时，不能只注释容器，还要调整 depends_on、健康检查、环境和备份脚本。使用 docker compose config 检查最终模型，并在空测试环境启动。

外部服务改变恢复责任。NetBox 团队要能获得数据库恢复点和演练证据，数据库团队要知道应用版本与迁移窗口。只说“数据库由平台负责”而没有联合恢复流程，会在事故时互相等待。

从源码安装迁移到 Compose

迁移的核心是数据和版本，不是复制应用目录。先确认旧实例 NetBox 与插件版本，选择能够直接承载该数据库 schema 的目标 netbox-docker 组合。若旧版本太早，应先按官方升级路径在原环境或副本升级，不要把多年旧库直接接到最新镜像。

盘点旧环境：PostgreSQL、configuration.py、SECRET_KEY、token peppers、媒体、自定义脚本、reports、插件、LDAP/OAuth、邮件、Webhook、证书和反向代理。把每项映射到 Compose 的配置、secret、派生镜像或挂载位置。

先在隔离环境迁移副本。导出旧数据库和媒体，使用匹配版本镜像恢复，配置相同秘密和插件，启动后验证。若目标是同时升级，先完成“同版本迁移”，证明容器化没有改变功能，再单独执行版本升级。把两个重大变化分开更容易定位问题。

正式切换前停止旧实例写入，完成最终数据库和媒体备份，记录时间点。启动 Compose 后执行数据库迁移、登录、API、后台任务、附件、权限、插件和关键自动化验证。DNS 或负载入口切换前，使用临时 hosts 或测试域名完成检查。

回退时必须考虑新实例是否已经接收写入。若切换后产生新数据，简单重新启动旧实例会丢失这些变更。回退方案应规定维护窗口内禁止或限制写入，或者把新数据库恢复到旧平台支持的状态。跨版本数据库通常不能直接向后兼容。

迁移完成后保留旧环境只读或关机一段观察期，但必须防止两个实例同时成为写入口。最终销毁前确认备份、审计、自动化目标和秘密轮换。

发布流水线与环境一致性

可重复部署不应依赖管理员在服务器上敲一串命令。仓库至少包含上游版本引用、override、派生 Dockerfile、插件 requirements、非敏感配置、测试和操作文档。秘密由发布环境注入。

提交时执行静态检查：YAML 解析、docker compose config、禁止 latest 或 snapshot、禁止明文密码、检查端口是否意外绑定所有地址、验证镜像来源。派生镜像构建后进行漏洞扫描和软件清单记录。

测试环境从空卷启动一次，验证全新安装；再从生产脱敏备份恢复一次，验证升级路径。这两类测试不同：空环境证明初始化，恢复环境证明真实 schema、插件和数据能工作。

应用测试至少覆盖登录、/api/status/、一个只读 API、一个受控创建与删除、后台任务、静态文件和插件页面。权限测试使用普通用户和自动化用户，不仅使用超级管理员。

发布制品使用不可变 tag 和 digest。生产部署读取批准版本，不在服务器上临时构建。若必须在受限环境构建，也要保存上下文、依赖和 digest，使灾备可以重现。

发布流程保留旧制品和数据库恢复点，设置观察窗口。指标异常时回退到明确组合，不能执行另一次未测试构建“碰碰运气”。发布结束后把实际运行 digest回写资产或部署记录。

容器安全加固

优先使用上游受维护镜像，不自行添加无关调试工具。派生镜像采用最少层和固定依赖，构建阶段不写入秘密。镜像仓库启用访问控制、扫描和签名或来源验证。

容器尽量以镜像规定的非 root 用户运行。不要为了挂载权限强制改成 root。需要调整宿主机目录时，按 UID/GID 赋权。只读配置用只读挂载，只有媒体、临时目录和必要路径允许写。

限制 Linux capabilities、特权模式、宿主机设备和 Docker socket。NetBox 不需要 privileged: true，也不需要挂载 /var/run/docker.sock。任何要求这些权限的插件或脚本都应被视为高风险设计。

为容器设置合理资源边界可以防止单个进程耗尽主机，但边界要经过测试。内存过低会在数据库迁移或高峰时 OOM；CPU 过低会让请求和任务积压。资源限制不是性能调优替代品。

根文件系统只读是否可行取决于镜像和挂载设计，应在当前 release 测试。临时目录、静态文件初始化和插件可能需要写入。不要为了形式上的加固破坏入口脚本。

控制出站访问。NetBox 可能需要邮件、Webhook、SSO、插件或外部 API，但不应默认访问任意网络。列出必要目标，并监控异常连接。代理凭据和 CA 证书通过受控挂载提供。

定期更新宿主机、Docker、Compose、基础镜像和应用，但分开测试。镜像扫描发现漏洞后判断漏洞组件是否可达、上游是否有修复以及升级兼容，不直接在运行容器中 apt upgrade，因为重建后修改会消失。

典型事故复盘

事故一：管理员把镜像从固定版本改为 latest，执行 pull 后 NetBox 自动跨版本升级，插件不兼容，数据库迁移完成但 Web 无法启动。根因不是容器，而是版本不可重复。修复需要恢复升级前数据库和旧镜像；预防措施是禁止移动 tag、测试升级和保存 digest。

事故二：为了迁移目录，直接复制正在运行的 PostgreSQL volume 文件。新主机启动后数据库无法恢复或出现一致性问题。根因是把文件复制当数据库备份。正确做法是使用 pg_dump 或受支持物理备份，并在隔离环境验证。

事故三：修改 POSTGRES_PASSWORD 后以为数据库用户密码已更新，NetBox持续认证失败。数据库镜像初始化变量通常只在空数据目录生效，已有卷不会自动修改内部账号。应在 PostgreSQL 中执行受控密码变更，同时更新应用 secret。

事故四：所有容器显示 running，但自动化 Webhook 长时间不执行。Web 容器正常，worker 因插件导入错误持续重启。监控只覆盖首页，没有覆盖 worker 和队列。预防是分别监控服务角色，并在发布验收中执行后台任务。

事故五：Docker JSON 日志占满磁盘，PostgreSQL无法写入，NetBox整体故障。团队只监控数据库卷，未监控 Docker 数据目录。应配置 logging driver 轮转、宿主机文件系统告警和安全清理流程。

事故六：恢复测试实例误用了生产 Webhook 和邮件配置，创建测试设备后触发真实自动化。恢复副本必须在隔离网络使用替代 secrets，禁用外部副作用，并清晰标记环境。

事故七：管理员执行 docker compose down -v 想“重启干净”，同时删除命名卷。down 和 down -v 风险完全不同。生产运行手册应禁止破坏性选项，关键操作需要双人确认和近期备份。

每次事故都应更新自动检查，而不是只提醒“下次小心”。例如 CI 禁止 latest，备份任务验证 dump，监控发现 worker 重启，日志轮转由配置管理保证，恢复环境自动替换外部端点。

备份

数据库逻辑备份可通过 PostgreSQL 容器执行。服务名、用户名和路径按实际 Compose 替换：

mkdir -p /srv/netbox/backups
chmod 700 /srv/netbox/backups

docker compose exec -T postgres \
  pg_dump -U netbox -d netbox -Fc \
  > "/srv/netbox/backups/netbox-$(date +%F-%H%M).dump"

命令需要在目标 release 验证环境变量和用户。输出重定向发生在宿主机，执行后检查文件非空并使用 pg_restore --list 验证目录。不能只根据退出码认为备份有效。

还要备份：

• Git commit、override 和非敏感配置。
• secrets 的加密副本。
• 媒体卷。
• 派生镜像的 Dockerfile、requirements 和 digest。
• 插件清单与配置。
• 反向代理和证书配置。
• 恢复与升级文档。

命名卷备份不能靠直接复制正在写入的 PostgreSQL 数据目录。数据库必须使用一致性工具。媒体卷可以在明确一致性要求下文件级备份，必要时短暂停止写入。

备份复制到独立存储并设置保留、加密和访问审计。主机被勒索或磁盘损坏时，本地 /srv/netbox/backups 可能同时丢失。

恢复演练

恢复演练准备一台隔离 Docker 主机，安装兼容 Engine 和 Compose，检出与备份一致的 netbox-docker commit，拉取相同镜像 digest，恢复 secrets、配置和媒体。

先启动 PostgreSQL 与 Redis，再把数据库 dump 恢复到空数据库。具体命令按 Compose 服务和 PostgreSQL 版本验证。恢复前确认目标数据库确实是隔离空库，避免误覆盖生产。

启动 NetBox 后检查迁移状态、登录、对象数量、附件、API、worker、插件和关键查询。禁用生产 Webhook、邮件和外部自动化，避免恢复副本触发真实动作。

记录实际恢复时间、缺失文件、人工步骤和错误。把修订反馈到备份与部署流程。每次重大版本或插件变化后重新演练，因为旧恢复手册可能不再适用。

升级

升级同时涉及 NetBox 和 netbox-docker。先阅读 NetBox release notes、升级指南、netbox-docker release 说明和插件兼容。确认是否需要跨中间版本，不从一个陈旧版本直接跳到最新。

升级前保存：

git rev-parse HEAD
docker compose config --images
docker compose ps

并完成数据库、媒体、配置和 secrets 备份。最好从生产备份建立测试副本，在目标 Compose 和镜像上运行迁移并记录耗时。

生产发布的一般流程是：

1. 停止写入或建立维护窗口。
2. 完成升级前备份并验证。
3. 切换到目标 netbox-docker release。
4. 合并上游 Compose 变化与本地 override。
5. 固定匹配的 NetBox 镜像和插件镜像。
6. docker compose pull。
7. docker compose up -d。
8. 观察迁移、应用、worker 和数据库日志。
9. 完成功能和权限验收。

不要使用 git pull 后不看差异直接启动。先比较示例 env、override 和 Compose。上游可能新增必需变量、服务、卷或健康检查。

升级后的旧镜像应暂时保留，但数据库迁移后仅切回镜像通常不构成安全回退。回退需要恢复升级前数据库、配置、媒体和旧镜像组合。回退在测试环境演练后才可信。

故障排查

容器不断重启时：

docker compose ps
docker compose logs --tail=300 netbox
docker inspect "$(docker compose ps -q netbox)"

检查退出码、OOM、健康检查、配置和依赖。退出码 137 优先检查内存和宿主机日志。不要反复 down -v，-v 可能删除数据卷。

数据库认证失败时，检查 secrets 或环境是否一致、PostgreSQL 数据卷是否来自旧部署、密码是否在初始化后被修改。PostgreSQL 官方镜像的初始化变量通常只在空数据目录首次生效，修改环境变量不会自动修改已有数据库用户密码。

数据库迁移失败时，停止继续重启并保存日志。确认 NetBox 镜像与仓库版本、插件和数据库版本。不要手工删除 migration 记录。必要时恢复升级前备份。

Redis 连接失败时，检查服务名、网络、密码、逻辑数据库和容器状态。Compose 内服务通常通过服务名解析，不能把容器内的 localhost 当成 Redis 容器。

页面 502 时，先检查反向代理到宿主机映射，再检查 NetBox 容器。页面 400 时检查 ALLOWED_HOSTS 和代理 Host。静态文件失败时检查镜像启动、路径和反向代理规则。

容器 healthy 但后台任务不运行时，检查 worker 服务和队列。多个服务使用不同镜像版本时也会产生异常，比较各容器 image ID。

磁盘快速增长时分别检查 PostgreSQL 卷、媒体、Docker JSON 日志、无引用镜像和构建缓存。清理前确认对象用途，禁止在不了解的情况下运行激进 prune。

日常运行与交付

每日检查服务、worker、数据库、Redis、磁盘、HTTPS 和备份。每周检查容器重启、错误日志、任务失败和镜像漏洞。每月复审 Docker/Compose、NetBox、插件和操作系统支持状态。每季度执行恢复演练和权限复审。

Compose 目录应是受控部署仓库。生产变更通过 pull request 或等价审批，CI 至少验证 YAML、docker compose config、禁止明文秘密和镜像 tag。测试环境启动相同组合后，再批准生产。

交付物包括：主机与端口、Git commit、镜像 tag 和 digest、override、secrets 管理、卷清单、反向代理、插件镜像、备份恢复、升级回退、监控告警、账号权限和责任人。

上线验收要覆盖重启 Docker 主机、创建和查询对象、API、后台任务、附件、备份与隔离恢复。只有容器可重建、数据可恢复、版本可追踪，Compose 路线才真正发挥价值。

验收还必须包含负向场景。普通只读用户应无法创建和删除对象，受限自动化 token 不应读取未授权范围，未受信域名不能绕过 ALLOWED_HOSTS，数据库和 Redis 端口不应从普通办公网络访问。删除测试容器后重新 up，数据和附件必须仍在；切换到一台空白主机恢复时，不能依赖原主机中未记录的手工文件。

对每项验收保存命令、时间、结果和负责人。容器状态、页面截图和一份备份文件都只是局部证据；完整结论需要同时证明应用、数据、权限、后台任务、外部入口和恢复路径。若某项因环境限制未测试，应在交付清单中明确风险和补测日期，不能默认为已经通过。

每月还应把生产 docker compose config 的非敏感结果与批准仓库比较，检查端口、镜像、卷和环境是否发生漂移。发现临时修改后，应纳入代码并重新测试，或恢复批准配置，不能让服务器上的手工状态长期成为唯一事实。

这项复审应持续执行。

与源码安装路线比较

源码安装把 Python 环境、systemd、Gunicorn 和 Nginx 直接交给 Linux 管理，便于精细调试，但团队需要维护依赖。Compose 把应用依赖装进镜像，重建和环境一致性更好，但要求团队理解容器、卷和镜像供应链。

插件方面，源码安装可在虚拟环境安装，但仍需固定版本；Compose 更适合通过派生镜像安装。数据库方面，两条路线都必须备份 PostgreSQL。安全方面，两条路线都不能使用弱密码、明文秘密和裸露管理端口。

不要因为 Compose 命令短就认为更简单。真正复杂度从安装包转移到镜像、Compose、卷和发布。选择团队能够长期维护的方式，并通过恢复演练验证，而不是按个人偏好决定。

小结

可靠的 NetBox Compose 部署建立在官方 netbox-docker release、匹配镜像、最小 override、受控 secrets、持久化卷、HTTPS 入口和可恢复数据库之上。初次启动只是开始，插件应进入派生镜像，日志和 worker 要单独监控，升级必须同时管理 NetBox、netbox-docker 和数据库迁移。

下一篇进入 IPAM，不再讨论安装方式，而是用 VRF、RIR、Aggregate、Prefix、VLAN 和 IP address 建立可供分配、审计与自动化消费的地址空间模型。

参考资料

• netbox-community/netbox-docker：官方社区容器项目与 Quickstart，检索日期 2026-06-12，https://github.com/netbox-community/netbox-docker
• netbox-community/netbox-docker Wiki，检索日期 2026-06-12，https://github.com/netbox-community/netbox-docker/wiki
• Docker Documentation：Install Docker Engine，检索日期 2026-06-12，https://docs.docker.com/engine/install/
• Docker Documentation：Docker Compose，检索日期 2026-06-12，https://docs.docker.com/compose/
• Docker Documentation：Manage data in Docker，检索日期 2026-06-12，https://docs.docker.com/engine/storage/
• NetBox Documentation：Installation，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/
• NetBox Documentation：Upgrading NetBox，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/upgrading/
• NetBox Documentation：Configuration，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/configuration/
• netbox-community/netbox Releases，检索日期 2026-06-12，https://github.com/netbox-community/netbox/releases
• PostgreSQL Documentation：Backup and Restore，检索日期 2026-06-12，https://www.postgresql.org/docs/current/backup.html