pyLink - 跨局域网大文件传输工具

pyLink 是一个基于 Python 的跨局域网大文件传输工具，利用 WebRTC 技术实现内网穿透，无需依赖专用服务器即可在不同网络环境下（如家庭、公司、公共网络等）安全地传输大文件。

功能特性

• 跨局域网传输：利用 WebRTC 技术实现内网穿透，无需配置路由器端口映射
• 大文件支持：优化的文件分块传输机制，支持 1GB 以上的大文件传输
• 断点续传：网络中断后可从断点处继续传输，避免重新开始
• 进度反馈：实时显示文件传输进度
• 数据加密：支持端到端加密（AES-256-GCM）和 WebRTC 自带的 DTLS 加密
• 跨平台：支持 Windows、macOS 和 Linux 等主流操作系统
• 测试模式：新增测试模式，可在同一进程中模拟发送方和接收方的文件传输流程，便于开发和调试

技术栈

• Python 3.8+：主要开发语言
• WebRTC (aiortc)：实现内网穿透和 P2P 连接
• 异步编程 (asyncio)：提供高性能的网络通信
• 加密 (cryptography, pynacl)：确保数据传输安全

安装方法

前提条件

• Python 3.8 或更高版本
• pip 包管理器

步骤

1. 克隆或下载项目代码到本地

2. 进入项目目录

   cd pyLink

3. 创建并激活虚拟环境（推荐）

   # Windows
   python -m venv .venv
   .venv\Scripts\activate
   
   # macOS/Linux
   python3 -m venv .venv
   source .venv/bin/activate

4. 安装依赖包

   pip install -r requirements.txt

使用方法

pyLink 提供了三种运行模式：发送方模式（send）、接收方模式（receive）和测试模式（test）。传输文件时，需要在两台设备上分别运行发送方和接收方模式；开发测试时，可以使用测试模式在同一进程中模拟完整的传输流程。

发送文件（发送方）

1. 在要发送文件的设备上，运行以下命令：

   python src/main.py send -f "path/to/your/file.ext"

   可选参数：

   • -k KEY 或 --key KEY：设置加密密钥（建议使用，增强安全性）
   • -v 或 --verbose：显示详细日志

2. 程序会生成一个连接信息（JSON 格式），请将此信息发送给接收方

3. 等待接收方连接并接收文件

接收文件（接收方）

1. 在要接收文件的设备上，运行以下命令：

   python src/main.py receive

   可选参数：

   • -k KEY 或 --key KEY：设置解密密钥（必须与发送方使用的密钥相同）
   • -v 或 --verbose：显示详细日志

2. 输入发送方提供的连接信息

3. 程序会生成一个应答信息，请将此信息发送给发送方

4. 等待连接建立并接收文件

5. 接收的文件将保存在 downloads 目录中

测试模式

测试模式允许在同一进程中模拟发送方和接收方的完整文件传输流程，主要用于开发和调试。

1. 运行以下命令启动测试模式：

   python src/main.py test -f "path/to/test/file.ext"

   可选参数：

   • -k KEY 或 --key KEY：设置加密密钥
   • -v 或 --verbose：显示详细日志

2. 程序会在同一进程中创建发送方和接收方实例，并自动模拟连接建立、文件传输的完整过程

3. 测试完成后，程序会显示传输结果，测试文件将保存在 downloads 目录中

注意事项

• 对于某些严格的网络环境（如企业防火墙、NAT类型为对称型），可能需要配置 TURN 服务器。请在 config/config.yaml 文件中修改 ice_servers 配置。
• 传输大文件时，建议使用高性能的 Wi-Fi 或有线网络连接，以获得最佳传输速度。
• 为确保数据安全，强烈建议使用加密密钥（-k 参数）。
• 程序已修复发送方处理传输完成文件时可能出现的"处理传输完成的文件失败: 'temp_file_path'"错误，提高了传输稳定性。

配置文件

项目的配置文件位于 config/config.yaml，您可以根据需要修改以下配置项：

• network：网络相关配置（端口范围、缓冲区大小、超时时间、ICE服务器等）
• file_transfer：文件传输相关配置（分块大小、并发传输的块数、临时文件目录、下载目录等）
• security：安全相关配置（加密算法、密钥长度、是否启用 DTLS 加密、是否启用端到端加密等）
• logging：日志相关配置（日志级别、日志格式、日志文件等）

故障排除

• 连接超时：检查网络连接是否正常，可能需要配置 TURN 服务器
• 文件传输中断：重新运行程序并使用相同的文件，将自动启用断点续传功能
• 加密错误：确保发送方和接收方使用相同的加密密钥
• 文件传输完成错误：程序已修复发送方处理传输完成文件时的 'temp_file_path' 相关错误

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

免责声明

本工具仅供学习和个人使用，对于使用本工具造成的任何损失，作者不承担任何责任。