haji/netbox

netbox-docker

本仓库包含将NetBox构建为Docker容器所需的组件。使用此代码构建的镜像每晚发布至https://hub.docker.com/r/ninech/netbox/tags/。

有疑问？在GitHub上提交issue前，请加入Network To Code并在#netbox-docker频道寻求帮助。

快速启动

如需启动NetBox：

bash
$ git clone -b master https://github.com/ninech/netbox-docker.git
$ cd netbox-docker
$ docker-compose pull
$ docker-compose up -d

几分钟后应用即可使用。使用docker-compose port nginx 8080查看连接地址：

bash
$ echo "http://$(docker-compose port nginx 8080)/"
http://0.0.0.0:32768/

# 在macOS上用默认浏览器打开netbox：
$ open "http://$(docker-compose port nginx 8080)/"

# 在大多数Linux系统上用默认浏览器打开netbox：
$ xdg-open "http://$(docker-compose port nginx 8080)/" &>/dev/null &

或者，使用https://github.com/ninech/reception连接到docker-compose项目。

默认凭据：

• 用户名：admin
• 密码：admin
• API令牌：0123456789abcdef0123456789abcdef01234567

依赖项

本项目仅依赖Docker和docker-compose，需满足以下要求：

• Docker版本至少为1.13.0
• docker-compose版本至少为1.10.0

可通过docker --version和docker-compose --version命令检查版本是否符合要求。

配置

可通过环境变量配置应用，这些变量定义在netbox.env中。参考Compose中的环境变量了解覆盖这些变量的多种方式（最简单的方法是直接修改该文件）。

所有可能的变量可查看https://github.com/ninech/netbox-docker/blob/master/docker/configuration.docker.py和https://github.com/ninech/netbox-docker/blob/master/docker/docker-entrypoint.sh文件。通常，环境变量与NetBox配置变量同名。数组类型的变量通常通过空格分隔多个值，例如ALLOWED_HOSTS=localhost ::1 127.0.0.1允许通过http://localhost:8080、http://[::1]:8080和http://127.0.0.1:8080访问NetBox。

生产环境

默认设置针对（本地）开发环境优化，生产环境需调整配置，至少修改以下变量：

• ALLOWED_HOSTS：添加所有指向NetBox实例的URL，空格分隔。例如ALLOWED_HOSTS=netbox.mycorp.com server042.mycorp.com 2a02:123::42 10.0.0.42 localhost ::1 127.0.0.1（建议始终允许本地连接以便调试，即localhost ::1 127.0.0.1）
• DB_*：使用自己的持久化数据库，不要使用默认密码！
• EMAIL_*：使用自己的邮件服务器
• MAX_PAGE_SIZE：建议使用默认值1000
• SUPERUSER_*：仅在初始设置时定义，数据库设置完成后删除，不要使用默认密码！
• REDIS_*：使用自己的持久化Redis，不要使用默认密码！

在Docker Swarm/Kubernetes/OpenShift上运行

可在Docker Swarm、Kubernetes或OpenShift等集群中运行此镜像，但这属于高级用法。

建议通过容器平台提供的机制（如Docker Swarm配置、Kubernetes ConfigMap、OpenShift ConfigMaps），从https://github.com/digitalocean/netbox/blob/develop/netbox/netbox/configuration.example.py开始静态配置NetBox，并将其挂载到容器的/etc/netbox/config/目录。

若仍希望通过环境变量配置，可继续使用https://github.com/ninech/netbox-docker/blob/master/docker/configuration.docker.py。但不建议在环境变量中存储密钥，因为环境变量会传递给所有子进程，可能轻易泄露到其他系统（如错误收集工具常收集所有环境变量）。

因此，强烈建议使用容器平台提供的密钥机制（如Docker Swarm密钥、Kubernetes密钥、OpenShift密钥）。https://github.com/ninech/netbox-docker/blob/master/docker/configuration.docker.py和https://github.com/ninech/netbox-docker/blob/master/docker/docker-entrypoint.sh尝试从以下文件加载密钥：若环境变量和对应文件同时定义密钥，以环境变量值为准。

• SUPERUSER_PASSWORD：/run/secrets/superuser_password
• SUPERUSER_API_TOKEN：/run/secrets/superuser_api_token
• DB_PASSWORD：/run/secrets/db_password
• SECRET_KEY：/run/secrets/secret_key
• EMAIL_PASSWORD：/run/secrets/email_password
• NAPALM_PASSWORD：/run/secrets/napalm_password
• REDIS_PASSWORD：/run/secrets/redis_password

