安装与设置指南

1. 下载 .dmg 并打开。
2. 把 DeviceShelf 拖进「应用程序」文件夹。
3. 从 Launchpad 或「应用程序」里打开。它经过 Apple 公证，直接就能启动，不会弹安全警告。

系统要求：macOS 12 或更高版本（Apple Silicon 与 Intel）。按设备实时带宽需要提升权限，参见实时带宽。其余功能开箱即用。

1. 下载安装程序（.exe）——Intel/AMD 选 x64，Snapdragon / Copilot+ 电脑选 ARM64 版。
2. 运行它。Windows SmartScreen 可能提示发布者未经验证（该版本未签名）：点击更多信息 → 仍要运行。
3. 跟着安装向导走完，然后启动 DeviceShelf。

要看实时带宽：先装 Npcap。Windows 上按设备统计带宽依赖抓包，因此需要 Npcap。安装程序会引导你安装；你也可以自行下载 Npcap，然后重启 DeviceShelf。扫描、端口、安全报告等其余功能无需 Npcap。

延伸阅读：启用实时带宽。

DeviceShelf 提供 AppImage（免安装，随处可跑）以及原生 .deb / .rpm 包，支持 x86-64 和 ARM64。

要装 .deb？请用终端，别双击——在 Ubuntu 24.04 上双击 .deb 会交给 App Center 处理，可能悄无声息地失败：

sudo apt install ./DeviceShelf-*.deb

完整的 Linux 指南（AppImage、.rpm、抓包权限）：在 Linux 上安装。

iPhone 和 iPad 版的 DeviceShelf 已上架 App Store。Android 版以直装 APK 的形式提供，由你自己安装——没有 Google Play 上架。许可证密钥在桌面端和移动端通用，买一次覆盖你所有设备。

如果要不间断地监控，还有一个无界面的服务器版：可跑在 Docker 里、用 .deb 安装，或注册成 Windows 服务。把它指向你想全天候盯着的网络即可。你现有的许可证就覆盖它：同一个密钥，不额外收费。

1.5.3 新功能：服务器内置本地 MCP 服务器——连接 Claude、Cursor 或任何 AI 代理，用自然语言询问你的网络。连接指南 →

安装步骤、告警、令牌设置和 MCP 连接示例都在服务器指南里。

服务器版通过 MQTT 把你的设备发布给 Home Assistant。Home Assistant 会自动发现它们，所以那边除了 MQTT 集成和一个 broker 之外不用装任何东西——不需要 add-on，也不需要自定义组件。

1. 确认 Home Assistant 里的 MQTT 集成已经连上你的 broker（Mosquitto add-on 可以，任何外部 broker 也可以）。
2. 在服务器控制台里打开设置 → 集成 → Home Assistant，填入 broker 地址（192.168.1.10:1883 就够了），如果你的 broker 需要认证再补上用户名和密码。
3. 勾选发布到 Home Assistant，然后点测试连接。实体会在一个扫描周期内出现。

每台导出的设备都会变成 Home Assistant 里的一台设备，带一个在线状态传感器以及 IP 和延迟，厂商、型号、类型、操作系统和开放端口则作为属性附在上面。旁边还有网络计数器和一个事件实体，会在出现新设备、设备离线以及新端口被打开时触发，于是自动化就能在陌生设备接入你网络时做出反应。

收藏的设备和基础设施（网关、路由器、交换机、AP、NAS、打印机）会自动发布。其他设备可以在各自的详情页里单独加入或排除。

路由器知道扫描发现不了的设备：休眠的手机、其他 VLAN 里的设备。DeviceShelf 可以直接从路由器读取客户端列表，桌面版、手机和服务器都可以。每一端都自己去问路由器，不经过我们的服务器。

1. 打开设置 → 路由器 / 控制器（桌面应用和服务器控制台），手机上是设置 → 路由器。
2. 选择路由器品牌，或者保留自动检测。如果路由器就是你的网关，地址留空即可。
3. 按品牌下方的提示填写。大多数家用路由器（FRITZ!Box、ASUS、Netgear、TP-Link 等）需要网页管理界面的密码；UniFi、pfSense、OPNsense、FortiGate 和 Omada 这类控制器通常需要 API 密钥。
4. 点测试连接，会显示哪个品牌做了应答、返回了多少台设备。

密码只保存在你的设备上（Mac 上是钥匙串，iPhone 和 Android 上是系统的安全存储，Windows 和 Linux 上是加密文件），也只会发给你的路由器。有些路由器在局域网里只支持未加密的 HTTP，这时网络里任何监听的人都能读到登录信息。

ASUS：DeviceShelf 会先尝试 HTTPS。如果连接测试提示使用的是未加密的 HTTP，请在路由器的 Administration → System → Local Access Config 中开启 HTTPS。

