# FileSwap

**Repository Path**: shcao/file-swap

## Basic Information

- **Project Name**: FileSwap
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📡 局域网文件交换工具 (FileSwap)

一个基于 Python 的局域网文件与消息交换工具，支持设备自动发现、文字消息发送、文件传输和下载。通过浏览器访问 Web 界面操作，无需安装客户端。

---

## 📁 项目文件说明

### `app.py` — 主界面与应用入口

**作用：** 应用程序的入口文件和用户界面层。

**主要职责：**
- **构建 Web 界面：** 基于 Gradio 框架构建响应式 Web UI，包含设备列表、消息发送、文件下载等功能区域
- **事件处理：** 处理所有用户交互事件（点击按钮、选择设备、上传文件等）
- **定时轮询：** 每 2 秒自动刷新设备列表、消息记录和可下载文件列表
- **文件操作：** 提供下载文件到本地、打开文件所在文件夹、用系统默认程序打开文件等功能
- **跨平台支持：** 打开文件/文件夹功能兼容 Windows、macOS 和 Linux

**界面布局：**
```
┌─────────────────────────────────────────────────────┐
│              📡 局域网文件交换工具                      │
├────────────────┬────────────────────────────────────┤
│  📋 在线设备    │  ✉️ 发送消息/文件                     │
│  [设备表格]     │  [文字输入] [文件上传] [发送]          │
│  [选中设备]     │                                    │
│                │  📬 消息展示                          │
│  🔍 服务发现    │  [消息记录]                           │
│  🔄 刷新文件    │                                    │
│                │  📥 文件下载                          │
│  ⚙️ 配置       │  [文件下拉] [下载] [打开文件夹] [打开]  │
│  [本机IP]      │  [下载状态] [下载的文件]               │
│  [端口] [IP段]  │                                    │
│  [应用配置]     │                                    │
└────────────────┴────────────────────────────────────┘
```

---

### `network.py` — 网络通信模块

**作用：** 提供所有底层网络通信功能，是整个应用的核心引擎。

**主要职责：**
- **设备发现（UDP）：** 基于 UDP 广播协议在局域网内自动发现运行本工具的其他设备
- **心跳维护：** 每 30 秒广播一次心跳，维持设备在线状态；超过 90 秒未响应的设备自动移除
- **文字传输（TCP）：** 通过 TCP 连接发送和接收文字消息，保证可靠传输
- **文件传输（TCP）：** 通过 TCP 连接分块传输文件，支持大文件（最大 10GB）
- **文件缓存：** 接收的文件暂存在内存中（缓存上限 15GB），供用户选择下载

**通信协议设计：**
```
┌─────────────────────────────────────────────────────┐
│  协议层              端口           用途               │
├─────────────────────────────────────────────────────┤
│  UDP 服务发现     10900 (默认)    设备发现与心跳        │
│  TCP 数据传输     10901 (自动)    文字消息与文件传输     │
└─────────────────────────────────────────────────────┘

UDP 发现协议：
  设备A → UDP广播 → {"type":"discover","ip":"...","hostname":"..."}
  设备B → UDP回复 → {"type":"discover_reply","ip":"...","hostname":"..."}

TCP 传输协议：
  [JSON 头部]\n[二进制负载（仅文件类型有）]

  文字消息：{"type":"text","ip":"...","hostname":"...","content":"消息内容"}
  文件传输：{"type":"file","ip":"...","hostname":"...","filename":"文件名","filesize":字节数}
```

**线程模型：**
| 线程 | 功能 |
|------|------|
| `_udp_listener` | UDP 监听，接收发现请求和回复 |
| `_tcp_listener` | TCP 监听，接受连接并分发给处理线程 |
| `_heartbeat_loop` | 心跳循环，定期广播 + 清理过期设备 |
| `_delayed_discovery` | 延迟发现，启动 1 秒后执行首次扫描 |

