博客 / 詳情

返回

NetBox 自動化導入資產 - IP地址

簡介

本文章主要講解使用orb-agent 掃描網絡收集IP信息，通過Diode 攝取到NetBox。

這兩個工具都是NetBox官方的自動化發現產品，下面是示意圖。

<!--more-->

+------------------+
|    orb-agent     |
|------------------|
| 網絡掃描/資產發現 |
+------------------+
          |
          | grpc 通過NMAP/SNMP等掃描結果（IP、主機、服務）
          v
+------------------+
|      Diode       |
|------------------|
| 數據清洗/轉換    |
| 安全傳輸/推送    |
+------------------+
          |
          | grpc 通過Diode插件標準化後的資產數據
          v
+------------------+
|     NetBox       |
|------------------|
| IPAM / DCIM 管理 |
| 資產持續更新     |
+------------------+

相關文檔

https://github.com/netboxlabs/diode

https://github.com/netboxlabs/diode/blob/develop/GET\_STARTED.md

Diode安裝

環境要求

  • NetBox 版本大於 4.2.3
  • Docker 版本大於 27.0.3

Docker 國內安裝

PS：安裝最新版，使用compose V2部署。

https://mirror.nju.edu.cn/mirrorz-help/docker-ce/?mirror=NJU

Docker Hub國內加速
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker-0.unsee.tech",
    "https://docker-cf.registry.cyou",
    "https://docker.1panel.live"
  ]
}
EOF

systemctl enable docker

systemctl daemon-reload && sudo systemctl restart docker

systemctl enable docker

環境介紹

  • 系統使用Rocky Linux 9.7
  • 使用源碼部署的NetBox 4.4.8
  • NetBox訪問地址為 http://192.168.31.173

NetBox部署教程：https://songxwn.com/netbox4-CN/

Docker安裝Diode Server

mkdir /opt/diode
# 創建 Diode 服務的工作目錄，用於存放配置和 compose 文件

cd /opt/diode
# 進入工作目錄，後續文件都會下載到這裏

curl -sSfLo quickstart.sh https://raw.githubusercontent.com/netboxlabs/diode/release/diode-server/docker/scripts/quickstart.sh
# 從官方倉庫下載 Diode 的 quickstart 腳本，用於自動生成 docker-compose.yaml 等文件
# -sSfL 參數確保失敗時退出，並跟隨重定向

chmod +x quickstart.sh
# 給 quickstart.sh 添加可執行權限

./quickstart.sh http://192.168.31.173
# 運行 quickstart 腳本，指定你的 NetBox訪問 URL
# 腳本會自動生成 docker-compose.yaml、配置文件和默認目錄結構

docker compose up -d
# 啓動 Diode 服務（PostgreSQL、Redis、Diode Server 等），並以後台方式運行
# 注意會佔用宿主機8080端口。

查看netbox-to-diode用户的密鑰 - 用於diode插件

echo $(jq -r '.[] | select(.client_id == "netbox-to-diode") | .client_secret' /opt/diode/oauth2/client/client-credentials.json)

Netbox 接入Diode Server

cd /opt/netbox
# 進入 NetBox 的安裝目錄（通常包含 venv、configuration、netbox 源碼等）

source venv/bin/activate
# 激活 NetBox 的 Python 虛擬環境，確保插件安裝到 NetBox 的 venv 中

pip install netboxlabs-diode-netbox-plugin
# 在 NetBox 的虛擬環境中安裝 Diode NetBox 插件，用於與 Diode/Orb 集成


]

開啓插件，並配置接入Diode參數

編輯configuration/configuration.py文件

