# qdlocalshare

**Repository Path**: DragonCodingPlus/qdlocalshare

## Basic Information

- **Project Name**: qdlocalshare
- **Description**: windows 和 mac版本的DLocalShare，支持局域网多线程传文件。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DLocalShare - 局域网点对点文件传输工具

<div align="center">

![App Icon](ic_app_icon.png)

**快速、安全、无需服务器的本地文件传输解决方案**

[功能特性](#features) • [快速开始](#quick-start) • [技术架构](#architecture) • [构建指南](#building) • [协议说明](#protocol)

</div>

---

## 📖 简介

DLocalShare 是一款基于 Qt6/QML 开发的跨平台局域网文件传输应用，支持在 Wi-Fi 网络中的设备之间直接进行高速文件传输，无需任何中间服务器或互联网连接。

### 核心优势

- **零配置**: 自动发现局域网内的其他设备，无需手动输入 IP 地址
- **高速传输**: 采用多线程并行传输技术，充分利用 Wi-Fi 带宽
- **断点续传**: 支持传输中断后从断点继续，避免重复传输
- **隐私安全**: 纯本地运行，所有数据仅在局域网内传输
- **跨平台**: 支持 macOS、Windows 桌面平台

---

## ✨ 功能特性

### 设备发现
- 基于 UDP 多播协议的自动设备发现
- 实时显示在线设备列表
- 支持设备名称自定义和编辑
- 自动处理网络接口选择（Wi-Fi）

### 文件传输
- **并行传输**: 将文件分割为多个块，通过 3 个并行 TCP 连接同时传输
- **断点续传**: 传输中断后可从已完成的块继续，无需重新开始
- **进度可视化**: 实时显示整体进度和每个块的传输状态
- **速度监控**: 实时计算并显示传输速度
- **批量发送**: 支持一次选择多个文件发送给同一设备
- **取消与重试**: 可随时取消传输或重试失败的传输

### 用户体验
- **现代化界面**: 基于系统默认主题的简洁美观界面
- **国际化**: 支持中文和英文界面
- **保存位置自定义**: 可自定义文件保存目录

---

## 🚀 快速开始

### 系统要求

- **操作系统**: macOS 14.0+ / Windows 10
- **内存**: 最低 2GB RAM
- **网络**: Wi-Fi 网络连接（所有设备需在同一局域网内）
- **磁盘空间**: 至少 50MB 可用空间用于应用程序

### 安装

#### macOS
1. 下载 `DLocalShare_x.x.x.dmg` 文件
2. 双击 DMG 文件打开
3. 将 `DLocalShare.app` 拖拽到 `Applications` 文件夹
4. 首次运行时，在"系统偏好设置 > 安全性与隐私"中允许运行

#### Windows
1. 下载 `DLocalShare_x.x.x.zip` 安装包
2. 解压安装包，双击运行 `DLocalShare.exe`
3. 启动应用程序

### 使用方法

#### 接收文件
1. 确保您的设备已连接到 Wi-Fi 网络
2. 启动 DLocalShare 应用
3. 应用会自动进入等待接收状态
4. 当其他设备向您发送文件时，传输会自动开始
5. 文件默认保存到 `Downloads/LocalShare/` 目录

#### 发送文件

**方式一：从应用内发送**
1. 点击主界面右上角的设备列表图标
2. 选择要发送的文件
3. 从设备列表中选择目标设备
4. 点击"发送到 N 台设备"按钮

**方式二：系统分享菜单**
1. 在文件管理器中右键点击文件
2. 选择"分享"或"发送到"
3. 选择"DLocalShare"作为分享目标
4. 在弹出的设备列表中选择目标设备
5. 点击"发送"按钮

#### 管理传输
- **查看传输列表**: 点击主界面的"查看接收中 (N)"按钮
- **取消传输**: 在传输列表中点击删除图标，确认后即可取消
- **重试失败传输**: 对于失败的传输，点击重试图标即可重新发送

---

## 🏗️ 技术架构

### 概述

DLocalShare 采用双层架构设计，包含设备发现和文件传输两个独立子系统：

| 子系统 | 用途 | 传输协议 |
|--------|------|----------|
| **设备发现** | 在局域网中发现和通告设备 | UDP 多播 (IPv4) |
| **文件传输** | 在已发现设备间传输文件 | TCP (每文件多并发连接) |

### 设备发现协议 (LocalGroup)

基于自定义 UDP 多播协议实现：

- **多播地址**: `239.255.88.88`
- **端口**: `41575`
- **TTL**: `1` (仅限链路本地，不会被路由器转发)
- **最大数据包**: `4096` 字节

**帧格式** (UTF-8 JSON):
```json
{
  "type": "REGISTER",
  "deviceId": "uuid-string",
  "deviceName": "My Computer",
  "ipv4": "192.168.1.100",
  "port": 41576
}
```

**工作流程**:
1. 设备启动时广播 `REGISTER` 消息
2. 收到其他设备的 `REGISTER` 后回复 `ACK`
3. 设备离线时广播 `EXIT` 消息
4. 维护实时更新的在线设备列表

### 文件传输协议

采用基于块的并行传输机制：

**传输参数**:
- **线程数**: 3 (可配置)
- **连接超时**: 10 秒
- **读取超时**: 10 秒

**消息帧格式**:
```
[1 字节类型][4 字节大端序长度][N 字节载荷]
```

**消息类型**:
- `0x08` (`MSG_RESUME_INFO`): 断点续传信息
- `0x09` (`MSG_BLOCK_HEADER`): 块元数据头

**块分割算法**:
```
numThreads = 3
baseSize = fileSize / numThreads
remainder = fileSize % numThreads

对于每个块 i (0 到 numThreads-1):
  offset = i * baseSize + min(i, remainder)
  size = baseSize + (1 if i < remainder else 0)
```

这种分割方式确保文件大小均匀分布，各块大小差异不超过 1 字节。

**传输流程**:
```
发送方                              接收方
   │                                  │
   │──── TCP 连接 ───────────────────►│
   │                                  │
   │──── MSG_BLOCK_HEADER ──────────►│
   │     {块信息 JSON}                │
   │                                  │
   │◄─── MSG_RESUME_INFO ───────────│
   │     {transferId, blockIndex,    │
   │      receivedBytes}             │
   │                                  │
   │──── 原始块数据 ─────────────────►│
   │     (根据续传信息调整偏移量)      │
   │                                  │
   │──── TCP FIN ───────────────────►│
   │                                  │
```

### 断点续传机制

**预分配文件**:
- 接收方在传输开始前创建 `.temp` 临时文件，预分配完整文件大小
- 使用 `QFile::resize(fileSize)` 确保磁盘空间充足
- 允许多个并发连接随机写入不同位置

**元数据文件 (.meta)**:
```json
{
  "transferId": "uuid",
  "blockBytes": [1024000, 1024000, 512000]
}
```
- 记录每个块已接收的字节数
- 每秒最多写入一次，减少 I/O 开销
- 传输完成后自动删除

**崩溃恢复**:
- 接收方启动时检查 `.meta` 文件
- 恢复每个块的进度，只请求未完成的块
- 所有块完成后重命名 `.temp` 为最终文件名

### 数据模型

**TransferItem** (传输项):
```cpp
struct TransferItem {
    QString id;                  // UUID
    QString fileName;            // 文件名
    qint64 fileSize;             // 文件大小（字节）
    QString mimeType;            // MIME 类型
    TransferDirection direction; // SEND / RECEIVE
    TransferStatus status;       // PENDING / TRANSFERRING / COMPLETED / ERROR
    float progress;              // 进度 0.0 - 1.0
    qint64 transferredBytes;     // 已传输字节数
    int totalChunks;             // 总块数
    QSet<int> completedChunks;   // 已完成块索引
    QString targetDeviceName;    // 目标设备名称
    QString localFilePath;       // 本地文件路径
    QString errorMessage;        // 错误信息
    qint64 speedBytesPerSec;     // 传输速度（字节/秒）
};
```

---

## 💻 构建指南

### 依赖项

- **Qt 6.10+** (需要 Quick 和 Network 模块)
- **CMake 3.16+**
- **C++17 兼容编译器**

### macOS 构建

```bash
# 克隆仓库
git clone https://gitee.com/DragonCodingPlus/qdlocalshare.git
cd DLocalShare

# 运行构建脚本
chmod +x build_mac.sh
./build_mac.sh
```

构建产物位于 `build/mac-release/`:
- `DLocalShare.app` - 应用程序包
- `DLocalShare_x.x.x.dmg` - 可分发的 DMG 安装包

**自定义 Qt 路径**:
如果 Qt 安装在非标准位置，编辑 `build_mac.sh` 修改 `QT_DIR` 变量：
```bash
QT_DIR="/path/to/your/Qt/6.10.1/macos"
```

### Windows 构建

```powershell
# 在 PowerShell 中运行
.\build_windows.bat
```

### 项目结构

```
DLocalShare/
├── main.cpp                  # 应用程序入口点
├── Main.qml                  # 主 QML 界面
├── MainScreen.qml            # 主屏幕组件
├── TransferScreen.qml        # 传输列表屏幕
├── TransferCard.qml          # 传输卡片组件
├── TransferBlockBar.qml      # 块进度条组件
├── DeviceCard.qml            # 设备卡片组件
├── AboutDialog.qml           # 关于对话框
├── CMakeLists.txt            # CMake 构建配置
├── build_mac.sh              # macOS 构建脚本
├── build_windows.bat         # Windows 构建脚本
├── ic_app_icon.png           # 应用图标源文件
├── qrcode_weixin.webp        # 微信公众号二维码
├── i18n/                     # 国际化文件
│   └── app_zh.qm             # 中文翻译
└── src/                      # C++ 源代码
    ├── protocol.h/cpp        # 协议定义和序列化
    ├── deviceinfo.h          # 设备信息数据结构
    ├── blockinfo.h           # 块信息数据结构
    ├── transferitem.h/cpp    # 传输项数据模型
    ├── localgroupmanager.h/cpp  # 设备发现管理器
    ├── filesender.h/cpp      # 文件发送器
    ├── filereceiver.h/cpp    # 文件接收器
    ├── transfermanager.h/cpp # 传输管理器（编排层）
    ├── devicemodel.h/cpp     # 设备列表模型（QML 绑定）
    ├── transfermodel.h/cpp   # 传输列表模型（QML 绑定）
    └── fileutils.h/cpp       # 文件工具函数
```

---

## 🔐 权限说明

### Android (参考实现)

| 权限 | 用途 |
|------|------|
| `INTERNET` | TCP/UDP 套接字通信 |
| `ACCESS_WIFI_STATE` | 检测 Wi-Fi 状态 |
| `CHANGE_WIFI_MULTICAST_STATE` | 获取多播锁以进行 UDP 多播 |
| `WAKE_LOCK` | 传输期间防止 CPU 休眠 |

### 桌面平台等效要求

| 平台 | 网络权限 | 防火墙配置 |
|------|---------|-----------|
| **macOS** | 需要在 `Info.plist` 中声明网络访问 | 首次运行时系统会提示允许传入连接 |
| **Windows** | 无特殊权限要求 | 可能需要在 Windows 防火墙中允许应用 |

**注意**: 某些企业级 Wi-Fi 网络可能禁用了多播或限制了设备间通信。如果遇到设备无法发现的问题，请联系网络管理员确认多播和客户端隔离策略。

---

## 🌍 国际化

DLocalShare 目前支持以下语言：

- 🇨🇳 **简体中文** (zh-CN) - 默认语言（当系统语言为中文时）
- 🇺🇸 **英语** (en-US) - 默认语言（其他系统语言）


---

## 🤝 贡献指南

欢迎报告问题或提出建议！

### 提交问题
- 描述清楚的问题现象
- 提供复现步骤
- 附上系统环境和应用版本信息

---

## 📞 联系方式

- **开发者**: [DragonCoding](https://mjlong123.top)
- **产品主页**: [DLocalShare](https://mjlong123.top/products/dlocalshare)
- **问题反馈**: [Issues](https://gitee.com/DragonCodingPlus/qdlocalshare/issues)

---

<div align="center">

**Made with ❤️ by DragonCoding**

⭐ 如果这个项目对您有帮助，请给我们一个 Star！

</div>