devonm/netbox

netbox-docker-plugins 镜像文档

1. 镜像概述和主要用途

netbox-docker-plugins 是一个基于官方 NetBox 构建的 Docker 镜像，预集成了三个增强插件，旨在简化 NetBox 部署流程并扩展其功能。该镜像适用于需要快速搭建具备额外功能的 NetBox 实例的场景，无需手动安装和配置插件。

2. 核心功能和特性

2.1 镜像特性

• 基于官方 NetBox Docker 镜像构建，确保兼容性和稳定性
• 预安装插件，减少部署后配置步骤
• 支持标准 NetBox 环境变量和配置方式，易于集成现有部署流程

2.2 预装插件功能

2.2.1 netbox-secretstore

• 功能：提供敏感信息（如密钥、凭证）的安全存储和管理能力
• 特性：支持加密存储、访问控制、审计日志，集成 NetBox 权限系统

2.2.2 netbox-lists

• 功能：允许用户创建和管理自定义列表，用于组织和分类 NetBox 资源
• 特性：支持列表共享、条件筛选、自定义字段，提升资源管理灵活性

2.2.3 netbox-plugin-auth-saml2

• 功能：提供 SAML2 协议认证支持，集成企业身份提供商（IdP）
• 特性：支持单点登录（SSO）、角色映射、多 IdP 配置，增强身份认证安全性

3. 使用场景和适用范围

3.1 适用场景

• 企业级 NetBox 部署：需集中管理敏感数据（如设备凭证）的团队
• 身份认证集成：使用 SAML2 协议（如 Azure AD、Okta）的组织
• 资源分类管理：需要自定义列表功能组织网络资源的场景

3.2 适用范围

• 中小型网络管理团队
• 需快速部署带扩展功能 NetBox 的环境
• 符合 SAML2 认证标准的企业 IT 架构

4. 使用方法和配置说明

4.1 前置要求

• Docker Engine 20.10+
• Docker Compose 2.0+（推荐）
• 外部 PostgreSQL 数据库（版本 13+）
• 外部 Redis 服务（版本 6+）

4.2 部署示例

4.2.1 使用 docker run 部署

bash
docker run -d \
  --name netbox-plugins \
  -p 8000:8000 \
  -e SECRET_KEY="your-secure-secret-key" \
  -e DATABASE_URL="postgres://user:password@postgres:5432/netbox" \
  -e REDIS_URL="redis://redis:6379/0" \
  -e ALLOWED_HOSTS="localhost,192.168.1.100" \
  -e SAML2_AUTH_ENABLED="true" \
  -e SAML2_AUTH_METADATA_URL="https://idp.example.com/metadata.xml" \
  --restart unless-stopped \
  netbox-docker-plugins:latest

4.2.2 使用 docker-compose 部署

创建 docker-compose.yml 文件：

yaml
version: '3.8'

services:
  netbox:
    image: netbox-docker-plugins:latest
    container_name: netbox
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - SECRET_KEY=your-secure-secret-key
      - DATABASE_URL=postgres://netbox:netbox@db:5432/netbox
      - REDIS_URL=redis://redis:6379/0
      - ALLOWED_HOSTS=localhost,netbox.example.com
      - DEBUG=False
      # SAML2 插件配置
      - SAML2_AUTH_ENABLED=true
      - SAML2_AUTH_ENTITY_ID=https://netbox.example.com/saml2/metadata
      - SAML2_AUTH_METADATA_URL=https://idp.example.com/metadata.xml
      - SAML2_AUTH_ATTRIBUTE_MAPPING=username=uid,email=mail,first_name=givenName,last_name=surname
      # SecretStore 插件配置
      - SECRETSTORE_ENCRYPTION_KEY=your-encryption-key-for-secrets
    depends_on:
      - db
      - redis

  db:
    image: postgres:14-alpine
    container_name: netbox-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=netbox
      - POSTGRES_PASSWORD=netbox
      - POSTGRES_DB=netbox
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    container_name: netbox-redis
    restart: unless-stopped
    volumes:
      - redis-data:/data

volumes:
  postgres-data:
  redis-data:

启动服务：

bash
docker-compose up -d

4.3 配置说明

4.3.1 基础环境变量（必填）

4.3.2 插件专用环境变量

netbox-plugin-auth-saml2

netbox-secretstore

4.3.3 配置验证

部署后，通过访问 http://<netbox-host>:8000/plugins/ 验证插件是否加载成功，各插件应显示在插件列表中。

5. 注意事项

• SECRET_KEY 和 SECRETSTORE_ENCRYPTION_KEY 需妥善保管，丢失将导致数据不可用
• SAML2 配置需与 IdP 同步，确保元数据 URL 可访问且属性映射正确
• 镜像基于官方 NetBox 构建，版本兼容性请参考对应 NetBox 版本文档
• 生产环境建议启用 HTTPS，可通过反向代理（如 Nginx）配置 TLS 证书

6. 插件官方文档参考

• https://github.com/dansheps/netbox-secretstore
• https://github.com/devon-mar/netbox-lists
• https://github.com/jeremyschulman/netbox-plugin-auth-saml2