探针部署

探针客户端用于分布式网络扫描，将扫描任务分发到各网段的独立节点执行。

部署方式

环境变量方式

在 1Panel 中创建 Docker Compose 应用，使用以下配置：

services:
  ipam-probe:
    image: ccr.ccs.tencentyun.com/ipam-go/probe:latest
    container_name: ipam-probe
    network_mode: host
    restart: unless-stopped
    cap_add:
      - NET_RAW
      - NET_ADMIN
    volumes:
      # 探针状态持久化（避免容器重启后全量扫描）
      - probe-state:/var/lib/ipam-probe
      # 探针日志
      - ./probe-logs:/var/log/ipam-probe
      # 探针配置文件（可选，挂载时使用配置文件模式，不挂载时使用环境变量模式）
      # - ./probe-config/probe.toml:/etc/ipam-probe/probe.toml:ro
    environment:
      - TZ=${TZ:-Asia/Shanghai}
      - API_SERVER=${PROBE_API_SERVER:-http://127.0.0.1:12389}
      - API_KEY=${PROBE_API_KEY:-}
      - LOG_LEVEL=${PROBE_LOG_LEVEL:-info}

  volumes:
    probe-state:
      driver: local

环境变量配置

# ==============================================================================
# 1. 时间与区域
# ==============================================================================
TZ=Asia/Shanghai

# ==============================================================================
# 2. 探针客户端
# ==============================================================================
# 探针镜像
PROBE_IMAGE=ccr.ccs.tencentyun.com/ipam-go/probe:latest
# API 服务器地址
PROBE_API_SERVER=http://ipam-server:12389
# API 密钥（在管理后台创建）
PROBE_API_KEY=your-api-key
# 日志级别
PROBE_LOG_LEVEL=info

部署步骤

1. 在 1Panel 中创建 Docker Compose 应用
2. 将上述 Docker Compose 配置粘贴到 compose 配置中
3. 将上述环境变量粘贴到环境变量配置中
4. 点击部署

权限要求

探针需要 host 网络模式及 NET_RAW、NET_ADMIN 权限以执行 ICMP 和 ARP 扫描：

• host 网络模式：ARP/MAC 扫描需要访问主机的网络栈
• NET_RAW：允许使用原始套接字（ICMP Ping）
• NET_ADMIN：允许执行 ARP 扫描等网络管理操作

探针参数说明

CLI 参数：

参数	说明	默认值
-a	API 服务器地址	必填
-i	扫描间隔（秒）	60
-c	配置文件路径	probe.toml
-g	生成配置文件模板	—
-s	注册为 systemd 服务	—

环境变量：

变量	说明	默认值
PROBE_IMAGE	探针镜像地址	ccr.ccs.tencentyun.com/ipam-go/probe:latest
API_SERVER	API 服务器地址	—
API_KEY	API 密钥	—
LOG_LEVEL	日志级别	info

故障排查

探针无法连接

# 检查探针日志
docker logs ipam-probe

# 验证 API 密钥
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:12389/api/probe/validate-api-key

# 检查网络连通性
ping ipam-server

扫描不到 MAC 地址

1. 检查网络连通性
2. 确认 ARP 协议未被阻断
3. 检查防火墙设置
4. 验证容器是否具有 NET_RAW 和 NET_ADMIN 权限

探针离线

1. 检查探针网络连接
2. 验证 API 密钥有效性
3. 检查 API 服务器可达性
4. 查看探针日志