方案简介

LAN Orangutan 是一款面向 homelab 用户的自托管网络发现工具，核心配方是「nmap 扫描引擎 + Go 单二进制 Web 服务 + Docker 宿主网络部署 + Tailscale 组网发现」。它扫描你的局域网，自动发现设备，并在一个干净的 Web 仪表盘或 CLI 中对设备打标签、分组、加备注和持续追踪。对于同时使用 Tailscale 的 homelabber，它还能在应用内连接、断开并发现 tailnet 中的 peer 节点。项目跨 Linux、macOS、Windows，发布为单二进制无依赖，也可用 Docker 容器化部署。

组成与分工

• nmap：核心扫描引擎，负责设备发现；配合 sudo 读取 ARP 表获取 MAC 地址与厂商信息
• Tailscale：组网集成对象，在应用内发现 tailnet peers 并可连接/断开
• Docker / Docker Compose：容器化部署方式，使用 host networking 接入真实局域网
• Web 仪表盘：实时设备状态、分组、搜索过滤、CSV/JSON 导出
• CLI（orangutan）：扫描、列表、导出、配置管理等命令行操作，支持 JSON 输出

前置要求

• nmap 必须安装：

macOS：
bash
brew install nmap

Ubuntu/Debian：
bash
sudo apt install nmap

Windows：从 nmap.org 下载。

Docker 部署需 Linux；macOS/Windows 请直接运行二进制。

实施步骤

1. 下载

从 GitHub Releases 获取对应平台的最新版本。

2. 或使用 Docker 部署（仅 Linux）

拉取镜像：
bash
docker pull 291group/lan-orangutan

或使用 compose 文件获得带 host networking 和持久化数据目录的完整部署：
bash
curl -O https://raw.githubusercontent.com/291-Group/LAN-Orangutan/main/docker-compose.yml
docker compose up -d

3. 运行

bash

Linux/macOS - Run with sudo for full device info (MAC addresses, vendors)

sudo ./orangutan serve

Windows (run as Administrator for full device info)

orangutan.exe serve

4. 初始化

打开 http://localhost:291，首次访问会要求创建密码，创建前其他功能不可访问。

使用与配置要点

扫描：
bash
sudo orangutan scan # Scan default network
sudo orangutan scan 192.168.1.0/24 # Scan specific network
sudo orangutan scan all # Scan all detected networks

启动 Web 服务：
bash
sudo orangutan serve # Default port 291
sudo orangutan serve --port 8080 # Custom port
sudo orangutan serve --bind 127.0.0.1 # This machine only, no password needed

设备管理与导出：
bash
orangutan list --format # JSON output
orangutan export devices.csv # Export to CSV
orangutan status # Show system status

Web 仪表盘提供实时在线状态、设备分组（Server、Desktop、IoT 等）、标签备注、搜索过滤与导出。

注意事项与常见问题

• Docker 需要 Linux：容器使用 host networking，否则只能看到其他容器（172.17.0.0/16）而非局域网设备。
• Docker Desktop（macOS/Windows）不支持：虚拟机网关会代替不存在的地址应答探测，扫描结果看似成功实则虚假；项目会检测该情况并在仪表盘给出警告。
• 权限：无 sudo 时仍能看到设备 IP，但 MAC 地址与厂商信息缺失。
• 从旧版 Python+PHP 版本升级时，配置和设备列表（/etc/lan-orangutan、/var/lib/lan-orangutan）会保留，PHP/Python 不再需要。

优缺点

• ✓ 单二进制零依赖部署
• ✓ Web UI 与 CLI 双模式
• ✕ Docker 需 Linux host
• ✕ 无 sudo 丢失 MAC 厂商信息

出处

本方案挖掘自开源项目 291-Group/LAN-Orangutan，方案内容与实施命令均来自其 README 原文。