**核心类：**
- `NetworkManager` — 网络管理器，负责设备发现、消息收发、文件传输和缓存管理
- `Device` — 设备数据类，记录已发现设备的 IP、主机名和最后心跳时间
- `ReceivedMessage` — 消息数据类，记录收到的文字/文件消息的详细信息

---

### `build.py` — 打包脚本

**作用：** 将整个项目打包为单个 `.exe` 可执行文件，方便分发。

**打包流程：**
1. 安装 `requirements.txt` 中的所有依赖
2. 收集 Gradio 及其依赖的静态资源（前端 HTML/CSS/JS 等）
3. 调用 PyInstaller 执行打包，处理隐式导入的 uvicorn 模块

**使用方式：**
```bash
python build.py
```

**输出：** `dist/FileSwap.exe`，双击即可运行，无需 Python 环境。

---

### `requirements.txt` — 依赖清单

**作用：** 列出项目运行所需的 Python 包及其最低版本。

| 依赖 | 版本要求 | 用途 |
|------|---------|------|
| `gradio` | >= 4.0.0 | Web UI 框架，构建浏览器界面 |
| `pyinstaller` | >= 6.0.0 | 打包工具（仅打包时需要） |

---

### `FileSwap.spec` — PyInstaller 打包配置

**作用：** PyInstaller 的打包配置文件，记录打包参数和资源收集规则。由 `build.py` 自动生成，也可手动编辑以微调打包行为。

---

## 🚀 快速开始

### 运行源码

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动应用
python app.py
```

启动后会自动打开浏览器访问 `http://localhost:7860`。

### 打包为可执行文件

```bash
python build.py
```

打包完成后，运行 `dist/FileSwap.exe` 即可。

---

## 📖 使用说明

1. **启动应用** — 运行 `python app.py`，浏览器自动打开
2. **配置网络** — 左栏"配置"区选择本机 IP，设置 IP 段前缀（默认 `192.168.31`），点击"应用配置"
3. **发现设备** — 点击"🔍 服务发现"扫描局域网，发现的设备会显示在"在线设备"表格中
4. **选择目标** — 点击设备表格中的某一行，选中目标设备
5. **发送消息** — 在右侧输入文字或上传文件，点击"📤 发送"
6. **接收文件** — 收到的文件会自动出现在"可下载文件"下拉框中（每 2 秒自动刷新）
7. **下载/打开文件** — 从下拉框选择文件，点击"💾 下载"、"📂 打开文件夹"或"📄 打开文件"

---

## ⚙️ 配置参数

| 参数 | 默认值 | 说明 |
|------|-------|------|
| UDP 端口 | 10900 | 服务发现端口，TCP 端口自动为 +1 |
| IP 段前缀 | 192.168.31 | 扫描范围为 x.1 ~ x.255 |
| 单文件上限 | 10 GB | `network.py` 中 `MAX_FILE_SIZE` |
| 缓存总上限 | 15 GB | `network.py` 中 `MAX_CACHE_SIZE` |
| 心跳间隔 | 30 秒 | `network.py` 中 `HEARTBEAT_INTERVAL` |
| 设备超时 | 90 秒 | `network.py` 中 `DEVICE_TIMEOUT` |
| Web 端口 | 7860 | Gradio Web 服务端口 |
| 轮询间隔 | 2 秒 | `app.py` 中 `POLL_INTERVAL` |

---

## 🏗️ 技术架构

```
┌──────────────────────────────────────────┐
│              浏览器 (Web UI)              │
│         Gradio 组件 · 事件驱动            │
└──────────────┬───────────────────────────┘
               │ HTTP (localhost:7860)
┌──────────────┴───────────────────────────┐
│              app.py (UI 层)              │
│   事件回调 · 定时轮询 · 文件操作           │
└──────────────┬───────────────────────────┘
               │ 函数调用
┌──────────────┴───────────────────────────┐
│           network.py (网络层)             │
│   UDP 发现 · TCP 传输 · 文件缓存          │
│   (多线程: UDP监听/TCP监听/心跳/延迟发现)   │
└──────────────────────────────────────────┘