同时请参考上述生产环境运行建议！

NAPALM配置

自v2.1.0起，NAPALM已与NetBox深度集成。NAPALM允许NetBox从设备获取实时数据并通过REST API返回给请求者。了解NAPALM及其工作原理，可参考NAPALM文档或NetBox集成文档。

如需启用此功能，在netbox.env（或相应密钥机制）中配置以下变量：

• NAPALM_USERNAME：用于连接网络设备的通用用户名
• NAPALM_PASSWORD：与用户名配合使用的密码
• NAPALM_TIMEOUT：连接设备超时时间（无响应时）

若不需要此功能，保持这些变量为空即可。

自定义报告

NetBox包含自定义报告功能，允许用户编写Python代码验证NetBox中的数据有效性。REPORTS_ROOT变量映射到容器内的/reports/目录，包含文档中的devices.py示例，但已重命名为devices.py.example以避免默认报告不满足预期时产生问题。

如需启用默认报告，将devices.py.example重命名为devices.py，然后在WebUI中访问/extras/reports/。也可动态添加其他报告到此目录，NetBox无需重启即可识别。

自定义初始化代码（如自动设置自定义字段）

使用docker-compose时，/opt/netbox/startup_scripts中的所有Python脚本将在应用启动后以./manage.py上下文自动执行。

此机制可用于多种场景，例如创建NetBox自定义字段：

python
# docker/startup_scripts/load_custom_fields.py
from django.contrib.contenttypes.models import ContentType
from extras.models import CF_TYPE_TEXT, CustomField

from dcim.models import Device
from dcim.models import DeviceType

device      = ContentType.objects.get_for_model(Device)
device_type = ContentType.objects.get_for_model(DeviceType)

my_custom_field, created = CustomField.objects.get_or_create(
    type=CF_TYPE_TEXT,
    name='my_custom_field',
    description='我的自定义字段'
)

if created:
  my_custom_field.obj_type.add(device)
  my_custom_field.obj_type.add(device_type)

初始化器

初始化器是内置的启动脚本，用于定义NetBox自定义字段、组、用户等资源。只需挂载自己的initializers文件夹（https://github.com/ninech/netbox-docker/blob/master/docker-compose.yml）。参考https://github.com/ninech/netbox-docker/tree/master/initializers了解文件格式。

自定义字段定义示例：

yaml
# initializers/custom_fields.yml
text_field:
  type: text
  label: 自定义文本
  description: 在文本字段中输入文本
  required: false
  filter_logic: loose
  weight: 0
  on_objects:
  - dcim.models.Device
  - dcim.models.Rack
  - ipam.models.IPAddress
  - ipam.models.Prefix
  - tenancy.models.Tenant
  - virtualization.models.VirtualMachine

用户/组初始化器的可用权限组

获取最新可用权限列表，运行以下命令：

bash
# 确保'netbox'容器已运行！不确定可运行`docker-compose up -d`
echo "from django.contrib.auth.models import Permission\nfor p in Permission.objects.all():\n  print(p.codename);" | docker-compose exec -T netbox ./manage.py shell

自定义Docker镜像

也可构建包含自定义启动脚本、自定义字段、用户和组的NetBox Docker镜像：

dockerfile
ARG VERSION=latest
FROM ninech/netbox:$VERSION

COPY startup_scripts/ /opt/netbox/startup_scripts/
COPY initializers/ /opt/netbox/initializers/

Netbox版本

docker-compose.yml文件已配置为运行特定版本的NetBox。如需使用此功能，在启动docker-compose前设置环境变量VERSION，VERSION可设为https://hub.docker.com/r/ninech/netbox/tags/：

bash
$ export VERSION=v2.2.6
$ docker-compose pull netbox
$ docker-compose up -d

也可构建特定版本的NetBox镜像。此时VERSION表示https://github.com/digitalocean/netbox/releases上的任何有效Git引用，通常为标签或分支名：

bash
$ export VERSION=develop
$ docker-compose build --no-cache netbox
$ docker-compose up -d

提示：若按标签名构建特定版本，--no-cache参数并非必需，可加快配置调整时的构建速度。

LDAP启用变体

标记为“-ldap”的镜像包含用于LDAP或Active Directory服务器认证的所有必要组件。默认配置ldap_config.py适用于Active Directory服务器。可通过环境变量注入自定义值，与主要配置机制类似。