PLUGINS = [
    "netbox_diode_plugin",

PLUGINS_CONFIG = {
    "netbox_diode_plugin": {
        # Diode gRPC target for communication with Diode server
        "diode_target_override": "grpc://<diode-server:port>/diode",
        # NetBox username associated with changes applied via plugin
        "diode_username": "netbox-to-diode",
        # netbox-to-diode client secret from earlier step
        "netbox_to_diode_client_secret": "NT3yLOQamJpx545nSacRf4IN8VrJ2zmWHkyrD2SkbAc="
    },
}
  • 注意：netbox\_to\_diode\_client\_secret 填寫密鑰為上面獲取到的。

使能插件生效

cd /opt/netbox/netbox
# 進入 NetBox 的 Django 項目目錄（包含 manage.py），插件遷移必須在這裏執行

./manage.py migrate netbox_diode_plugin
# 執行 Diode 插件的數據庫遷移，創建插件所需的表結構

sudo systemctl restart netbox netbox-rq
# 重啓 NetBox 主服務和後台任務隊列，使插件加載並生效

orb Agent 部署

mkdir /opt/orb
# 創建 Orb Agent 的工作目錄，用於存放配置文件、agent.yaml、compose 文件等

cd /opt/orb
# 進入 Orb Agent 的工作目錄，後續所有操作都會在這裏進行

創建/opt/orb/agent.yaml - 網絡掃描導入

orb:
  config_manager:
    active: local
  backends:
    common:
      diode:
        target: grpc://192.168.31.173:8080/diode
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: agent01
    network_discovery:
  policies:
    network_discovery:
      discovery_1:
        config:
          schedule: "* * * * *"
          timeout: 5
          defaults:
            description: IP discovered by network discovery
            tags: [net-discovery, orb-agent]
        scope:
          targets: 
            - 192.168.31.0/24 # IP subnet
            - google.com # dns lookup
          fast_mode: True
          max_retries: 0

注意：grpc://192.168.31.173:8080/diode ，把IP替換為你的服務器IP即可。

🧩 ORB 配置結構總覽

這段 YAML 主要定義了三個部分：

  1. config\_manager：ORB 自身的配置管理方式
  2. backends：ORB 如何把數據上報到後端（如 diode）
  3. policies：定義具體的任務（這裏是 network discovery）

你可以把它類比成：

  • config\_manager = ORB 的“配置源”
  • backends = ORB 的“輸出插件”
  • policies = ORB 的“任務調度器 + 任務定義”

✅ 1. config\_manager

config_manager:
  active: local

意思是：

  • ORB 的配置來源是 本地文件（local）
  • 而不是從遠端配置中心（如 diode server）動態拉取

這意味着你修改本地 YAML 就能立即生效，適合開發/測試環境。

✅ 2. backends（數據上報後端）

backends:
  common:
    diode:
      target: grpc://192.168.31.173:8080/diode
      client_id: ${DIODE_CLIENT_ID}
      client_secret: ${DIODE_CLIENT_SECRET}
      agent_name: agent01
  network_discovery:

🔍 解釋：

common.diode

這是一個通用 backend，所有 policy 都可以複用它。

字段説明：

字段 作用
target diode server 的 gRPC 地址
client_id / client_secret 用於認證（通常來自環境變量）
agent_name ORB agent 的標識，便於後端區分來源

你可以把它理解為：

ORB 發現到的 IP、DNS 結果等，會通過 gRPC 推送到 diode。

network\_discovery:

這裏留空，表示 network\_discovery policy 默認使用 common backend。

✅ 3. policies（任務定義）

這裏定義了一個名為 discovery\_1 的網絡發現任務。

policies:
  network_discovery:
    discovery_1:

✅ 3.1 config（任務執行參數）

config:
  schedule: "* * * * *"
  timeout: 5
  defaults:
    description: IP discovered by network discovery
    tags: [net-discovery, orb-agent]
🔍 字段解釋：
字段 作用
schedule: "* * * * *" 每分鐘執行一次（cron 表達式）
timeout: 5 每個探測任務最多執行 5 秒
defaults.description 發現的資產默認描述
defaults.tags 給發現的資產自動打標籤

你可以把它理解為：

每分鐘跑一次掃描，掃描結果會帶上默認標籤和描述，便於後端分類。

✅ 3.2 scope（掃描範圍）

scope:
  targets:
    - 192.168.31.0/24
    - google.com
  fast_mode: True
  max_retries: 0

🔍 字段解釋：

✅ targets

掃描目標列表，支持：

  • CIDR（如 192.168.31.0/24）
  • 域名（如 google.com）

ORB 會自動：

  • 對子網進行 ping/port 探測
  • 對域名進行 DNS 解析

✅ fast\_mode: True

快速掃描模式：

  • 不做深度端口探測
  • 不做反向 DNS
  • 更適合大規模快速發現

✅ max\_retries: 0

失敗不重試，適合快速巡檢。

✅ 整體流程（用你的視角總結）

ORB 的執行流程理解：

每分鐘：
  └─ network_discovery policy 啓動
       ├─ 掃描 192.168.31.0/24
       ├─ DNS 解析 google.com
       ├─ 發現結果打上默認標籤
       └─ 通過 diode backend 上報到 192.168.31.173:8080

Docker compose 部署orb Agent

創建/opt/orb/docker-compose.yml文件

services:
  orb-agent:
    image: netboxlabs/orb-agent:latest
    container_name: orb-agent
    environment:
      DIODE_CLIENT_ID: "diode-ingest"
      DIODE_CLIENT_SECRET: "NT3yLOQamJpx545nSacRf4IN8VrJ2zmWHkyrD2SkbAc="
    volumes:
      - /opt/orb:/opt/orb
    command: ["run", "-c", "/opt/orb/agent.yaml"]
    restart: unless-stopped
  • DIODE\_CLIENT\_SECRET密鑰通過命令echo $(jq -r '.[] | select(.client_id == "diode-ingest") | .client_secret' /opt/diode/oauth2/client/client-credentials.json) 獲取

部署啓動

docker compose up -d

docker compose logs

成果

技術交流羣

發送郵件到 ➡️ me@songxwn.com

或者關注WX公眾號：網工格物

微信掃碼

博客（最先更新）

https://songxwn.com/

教程
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.