03-NetBox进阶指南 1.0：自动化管理 IP 地址资产

- 这篇文章把 IP 发现 -> NetBox 纳管 -> 审计告警串成第一条可运行的自动化闭环。 - 重点不在单一脚本，而在如何把 Orb、Diode、Python 和钉钉组合成长期可维护的资产治理流程。 - 如果你已经完成基础部署，建议从这篇开始进入 NetBox 的工程化使用阶段。

NetBox Diode 与 Orb-Agent 同步架构

作者：数字卢语 · 发布：2026-04-08 · 更新：2026-04-13

摘要

这篇文章把 IP 发现 -> NetBox 纳管 -> 审计告警 串成第一条可运行的自动化闭环。
重点不在单一脚本，而在如何把 Orb、Diode、Python 和钉钉组合成长期可维护的资产治理流程。
如果你已经完成基础部署，建议从这篇开始进入 NetBox 的工程化使用阶段。

本文基于已完成的 NetBox 部署，讲解如何实现 IP 地址自动发现 + 自动审计 + 自动告警 的完整闭环体系。

一、整体方案说明

本方案包含两大核心能力：

自动发现 IP 地址
- 使用 Orb-agent 扫描网络
- 通过 Diode 自动同步至 NetBox
自动化审计与告警
- Python 脚本定期审计 IP 活跃状态
- 钉钉自动推送异常

二、系统架构设计

同步架构

整个系统采用四层架构，实现从“发现 → 管理 → 审计”的闭环：

扫描层（Orb-agent）
        ↓
传输层（Diode）
        ↓
核心管理层（NetBox）
        ↓
审计告警层（Python + 钉钉）

各层职责

扫描层（Orb-agent）
- 执行网络扫描
- 通过 gRPC 上报数据
传输层（Diode）
- 数据清洗与标准化
- 统一数据入口
核心层（NetBox）
- 作为 Source of Truth
- 存储所有 IP 资产
审计层（Python）
- 监控 IP 活跃状态
- 自动告警

三、基础环境配置

3.1 软件版本

操作系统：Ubuntu 22.04
NetBox：4.4.7
Python：3.10.12

3.2 Docker 镜像源

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.1panel.live",
    "https://hub.rat.dev"
  ]
}

3.3 Docker 安装

## 安装依赖

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg jq

# 添加 Docker 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加仓库
echo "deb [arch=$(dpkg --print-architecture) \
signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

## 安装 Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin

四、NetBox 与 Diode 集成部署

配置闭环

4.1 获取密钥

## 密钥 A（插件）
echo $(jq -r '.[] | select(.client_id == "netbox-to-diode") | .client_secret' /opt/diode/oauth2/client/client-credentials.json)

## 密钥 B（Agent）
echo $(jq -r '.[] | select(.client_id == "diode-ingest") | .client_secret' /opt/diode/oauth2/client/client-credentials.json)

4.2 部署 Diode Server

mkdir -p /opt/diode && cd /opt/diode

curl -sSfLo quickstart.sh \
https://raw.githubusercontent.com/netboxlabs/diode/release/diode-server/docker/scripts/quickstart.sh

chmod +x quickstart.sh

./quickstart.sh http://10.10.10.10

docker compose up -d

4.3 NetBox 插件安装

cd /opt/netbox
source venv/bin/activate

pip install netboxlabs-diode-netbox-plugin

4.4 插件配置

PLUGINS = [
    "netbox_diode_plugin",
]

PLUGINS_CONFIG = {
    "netbox_diode_plugin": {
        "diode_target_override": "grpc://10.10.10.10:8080/diode",
        "netbox_to_diode_client_secret": "密钥A",
    }
}

4.5 数据库迁移

cd /opt/netbox/netbox
./manage.py migrate netbox_diode_plugin

sudo systemctl restart netbox netbox-rq

五、Orb-Agent 部署

5.1 创建目录

mkdir /opt/orb
cd /opt/orb

5.2 配置 agent.yaml

orb:
  backends:
    common:
      diode:
        target: grpc://10.10.10.10:8080/diode
        client_id: "diode-ingest"
        client_secret: ${DIODE_INGEST_SECRET}

  policies:
    network_discovery:
      discovery_main:
        config:
          schedule: "0 0 * * *"
          concurrency: 50
          defaults:
          tags: [net-discovery, orb-agent]
          scope:
            targets:
              - 10.10.10.0/24
            exclude:
              - 10.10.10.0/28
          fast_mode: True

5.3 Docker Compose

services:
  orb-agent:
    image: netboxlabs/orb-agent:latest
    container_name: orb-agent
    environment:
      DIODE_CLIENT_ID: "diode-ingest"
      DIODE_CLIENT_SECRET: "密钥B"
    volumes:
      - /opt/orb:/opt/orb
    command: ["run", "-c", "/opt/orb/agent.yaml"]
    restart: unless-stopped

5.4 启动 Agent

docker compose up -d
docker compose logs

六、自动化审计与钉钉推送

6.1 逻辑设计

7天未更新 → 告警
30天未更新 → 标记为 Deprecated
每日推送状态报告

6.2 环境准备

source /opt/netbox/venv/bin/activate
pip install pynetbox requests

6.3 定时任务

crontab -e

0 9 * * * /opt/netbox/venv/bin/python3 /opt/orb/check_ips.py >> /var/log/netbox_ip_audit.log 2>&1

6.4 Python 示例代码

import pynetbox
import requests
import json
from datetime import datetime, timedelta, timezone

NB_URL = "http://10.10.10.10"
NB_TOKEN = "你的API_TOKEN"

DAYS_STALE = 7
DAYS_OFFLINE = 30

DINGTALK_WEBHOOK = "https://oapi.dingtalk.com/robot/send?access_token=你的TOKEN"
AT_MOBILES = ["你的手机号"]

nb = pynetbox.api(NB_URL, token=NB_TOKEN)
now = datetime.now(timezone.utc)

def send_msg(content):
    data = {
        "msgtype": "markdown",
        "markdown": {
            "title": "IP资产自动化审计",
            "text": content
        }
    }
    requests.post(DINGTALK_WEBHOOK, data=json.dumps(data),
                  headers={"Content-Type": "application/json"})

def main():
    ips = nb.ipam.ip_addresses.filter(tag='orb-agent')

    stale = []
    offline = []

    for ip in ips:
        last_seen = datetime.fromisoformat(ip.last_updated.replace('Z', '+00:00'))

        if last_seen < now - timedelta(days=DAYS_OFFLINE):
            ip.status = 'deprecated'
            ip.save()
            offline.append(ip.address)

        elif last_seen < now - timedelta(days=DAYS_STALE):
            stale.append(ip.address)

    msg = "审计结果：\n"
    msg += f"异常IP：{stale}\n"
    msg += f"弃用IP：{offline}"

    send_msg(msg)

if __name__ == "__main__":
    main()

七、排错指南

7.1 Agent 无法同步

查看日志：

docker logs orb-agent

问题定位：

Unauthenticated → 密钥错误
Connection Refused → Diode 未启动

7.2 插件未生效

检查：

configuration.py 中 PLUGINS 是否正确
是否重启 NetBox

7.3 Python 报错

确认：

source /opt/netbox/venv/bin/activate
pip install pynetbox requests

八、总结

本方案实现了：

自动发现 IP（Orb）
自动入库（Diode + NetBox）
自动审计（Python）
自动告警（钉钉）

最终形成：

IP 资产自动化管理闭环体系

九、延伸建议

可进一步扩展：

对接 Zabbix / ELK
接入多站点统一管理
构建自动化运维平台

摘要