目前在真机上测试过的有 UniFi 和 Zyxel。其他品牌是按厂商公开的接口文档实现的。如果你的路由器没有按预期应答，给我们写信。

1. 购买后你会收到一封带许可证密钥的邮件。
2. 在应用里：设置 → 许可证，点粘贴并激活。或者自己粘贴密钥，再点激活。
3. iPhone 和 iPad 上没有密钥输入框：在设备上打开许可证邮件并点激活按钮，或先在桌面端激活，再用 iPhone 相机扫描其二维码（设置 → 许可证 → 在手机上激活）。Android 上同样可以，或者在“设置 → 许可证”中粘贴密钥。
4. 服务器版：在服务器仪表盘的设置 → 常规 → 许可证中粘贴同一个密钥，或在环境变量中设置 DEVICESHELF_LICENSE（Docker、.deb、Windows 服务）。

不用账户，也不联网校验——激活完全离线完成。同一个密钥也能激活你其余的设备。延伸阅读：激活 DeviceShelf。

没有这些权限应用照样能跑，只是对应的那个功能不启用。

扫描找不到设备，或几乎找不到

扫描器看到的是它所连接的网络。在访客 Wi-Fi、VLAN 或开启 VPN 时，扫描的是那个网段而不是你的主网络——这是列表几乎为空的最常见原因。在 macOS 上还要检查「系统设置 › 隐私与安全性 › 本地网络」：如果 DeviceShelf 未获允许，扫描将一无所获。另外请给它半分钟——在线设备几秒内出现，名称和识别随后跟上。

实时带宽为空或呈灰色

每设备带宽依赖抓包，需要额外权限：Windows 上是 Npcap，macOS/Linux 上是 sudo 或 BPF 访问。应用的其他功能无需这些即可使用。实时带宽页面按平台说明了设置步骤。

Windows 提示发布者未知

SmartScreen 会对未签名的安装程序显示此提示。点击 更多信息 → 仍要运行。每个版本旁都公布了下载文件的 SHA-256 校验和，你可以核对所运行的文件。

.deb 在 Ubuntu 上装不上

双击 .deb 会交给 Ubuntu 的 App Center 处理，而它可能悄无声息地失败。请改用终端安装：sudo apt install ./DeviceShelf-*.deb。详见 Linux 页面。

许可证无法激活

把购买邮件中的完整令牌粘贴到「设置 › 许可证」中，注意不要有换行。验证在离线状态下进行，防火墙不会造成阻碍。如果令牌被拒绝，请回复购买邮件，我们来解决。

macOS

1. 如果你设置过实时带宽：在 DeviceShelf 中打开带宽，点击移除 BPF 访问权限。系统会要求输入管理员密码，然后删除系统设置中显示为 DeviceShelf-Helper 的辅助程序。在 Mac 重新启动之前，系统设置中可能仍会显示该条目。
2. 退出 DeviceShelf，并将其从“应用程序”拖到废纸篓。“登录时打开”项会随应用一起消失。
3. 如需同时删除设备列表、设置和已保存的密码，请删除文件夹 ~/Library/Application Support/DeviceShelf。

旧版本会把已保存的密码存放在钥匙串中。如需一并删除，请打开“钥匙串访问”，搜索 DeviceShelf 并删除找到的条目。

应用已移到废纸篓，但之前设置过实时带宽？在终端中运行以下命令即可移除辅助程序：

sudo launchctl bootout system /Library/LaunchDaemons/app.deviceshelf.ChmodBPF.plist
sudo rm -f /Library/LaunchDaemons/app.deviceshelf.ChmodBPF.plist
sudo rm -rf "/Library/Application Support/DeviceShelf"
sudo chown root /dev/bpf*

Windows

1. 打开设置 → 应用 → 已安装的应用，找到 DeviceShelf 并选择卸载。
2. 设备列表和设置保留在 %AppData%\DeviceShelf 中。删除该文件夹即可一并移除。
3. Npcap 在同一列表中有单独的条目。只有在电脑上没有其他程序（例如 Wireshark）使用它时才移除。

Linux

1. AppImage：删除该文件。软件包：sudo apt remove deviceshelf（.deb）或 sudo dnf remove deviceshelf（.rpm）。
2. 设备列表和设置位于 ~/.config/DeviceShelf。删除该文件夹即可一并移除。

• 在 Linux 上安装
• 运行全天候服务器版
• 启用实时带宽
• 激活你的许可证
• 历史版本与回退
• 常见问题
• 还是卡住了？联系我们

• 查看网络中的每台设备并找到它的 IP 地址
• 谁在使用我的 Wi-Fi？查看每台设备
• 逐步保护你的家庭网络
• 开放端口到底意味着什么
• 找出网络中的物联网设备
• 为什么手机会显示随机 MAC 地址
• 在 Windows 上扫描网络
• 在 Linux 上扫描网络
• 自托管网络监控