Bluehood快速上手:3条命令用Docker搭建蓝牙设备嗅探仪表盘(附BlueZ避坑清单)

原创2026-10-13 23:03:212,178 阅读

Bluehood快速上手:3条命令用Docker搭建蓝牙设备嗅探仪表盘(附BlueZ避坑清单)

Bluehood 是一款免费的开源蓝牙设备嗅探工具,它能被动监听你周围 2.4GHz 频段内的 BLE 和经典蓝牙设备,自动识别厂商、分类设备类型,并用 Web 仪表盘展示 30 天出现轨迹、信号强度热力图等行为模式。本文教你在 Linux 主机上用 3 条命令通过 Docker 搭建蓝牙设备嗅探仪表盘,并附上一份 BlueZ 避坑清单,新手也能一次跑通。

⚠️ Bluehood 目前处于 Alpha 阶段,属于隐私安全教育工具,请在符合当地法规的前提下仅对自己的环境进行监测。

一、Bluehood 是什么:你的"蓝牙邻居"雷达

Bluehood 会持续扫描附近的蓝牙设备,做到三件事:

  • 📡 持续嗅探:同时支持 BLE(低功耗蓝牙)和 Classic(经典蓝牙)双模扫描
  • 🏷️ 自动分类:通过 MAC 厂商库、BLE 服务 UUID 指纹、设备名特征,把设备归入手机、汽车、音频、可穿戴、IoT 等类别
  • 📊 行为分析:记录 RSSI 信号强度、出现时间段热力图、设备关联(谁和谁总是一起出现)、驻留时长等

设备分类逻辑实现在 bluehood/classifier.py,核心守护进程在 bluehood/daemon.py。

Bluehood蓝牙设备嗅探工具概览页展示项目使命与双模扫描能力

二、开始前:3个硬件与系统前提

前提条件 说明
Linux 主机 Docker 方案仅支持 Linux(macOS 可直装,见文末)
蓝牙 4.0+ 适配器 必须支持 BLE 且带 Central 角色,2.x/3.x 老网卡不行
Docker + Docker Compose 容器运行环境

先验证一下你的适配器是否支持 BLE Central 角色:

bluetoothctl show   # 输出中 Roles 里能看到 central 才算合格

三、3条命令快速搭建

核心原因:Bluehood 需要透过主机的 BlueZ(Linux 蓝牙协议栈)访问蓝牙硬件,Docker 镜像本身不包含 BlueZ,所以第一步必须在宿主机上装好它。

第1条:宿主机安装并启动 BlueZ

sudo apt install bluez && sudo systemctl enable --now bluetooth
# Arch Linux 用户:sudo pacman -S bluez bluez-utils && sudo systemctl enable --now bluetooth

第2条:拉取项目(自带 docker-compose 配置)

git clone https://gitcode.com/gh_mirrors/bl/bluehood && cd bluehood

仓库里自带的 docker-compose.yml 已经配置好了蓝牙访问所需的全部关键项:

  • network_mode: host + privileged: true:让容器能访问蓝牙硬件
  • 挂载 /var/run/dbus:容器通过 D-Bus 与宿主机 BlueZ 通信
  • 内置 healthcheck:启动前会先探测宿主机是否存在 org.bluez 服务,缺失会直接报错提示你装 BlueZ

第3条:启动容器

docker compose up -d

然后验证:

docker compose logs -f   # 看到扫描循环正常滚动即成功

打开浏览器访问 http://localhost:8080,蓝牙设备监控仪表盘就上线了 🎉

四、仪表盘功能速览

Bluehood蓝牙设备嗅探仪表盘展示设备列表、厂商识别与实时统计

打开仪表盘(Recon 页)你会看到:

  • 左侧统计栏:已识别目标数、当前活跃数、新增设备数、被随机化 MAC 隐藏的数量
  • 设备列表:每行显示设备类别(Phone / Car Vehicle 等)、MAC 地址(截图模式下自动打码)、厂商、识别符、累计出现次数
  • 搜索与筛选:按 MAC、厂商、名称搜索,按设备类型过滤,支持日期范围查询

