# minitrans **Repository Path**: mossflower/minitrans ## Basic Information - **Project Name**: minitrans - **Description**: Minitrans 是一个基于 Rust 开发的轻量级局域网文件传输库,采用"取件码"设计模式。它允许用户在局域网内快速、安全地传输文件,无需复杂的配置或第三方服务。 - **Primary Language**: Rust - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-27 - **Last Updated**: 2026-04-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: Rust, LIBS ## README # Minitrans - 局域网文件传输库 ## 概述 Minitrans 是一个基于 Rust 开发的轻量级局域网文件传输库,采用"取件码"设计模式。它允许用户在局域网内快速、安全地传输文件,无需复杂的配置或第三方服务。 ## 特性 - **简单易用**:基于"取件码"设计,发送方生成取件码,接收方使用取件码接收文件 - **高效传输**:使用内存映射文件技术提高大文件传输效率 - **数据压缩**:支持 zstd 压缩算法,减少网络传输量 - **异步处理**:多线程设计,发送和接收过程不阻塞主线程 - **进度回调**:提供详细的传输进度回调机制 - **超时处理**:自动处理连接超时,避免资源泄漏 - **错误处理**:完善的错误处理机制,提供友好的错误信息 ## 系统要求 - Rust 1.70 或更高版本 - 支持 IPv4 网络环境 - 局域网内设备可互相访问 ## 安装 在 `Cargo.toml` 中添加依赖: ```toml [dependencies] minitrans = "0.3.0" ``` ## 核心概念 ### 取件码系统 取件码是一个 64 位整数,由发送方的 IP 地址和端口号编码生成。接收方使用这个取件码连接到发送方并接收文件。 ### 传输流程 1. 发送方启动服务并生成取件码 2. 发送方等待接收方连接 3. 接收方使用取件码连接到发送方 4. 文件传输开始 5. 传输完成,双方自动清理资源 ## 使用示例 ### 发送文件示例 ```rust use minitrans::Sender; use std::path::Path; fn main() -> Result<(), Box> { // 创建发送器 let mut sender = Sender::new("path/to/your/file.txt"); // 设置进度回调 sender.on_process(|progress| { match progress { minitrans::SendProgress::Listening(addr) => { println!("监听地址: {}", addr); } minitrans::SendProgress::Connected(addr) => { println!("已连接: {}", addr); } minitrans::SendProgress::Sending(total, sent) => { println!("发送进度: {}/{} ({:.2}%)", sent, total, (sent as f64 / total as f64) * 100.0); } minitrans::SendProgress::Finished => { println!("发送完成!"); } minitrans::SendProgress::Timeout => { println!("连接超时,无人接收文件"); } minitrans::SendProgress::Error(err) => { eprintln!("发送错误: {}", err); } _ => {} } }); // 启动发送服务,获取取件码 let code = sender.send()?; println!("取件码: {}", code); println!("文件名: {}", sender.get_filename()); // 等待发送完成 while !sender.is_finished() { std::thread::sleep(std::time::Duration::from_secs(1)); } Ok(()) } ``` ### 接收文件示例 ```rust use minitrans::Recipient; use std::path::Path; fn main() -> Result<(), Box> { // 取件码(从发送方获取) let pickup_code = 12345678901234567890; // 创建接收器,指定保存目录 let mut recipient = Recipient::new(pickup_code, "./downloads"); // 设置进度回调 recipient.on_process(|progress| { match progress { minitrans::ReceiveProgress::Connecting(addr) => { println!("正在连接到: {}", addr); } minitrans::ReceiveProgress::Receiving(total, received) => { println!("接收进度: {}/{} ({:.2}%)", received, total, (received as f64 / total as f64) * 100.0); } minitrans::ReceiveProgress::Writing(total, written) => { println!("写入进度: {}/{} ({:.2}%)", written, total, (written as f64 / total as f64) * 100.0); } minitrans::ReceiveProgress::Finished => { println!("接收完成!"); } minitrans::ReceiveProgress::Error(err) => { eprintln!("接收错误: {}", err); } _ => {} } }); // 开始接收文件 recipient.receive(); // 等待接收完成(在实际应用中,你可能需要更复杂的等待逻辑) std::thread::sleep(std::time::Duration::from_secs(30)); Ok(()) } ``` ### 错误处理最佳实践 ```rust use minitrans::{Recipient, Sender, TransErr}; fn send_file_with_error_handling() -> Result { let mut sender = Sender::new("important_document.pdf"); sender.on_process(|progress| { if let minitrans::SendProgress::Error(err) = progress { // 记录错误日志 eprintln!("传输错误: {}", err); // 获取详细的错误信息 if let Some(source) = err.get_source() { eprintln!("原始错误: {:?}", source); } } }); match sender.send() { Ok(code) => { println!("发送成功,取件码: {}", code); Ok(code) } Err(err) => { eprintln!("发送失败: {}", err.get_message()); Err(err) } } } fn receive_file_with_error_handling(code: u64) { let mut recipient = Recipient::new(code, "./downloads"); recipient.on_process(|progress| { if let minitrans::ReceiveProgress::Error(err) = progress { // 处理不同类型的错误 eprintln!("接收错误: {}", err); // 可以根据错误类型采取不同的恢复策略 if err.get_message().contains("无法连接到发送方") { eprintln!("网络连接失败,请检查网络和取件码"); } else if err.get_message().contains("写入文件失败") { eprintln!("磁盘写入失败,请检查磁盘空间和权限"); } } }); recipient.receive(); } ``` ## 限制和注意事项 1. **仅支持 IPv4**:当前版本不支持 IPv6 2. **局域网限制**:只能在局域网内使用,不支持跨互联网传输 3. **文件大小限制**:受系统内存限制,但通常可以处理数 GB 的文件 4. **并发限制**:一个发送器只能服务一个接收器 5. **超时设置**:发送方默认等待 1 小时,超时后自动关闭 ## 故障排除 ### 常见问题 1. **无法生成取件码** - 检查网络连接 - 确保有可用的本地 IP 地址 - 检查防火墙设置 2. **无法连接到发送方** - 验证取件码是否正确 - 检查发送方是否仍在运行 - 确保网络可达 3. **传输速度慢** - 检查网络带宽 - 考虑调整压缩级别 - 检查磁盘 I/O 性能 4. **传输中断** - 检查网络稳定性 - 确保有足够的磁盘空间 - 检查系统资源使用情况 ## 版本历史 ### v0.4.0 - 增加 `SendConfig` 相关设置 - 支持 ip 白名单 - 支持三种 `ReceiveMode`:只允许一人接收;多人依次接收;多人同时接收 ### v0.3.0 - 支持 zstd 压缩算法 - 性能优化 ### v0.2.0 - 增加 `Send::is_finished()` 方法 - 增加连接成功状态 `SendProgress::Connected` - 增加超时状态 `SendProgress::Timeout` - 超时后自动关闭发送线程 ### v0.1.1 - 修复 `TransErr` 无法获取 message 的问题 ### v0.1.0 - 初始版本发布 ## 许可证 本项目采用 MIT 许可证。详见 [LICENSE](minitrans/LICENSE) 文件。 ## 贡献指南 欢迎提交 Issue 和 Pull Request。在提交代码前,请确保: 1. 代码通过 Rust 格式化工具格式化 2. 添加相应的测试 3. 更新文档 ## 联系方式 如有问题或建议,请通过项目 Issue 页面提交。 --- **注意**:本库设计用于局域网内可信环境下的文件传输,不建议在公共网络或不受信任的环境中使用。