# pi-discovery

**Repository Path**: dgjames/pi-discovery

## Basic Information

- **Project Name**: pi-discovery
- **Description**: Raspberry Pi IP/mDNS discovery tool for LAN
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 树莓派发现工具

> [English](README.md) | 中文

在局域网里找到你的树莓派，再也不用到处翻 IP 地址了。

两个互补的组件：

| 组件 | 运行位置 | 作用 |
|---|---|---|
| `raspberry-pi-discovery-server.py` | 树莓派（systemd 自启） | HTTP 服务，报告树莓派的 IP 和 mDNS 名称 |
| `find-pi.py` | Windows / Linux / macOS | 局域网扫描器 + mDNS 反向解析客户端 |

加上 `avahi-daemon` 在网络上把树莓派注册成 `<hostname>.local`，SSH 直接按名字连，开箱即用。

---

## 特性

- **mDNS** — 树莓派自动声明自己是 `raspberrypi.local`，SSH 和 HTTP 都能按名字访问
- **HTTP 发现** — `GET /ip` 以 JSON 格式返回 hostname、IP、mDNS 名称、SSH 命令
- **局域网扫描** — `find-pi.py` 扫描 `/24` 网段，找到的每个树莓派都会报告，并反向解析 `.local` 域名
- **一键安装** — `install-service.sh install` 一次性搞定 avahi + systemd
- **零外部依赖** — 只用 Python 3 标准库

---

## 快速开始

### 在树莓派上

```bash
git clone https://gitee.com/dgjames/pi-discovery.git
cd pi-discovery
sudo bash install-service.sh install
```

搞定。现在树莓派会响应以下访问：

- `ssh pi@raspberrypi.local`
- `http://raspberrypi.local:8080/ip`（JSON）
- `http://raspberrypi.local:8080/`（HTML 状态页）
- `http://raspberrypi.local:8080/all`（所有网卡 IP）

### 在 Windows 上

```powershell
# 让 Windows 能解析 .local 名字（一次性）
# 安装 Bonjour：装 iTunes 时会带上，或者
Add-WindowsCapability -Online -Name "Bonjour.PrintServices~~~~0.0.1.0"

# 然后任选一种：
ssh pi@raspberrypi.local

# 或者扫描：
python find-pi.py
```

`find-pi.py` 是只读的 —— 它只是向 8080 端口发 HTTP GET 请求，并反向解析 IP。

---

## HTTP API

| 接口 | 返回内容 |
|---|---|
| `GET /ip` | `{"hostname": "raspberrypi", "ip": "192.168.1.42", "port": 8080, "mdns": "raspberrypi.local", "message": "ssh pi@raspberrypi.local"}` |
| `GET /all` | 所有网卡的 IP |
| `GET /` | HTML 状态页 |

CORS 完全开放（`Access-Control-Allow-Origin: *`），所以任何设备的浏览器都能直接调用这个 API。

---

## 安装细节

`install-service.sh install` 做三件事：

1. 安装 `avahi-daemon`，配置它广播 `_ssh._tcp` 和 `_http._tcp` 服务
2. 写入 `/etc/hostname` 和 `/etc/hosts`，让树莓派的名字是 `raspberrypi`
3. 放置 systemd 单元文件（`pi-discovery.service`），在 8080 端口跑 HTTP 服务，崩溃自动重启，开机自启

### 自定义 hostname / 端口

```bash
sudo bash install-service.sh install --hostname pi-nas --port 9090
```

装好以后，编辑 `/etc/default/pi-discovery` 然后重启服务就能改配置，不用重跑安装脚本。

### 服务端配置优先级

服务端按下面的顺序决定 hostname 和端口（高优先级优先）：

1. 命令行参数：`--hostname NAME --port N --bind ADDR`
2. 环境变量：`PI_DISCOVERY_HOSTNAME`、`PI_DISCOVERY_PORT`、`PI_DISCOVERY_BIND`
3. 配置文件：`~/.pi-discovery.json`（JSON，例如 `{"hostname": "mypi", "port": 9090}`）
4. 兜底：系统 hostname，端口 8080

服务管理：

```bash
sudo systemctl status pi-discovery
sudo systemctl restart pi-discovery
sudo journalctl -u pi-discovery -f
```

卸载：

```bash
sudo bash install-service.sh uninstall
```

---

## 环境要求

- Raspberry Pi OS（基于 Debian），Python 3.7+
- Windows 扫描端需要 Python 3.7+（不需要 pip 包）
- 防火墙放行 8080/TCP（家庭局域网默认就是开放的）
- mDNS：树莓派装 `avahi-daemon`，Windows 装 Bonjour

---

## Windows 乱码问题排查

如果 `ssh pi@raspberrypi.local` 报错时显示乱码（`\262\273\326\252...`），这是 Windows 终端的 GBK 解码问题，不是这个项目的问题。`find-pi.py` 启动时会自动调用 `chcp 65001` 切到 UTF-8，所以扫描器不会乱码。

**根本原因**：Windows 的 PowerShell / cmd 默认用 GBK 解码 UTF-8 输出，OpenSSH 客户端的中文/特殊字符错误信息就被显示成乱码了。修复方法：

```powershell
# 临时切到 UTF-8
chcp 65001

# 永久切：Windows 10 1903+
# 设置 -> 时间和语言 -> 语言 -> 管理语言设置 -> 更改系统区域设置 -> 勾选 "Beta: 使用 Unicode UTF-8 提供全球语言支持"
```

---

## 许可证

MIT