Bluehood快速上手:3条命令用Docker搭建蓝牙设备嗅探仪表盘(附BlueZ避坑清单)
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。
二、开始前: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,蓝牙设备监控仪表盘就上线了 🎉
四、仪表盘功能速览
打开仪表盘(Recon 页)你会看到:
- 左侧统计栏:已识别目标数、当前活跃数、新增设备数、被随机化 MAC 隐藏的数量
- 设备列表:每行显示设备类别(Phone / Car Vehicle 等)、MAC 地址(截图模式下自动打码)、厂商、识别符、累计出现次数
- 搜索与筛选:按 MAC、厂商、名称搜索,按设备类型过滤,支持日期范围查询
点进单个设备还有 30 天出现时间线、RSSI 信号历史、时段热力图、关联设备等深度数据。界面源码在 bluehood/webapp/server.py,页面模板在 bluehood/webapp/templates.py。
💡 小技巧:按 / 快速聚焦搜索框,w 收藏设备,c 切换紧凑视图,按 ? 查看全部快捷键。
五、配置 ntfy.sh 推送通知(可选)
把设备"到达/离开"推送到手机上:
- 在 ntfy.sh 上创建一个 topic(如
bluehood-ops-alerts),手机端订阅它 - 进入 Bluehood 的 Config → Alert Configuration 页,填入 topic 并勾选推送开关
- 按需勾选触发条件:发现新设备、关注的设备回来、关注的设备离开
推送逻辑实现在 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 小时默默记录"谁家的蓝牙耳机在楼下出现"的雷达。建议先跑一周再翻热力图——你会发现,蓝牙信号泄露的日常轨迹远比想象中丰富 🕵️ 再次提醒:请把它当作隐私安全教育的镜子,只监测你自己有权限关注的范围。


