简介
本文章主要讲解使用orb-agent 扫描网络收集IP信息，通过Diode 摄取到NetBox。
这两个工具都是NetBox官方的自动化发现产品，下面是示意图。
+------------------+
| 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 主要定义了三个部分：
config_manager：ORB 自身的配置管理方式
backends：ORB 如何把数据上报到后端（如 diode）
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
