# UDP-Discovery-Agent (局域网服务发现代理)

[![Go Version](https://img.shields.io/github/go-mod/go-version/rainlu/udp-discovery-agent?color=00ADD8)](https://golang.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

一个基于 Go 语言实现的轻量级、零配置成本的局域网服务自动寻址方案。专门为移动端（Android/iOS）在局域网环境下快速定位后端 API 服务而设计。

## 🚀 为什么需要它？
在局域网环境下（如家庭、办公室或工厂），后端开发机或服务器的 IP 地址通常由 DHCP 动态分配，经常变动。
*   **传统方案**：手动在 App 输入框里填 IP，效率低且用户体验差。
*   **本项目方案**：App 发送一个“暗号”广播，代理自动回传当前 IP 和端口。秒连，零配置。

## ✨ 核心特性
*   **智能健康检查**：代理会自动探测本地业务端口是否在线，只有服务正常才回复广播，避免误连。
*   **按请求来源选回包 IP**：在多网卡环境下，优先根据本次客户端请求的路由结果，返回实际应连接的本机 IP；失败时再回退到本地网卡扫描逻辑。
*   **极简部署**：单文件二进制运行，无外部依赖，配套 `config.yaml` 灵活管理。
*   **可扩展性**：支持一个代理同时管理多个不同版本的后端服务（Standard/Advanced/Beta）。

## 🛠️ 快速上手

### 1. 配置 `server/config.yaml`
```yaml
# 代理监听的 UDP 端口 (App 需向此端口发送广播)
server_port: 8888

# 服务映射表 (暗号 : 业务实际端口)
services:
  DISCOVER_STANDARD_EDITION: 8080
  DISCOVER_ADVANCED_EDITION: 9090
```

### 2. 构建与运行
```bash
# 进入目录
cd server

# 赋予执行权限
chmod +x build.sh

# 编译 (生成在 dist 目录下)
./build.sh

# 按平台启动
# Windows:
#   dist/NetworkAgent.exe
# macOS Apple Silicon:
#   ./dist/NetworkAgent_mac_arm
# macOS Intel:
#   ./dist/NetworkAgent_mac_intel
```

### 3. 通信协议 (简版)
1.  **移动端广播**：发送纯文本 `DISCOVER_STANDARD_EDITION` 到 `255.255.255.255:8888`。
2.  **服务端响应**：回传文本 `SERVER_IP:192.168.1.105:8080`。
3.  **当前版本说明**：服务端当前只返回一个自动选择出的 IP，不返回候选 IP 列表。

---

## 📱 移动端集成
详细的 Android (Kotlin) 和 iOS (Swift) 接入指南及状态机逻辑，请参考：
*   [移动端局域网服务发现（UDP）对接文档.md](./docs/移动端局域网服务发现（UDP）对接文档.md)

## ⚖️ 开源协议
本项目采用 [MIT License](LICENSE) 开源。