点进单个设备还有 30 天出现时间线、RSSI 信号历史、时段热力图、关联设备等深度数据。界面源码在 bluehood/webapp/server.py,页面模板在 bluehood/webapp/templates.py。

💡 小技巧:按 / 快速聚焦搜索框,w 收藏设备,c 切换紧凑视图,按 ? 查看全部快捷键。

五、配置 ntfy.sh 推送通知(可选)

把设备"到达/离开"推送到手机上:

  1. 在 ntfy.sh 上创建一个 topic(如 bluehood-ops-alerts),手机端订阅它
  2. 进入 Bluehood 的 Config → Alert Configuration 页,填入 topic 并勾选推送开关
  3. 按需勾选触发条件:发现新设备、关注的设备回来、关注的设备离开

Bluehood蓝牙仪表盘通知推送配置页设置ntfy主题与告警触发条件

推送逻辑实现在 bluehood/notifications.py。另外在 Config 的 Operations 页还可以配置心跳上报(对接 Uptime Kuma 等监控)和存储轮转(自动清理 N 天前的记录)。

六、BlueZ 避坑清单 ⚠️

这是新手最容易卡住的地方,按报错对号入座:

报错 / 现象 原因 解决方案
org.freedesktop.DBus.Error.ServiceUnknown: The name org.bluez was not provided 宿主机没装 BlueZ 或 bluetooth 服务未运行 执行第 1 条命令,再 docker compose restart
容器状态 unhealthy compose 的 healthcheck 在宿主机 D-Bus 上找不到 org.bluez systemctl status bluetooth 确认服务在跑
No Bluetooth adapters with BLE 'central' role found 蓝牙适配器太老或无 BLE Central 角色 用 bluetoothctl show 检查 Roles;更换 Bluetooth 4.0+ 网卡
能启动但列表一直是空的 蓝牙没开、位置偏、或适配器没被识别 bluetoothctl power on;docker compose logs -f 看扫描日志
数据目录权限异常 容器用户与宿主机 UID 不匹配 设置环境变量 PUID/PGID 为你宿主机的 id -u/id -g,docker-entrypoint.sh 会在启动时自动同步用户身份

七、常用环境变量速查

在 docker-compose.yml 的 environment 里按需添加:

变量 默认值 用途
BLUEHOOD_ADAPTER 自动 指定 BLE 扫描适配器,如 hci0
BLUEHOOD_CLASSIC_ADAPTER 同上 指定另一个适配器做经典蓝牙扫描,实现双卡并发
TZ UTC 容器时区,如 Asia/Shanghai
BLUEHOOD_PRUNE_DAYS 0(关闭) 自动删除 N 天前的嗅探记录,防磁盘膨胀
BLUEHOOD_METRICS_PORT 关闭 开启 Prometheus 指标端口,如 9199

如果你还想上 Prometheus + Grafana,仓库里自带了可直接导入的 grafana/bluehood-dashboard.json,在 Grafana 的 Dashboards → Import 中导入即可。

八、其他部署方式

  • systemd 常驻(非 Docker):bluehood.service 已提供,sudo cp bluehood.service /etc/systemd/system/ 后 sudo systemctl enable --now bluehood
  • macOS 原生运行:不依赖 BlueZ,走 CoreBluetooth,pip install -e . 后执行 python -m bluehood.daemon 即可(首次运行记得授权蓝牙权限)
  • 数据位置:Docker 下存于 /data 卷(SQLite),裸机在 ~/.local/share/bluehood/bluehood.db

写在最后

3 条命令之后,你就有了一台 7×24 小时默默记录"谁家的蓝牙耳机在楼下出现"的雷达。建议先跑一周再翻热力图——你会发现,蓝牙信号泄露的日常轨迹远比想象中丰富 🕵️ 再次提醒:请把它当作隐私安全教育的镜子,只监测你自己有权限关注的范围。

登录后查看全文
bluehood