shajen/sdr-scanner

sdr-scanner Docker镜像文档

镜像概述

sdr-scanner是一款轻量级Docker镜像，封装了基于软件定义无线电（SDR）技术的频谱扫描工具。该镜像旨在简化无线电频谱监测流程，提供便捷的部署方式，支持实时频谱扫描、数据记录与基础频谱分析功能，适用于无线电爱好者、频谱监测人员及相关科研场景。

核心功能与特性

核心功能

• 多设备支持：兼容主流SDR设备，包括RTL-SDR（RTL2832U）、HackRF One、Airspy等
• 灵活扫描配置：支持自定义频率范围、扫描步长、采样率及扫描速度
• 数据记录：支持将扫描结果以CSV或JSON格式保存至本地文件系统
• 实时频谱可视化：集成基础频谱 waterfall 图与频谱密度显示（需通过Web UI或VNC访问）
• 低资源占用：优化Docker镜像体积，最小化运行时CPU/内存消耗

关键特性

• 即插即用：无需手动安装SDR驱动与依赖库，Docker容器自动配置设备环境
• 跨平台兼容：支持x86_64与ARM架构（如Raspberry Pi）
• 可扩展配置：通过环境变量或配置文件自定义高级扫描参数（如增益、滤波阈值）

使用场景与适用范围

典型使用场景

• 无线电爱好者进行频谱探索与监测
• 企业/机构监测特定频段内的无线电活动（如ISM频段、航空频段）
• 科研实验中的频谱数据采集与分析
• 无线电干扰排查与异常信号定位

适用人群

• 无线电爱好者与业余无线电操作员
• 频谱管理与监测从业人员
• 电子工程与通信专业科研人员

使用方法与配置说明

前置条件

• 已安装Docker Engine（20.10+）或Docker Desktop
• 物理机已连接兼容的SDR设备，并确保用户具有设备访问权限（Linux系统需将用户添加至plugdev或docker用户组）
• （可选）若需可视化功能，需安装VNC客户端或配置Web UI端口映射

快速启动（Docker Run）

基础扫描命令（RTL-SDR设备）

bash
docker run -d \
  --name sdr-scanner \
  --device /dev/bus/usb:/dev/bus/usb \  # 挂载USB设备（SDR通常通过USB连接）
  -v ./sdr-data:/app/data \             # 挂载数据目录（用于保存扫描记录）
  -e DEVICE_TYPE=rtl-sdr \              # 指定SDR设备类型
  -e FREQUENCY_START=88000000 \         # 起始频率（单位：Hz，示例为88MHz，FM广播频段）
  -e FREQUENCY_END=108000000 \          # 结束频率（单位：Hz，示例为108MHz）
  -e SAMPLE_RATE=2048000 \              # 采样率（单位：Hz，建议值：2048000-3200000）
  -e SCAN_STEP=100000 \                 # 扫描步长（单位：Hz，默认100kHz）
  sdr-scanner:latest

带数据记录的扫描命令

bash
docker run -d \
  --name sdr-scanner-record \
  --device /dev/bus/usb:/dev/bus/usb \
  -v ./sdr-records:/app/records \       # 挂载记录目录
  -e DEVICE_TYPE=hackrf \               # 使用HackRF设备
  -e FREQUENCY_START=433000000 \        # 433MHz ISM频段
  -e FREQUENCY_END=435000000 \
  -e SAMPLE_RATE=8000000 \
  -e OUTPUT_FORMAT=json \               # 输出格式：json 或 csv
  -e RECORD_INTERVAL=60 \               # 数据记录间隔（单位：秒，默认60s）
  sdr-scanner:latest

Docker Compose配置示例

创建docker-compose.yml文件：

yaml
version: '3.8'
services:
  sdr-scanner:
    image: docker.xuanyuan.run/sdr-scanner:latest
    container_name: sdr-scanner
    devices:
      - /dev/bus/usb:/dev/bus/usb  # 映射USB设备总线
    volumes:
      - ./sdr-data:/app/data       # 持久化扫描数据
    environment:
      - DEVICE_TYPE=rtl-sdr
      - FREQUENCY_START=144000000  # 144MHz业余无线电VHF频段
      - FREQUENCY_END=146000000
      - SAMPLE_RATE=2400000
      - GAIN=30                    # 接收增益（单位：dB，范围：0-50）
      - SCAN_SPEED=500000          # 扫描速度（Hz/秒，默认500kHz/s）
      - LOG_LEVEL=info             # 日志级别：debug/info/warn/error
    restart: unless-stopped         # 设备断开后自动重启容器

启动服务：

bash
docker-compose up -d

环境变量配置说明

数据持久化

扫描记录与日志文件默认保存在容器内/app/data目录，建议通过Docker卷（Volume）或绑定挂载（Bind Mount）持久化至宿主机，避免容器重启后数据丢失：

bash
# 绑定挂载示例（宿主机目录 ./sdr-data 映射至容器 /app/data）
-v /path/on/host/sdr-data:/app/data

常见问题解决

SDR设备无法识别

• 确认宿主机用户已加入plugdev组（Linux系统）：sudo usermod -aG plugdev $USER
• 检查设备是否被其他进程占用：sudo lsof | grep -i rtl
• 重启Docker服务：sudo systemctl restart docker

扫描数据异常或无输出

• 检查频率范围是否在设备支持范围内（如RTL-SDR通常支持24MHz-1.7GHz）
• 调整采样率与增益参数（增益过低可能导致信号无法检测）
• 查看容器日志排查错误：docker logs sdr-scanner

镜像更新与维护

• 获取最新镜像：docker pull docker.xuanyuan.run/sdr-scanner:latest
• 查看镜像版本：docker inspect --format='{{.Config.Labels.version}}' sdr-scanner:latest
• 提交反馈或问题：访问项目GitHub仓库（https://github.com/example/sdr-scanner%EF%BC%89%E6%8F%90%E4%BA%A4Issue

---

注：使用本工具需遵守当地无线电管理***，未经授权不得监测受保护频段或进行非法无线电活动。