故障排除

本节收集常见问题及解决方法。若问题未列出，可查看现有issues或创建新issue。

Docker Compose基础操作

• 使用docker-compose ps查看项目所有运行容器
• 使用docker-compose logs -f查看日志，docker-compose logs -f netbox仅显示netbox日志
• 使用docker-compose stop停止所有服务
• 使用docker-compose down -v --remove-orphans清理所有资源（将删除所有相关数据）
• 使用docker-compose exec netbox /bin/bash进入运行中的NetBox容器shell，可访问./manage.py（如重置密码）
• 访问数据库：docker-compose exec postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'
• 创建数据库备份：docker-compose exec postgres sh -c 'pg_dump -cU $POSTGRES_USER $POSTGRES_DB' | gzip > db_dump.sql.gz
• 恢复数据库备份：gunzip -c db_dump.sql.gz | docker exec -i $(docker-compose ps -q postgres) sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'

Nginx无法启动

首先停止docker-compose设置，然后找到并删除netbox-nginx-config卷：

bash
# 停止本地netbox-docker安装
$ docker-compose down

# 查找卷
$ docker volume ls | grep netbox-nginx-config
local               netbox-docker_netbox-nginx-config

# 删除卷
$ docker volume rm netbox-docker_netbox-nginx-config
netbox-docker_netbox-nginx-config

然后重新启动。若问题仍存在，查看日志：

bash
$ docker-compose logs -f nginx

出现“Bad Request (400)”错误

连接NetBox实例时出现“Bad Request (400)”错误。

通常是ALLOWED_HOSTS变量设置不正确导致。

如何升级

如何更新到新版本的netbox？

拉取最新镜像、停止并重启容器即可：

bash
docker-compose pull netbox
docker-compose stop netbox netbox-worker
docker-compose rm -f netbox netbox-worker
docker-compose up -d netbox netbox-worker

Webhooks不工作

首先确保Webhooks功能已启用且定义了Redis主机。检查netbox.env是否定义以下变量：

WEBHOOKS_ENABLED=true
REDIS_HOST=redis

然后确保redis容器和至少一个netbox-worker正在运行：

bash
# 检查容器状态
$ docker-compose ps

Name                           Command               State                Ports
--------------------------------------------------------------------------------------------------------
netbox-docker_netbox-worker_1   /opt/netbox/docker-entrypo ...   Up
netbox-docker_netbox_1          /opt/netbox/docker-entrypo ...   Up
netbox-docker_nginx_1           nginx -c /etc/netbox-nginx ...   Up      80/tcp, 0.0.0.0:32776->8080/tcp
netbox-docker_postgres_1        docker-entrypoint.sh postgres    Up      5432/tcp
netbox-docker_redis_1           docker-entrypoint.sh redis ...   Up      6379/tcp

# 连接Redis并发送PING命令：
$ docker-compose run --rm -T redis sh -c 'redis-cli -h redis -a $REDIS_PASSWORD ping'
Warning: Using a password with '-a' option on the command line interface may not be safe.
PONG

若redis和netbox-worker不可用，确保已更新docker-compose.yml文件！

若所有服务正常运行，检查netbox-worker和/或redis日志：

bash
docker-compose logs -f netbox-worker
docker-compose logs -f redis

仍无法解决，可连接redis容器监控执行的命令：

bash
docker-compose run --rm -T redis sh -c 'redis-cli -h redis -a $REDIS_PASSWORD monitor'

# 按多次CTRL-C退出

触发Webhook后无任何输出，需检查netbox和netbox-worker容器配置及NetBox管理界面中的Webhook配置。

重大变更

有时需要重新设计此设置结构，可能导致docker-compose.yml或Kubernetes/OpenShift配置需调整。自2018年4月起，从此仓库构建的每个镜像均包含NETBOX_DOCKER_PROJECT_VERSION标签。可通过docker inspect ninech/netbox:v2.3.1 --format "{{json .ContainerConfig.Labels}}"查看本地镜像标签，与以下列表比较是否存在重大变更：

• 0.7.0：MAX_PAGE_SIZE环境变量值改为NetBox默认值1000
• 0.6.0：默认启动脚本命名变更，若自定义脚本可能需调整
• 0.5.0：Alpine更新至3.8，*.env移至/env文件夹
• 0.4.0：使用NetBox Webhooks需在docker-compose.yml中添加Redis和netbox-worker
• 0.3.0：字段filterable: <boolean替换为`filter