# FileTransfer
**Repository Path**: sky0535/FileTransfer
## Basic Information
- **Project Name**: FileTransfer
- **Description**: 实现文件的断点续传
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-07
- **Last Updated**: 2025-07-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 文件传输系统
这是一个支持断点续传的文件传输系统，包含服务端、客户端和公共类库三个部分。
## 项目结构
```
FileTransfer/
├── FileServer/ # 服务端项目 (ASP.NET Core Web API)
│ ├── Controllers/ # API控制器
│ │ └── FileController.cs # 文件操作控制器
│ ├── Models/ # 服务端模型
│ │ └── UploadMessage.cs # 上传消息模型
│ ├── Files/ # 文件存储目录
│ ├── wwwroot/ # 静态文件
│ │ ├── index.html # Web界面主页面
│ │ ├── styles/ # CSS样式文件
│ │ │ └── index.css # 主样式文件
│ │ └── scripts/ # JavaScript脚本文件
│ │ └── index.js # 主脚本文件
│ ├── Properties/ # 项目属性
│ ├── bin/ # 编译输出目录
│ ├── obj/ # 临时编译文件
│ ├── appsettings.json # 配置文件
│ ├── appsettings.Development.json # 开发环境配置
│ ├── FileServer.csproj # 项目文件
│ ├── FileServer.csproj.user # 用户项目文件
│ ├── FileServer.http # HTTP测试文件
│ ├── Program.cs # 程序入口
│ └── Logs/ # 日志文件目录
│ ├── *.log # 生产环境日志文件
│ └── debug-*.log # 开发环境日志文件
├── FileClient/ # 客户端项目 (.NET Windows Forms)
│ ├── Models/ # 客户端模型
│ │ ├── DownloadTask.cs # 下载任务模型
│ │ └── ProgressEventArgs.cs # 进度事件参数
│ ├── Utils/ # 工具类
│ │ └── FileDownloadService.cs # 文件下载服务
│ ├── bin/ # 编译输出目录
│ ├── obj/ # 临时编译文件
│ ├── MainForm.cs # 主窗体
│ ├── MainForm.Designer.cs # 窗体设计器
│ ├── MainForm.resx # 窗体资源
│ ├── App.ico # 应用图标
│ ├── FileClient.csproj # 项目文件
│ ├── FileClient.csproj.user # 用户项目文件
│ ├── Program.cs # 程序入口
│ └── NLog.config # NLog日志配置文件
├── Common/ # 公共类库项目
│ ├── Models/ # 共享模型
│ │ └── FileData.cs # 文件数据模型
│ ├── Utils/ # 工具类
│ │ └── ConfigHelper.cs # 配置助手
│ ├── bin/ # 编译输出目录
│ ├── obj/ # 临时编译文件
│ └── Common.csproj # 项目文件
├── .git/ # Git版本控制目录
├── .vs/ # Visual Studio配置目录
├── .gitignore # Git忽略文件
├── FileTransfer.sln # 解决方案文件
├── LICENSE # 许可证文件
└── README.md # 项目说明文档
```
## 功能特性
### 服务端 (FileServer)
- ✅ 文件列表获取 - 获取服务器Files目录下的所有文件信息
- ✅ 文件信息查询 - 查询指定文件的详细信息（大小、修改时间等）
- ✅ 支持断点续传的文件下载 - 通过HTTP Range请求实现断点续传
- ✅ 文件上传功能 - 支持大文件上传（最大10GB）
- ✅ 文件删除功能 - 支持删除服务器上的文件
- ✅ 静态文件服务 - 提供Web界面上传文件
- ✅ Web界面功能 - 支持拖拽上传、实时进度显示、文件列表管理
- ✅ 大文件支持 - 最大支持10GB文件传输
- ✅ 超时配置 - 可配置的请求超时时间
- ✅ 错误处理 - 完善的异常处理和日志记录
- ✅ 日志系统 - 支持文件日志和控制台日志输出
- ✅ CORS支持 - 跨域资源共享配置
- ✅ 请求限制配置 - 支持大文件上传的请求体大小限制
### 客户端 (FileClient)
- ✅ 图形化用户界面 - Windows Forms界面，操作简单直观
- ✅ 文件列表浏览 - 实时获取并显示服务器文件列表
- ✅ 多文件同时下载 - 支持并发下载多个文件
- ✅ 实时下载进度显示 - 显示当前下载进度百分比
- ✅ 下载速度显示 - 实时显示下载速度（平滑计算）
- ✅ 剩余时间估算 - 基于当前速度估算剩余下载时间
- ✅ 断点续传支持 - 网络中断后可从断点继续下载
- ✅ 下载任务管理 - 管理多个下载任务的状态
- ✅ 暂停/继续下载 - 支持暂停和继续下载操作
- ✅ 取消下载功能 - 支持随时取消正在进行的下载
- ✅ 临时文件管理 - 自动清理下载过程中的临时文件
- ✅ 按钮状态管理 - 根据下载任务状态智能启用/禁用按钮
- ✅ 窗体关闭处理 - 关闭时自动取消所有下载任务并释放资源
### 公共类库 (Common)
- ✅ 共享数据模型 - FileData模型在服务端和客户端间共享
- ✅ 配置助手 - ConfigHelper提供统一的配置常量
- ✅ 跨项目类型定义 - 确保服务端和客户端使用相同的数据结构
- ✅ 缓冲区配置 - 统一的缓冲区大小和超时配置
- ✅ 网络配置 - 统一的网络连接和重试配置
## 技术栈
- **服务端**: ASP.NET Core 8.0 Web API
- **客户端**: .NET 8.0 Windows Forms
- **公共类库**: .NET 8.0 Class Library
- **Web界面**: HTML5 + CSS3 + JavaScript (ES6+)
- **通信**: HTTP REST API
- **断点续传**: HTTP Range 请求头
- **序列化**: System.Text.Json
- **文件操作**: System.IO.FileStream
- **异步编程**: async/await 模式
- **事件驱动**: C# 事件机制
- **项目架构**: 三层架构（服务端、客户端、公共类库）
- **配置管理**: IConfiguration 依赖注入
- **日志记录**: Serilog + ILogger 接口
- **前端技术**: XMLHttpRequest (进度监控), Fetch API, CSS3 动画
- **UI框架**: Windows Forms (.NET 8.0)
- **依赖注入**: Microsoft.Extensions.DependencyInjection
## 快速开始
### 1. 启动服务端
```bash
cd FileServer
dotnet run
```
服务端将在 `http://localhost:5000` 启动。
### 2. 启动客户端
```bash
cd FileClient
dotnet run
```
### 3. 使用Web界面
访问 `http://localhost:5000` 可以使用Web界面上传文件。
**Web界面特性：**
- 🎯 **拖拽上传** - 支持将文件直接拖拽到上传区域
- 📊 **实时进度** - 显示上传进度条和百分比
- 📁 **文件管理** - 实时显示服务器文件列表
- 🎨 **现代界面** - 美观的响应式设计
- ⚡ **快速下载** - 一键下载服务器文件
- 🗑️ **文件删除** - 支持删除服务器文件（带确认对话框）
### 4. 项目依赖关系
- **FileServer** 依赖 **Common** 项目
- **FileClient** 依赖 **Common** 项目
- **Common** 是独立的类库项目，不依赖其他项目
## API接口
### 获取文件列表
```
GET /api/file/list
```
### 获取文件信息
```
GET /api/file/info/{fileName}
```
### 下载文件（支持断点续传）
```
GET /api/file/download/{fileName}
Headers: Range: bytes=start-end
```
### 上传文件
```
POST /api/file/upload
Content-Type: multipart/form-data
```
### 删除文件
```
DELETE /api/file/delete/{fileName}
```
## 断点续传机制
### 服务端实现 (FileController.cs)
1. **解析Range请求头**: 解析 `Range: bytes=start-end` 格式的请求头
2. **验证请求范围**: 检查start和end值是否在文件大小范围内
3. **设置响应头**:
- `Accept-Ranges: bytes` - 表明支持Range请求
- `Content-Range: bytes start-end/total` - 指定返回的内容范围
- `Content-Length: length` - 返回内容的大小
4. **状态码处理**:
- 206 Partial Content - 部分内容响应
- 200 OK - 完整文件响应
5. **文件流定位**: 使用 `FileStream.Seek()` 定位到指定位置
6. **流式传输**: 从指定位置开始传输文件内容
### 客户端实现 (FileDownloadService.cs)
1. **断点信息管理**:
- 使用 `.resume` 文件保存断点位置
- 使用 `.tmp` 文件保存下载中的文件
2. **断点检测**: 启动时检查是否存在未完成的下载
3. **Range请求**: 使用 `TryAddWithoutValidation` 安全设置 `Range` 请求头
4. **响应头验证**: 安全获取和验证 `Content-Range` 响应头
5. **文件流定位**: 使用 `FileStream.Seek()` 定位到断点位置
6. **进度监控**: 实时计算下载速度和剩余时间
7. **平滑速度计算**: 使用加权平均算法平滑速度显示
8. **异常处理**: 网络中断时保存断点信息，支持自动重试
9. **清理机制**: 下载完成后删除临时文件
10. **连接稳定性**: 优化的HttpClient配置，提高连接稳定性
## 配置说明
### 服务端配置 (appsettings.json)
```json
{
"Serilog": {
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"System": "Warning"
}
},
"WriteTo": [
{
"Name": "Console"
},
{
"Name": "File",
"Args": {
"path": "Logs/{Date:yyyy-MM-dd}.log",
"rollingInterval": "Day",
"fileSizeLimitBytes": 10485760,
"retainedFileCountLimit": 30,
"rollOnFileSizeLimit": true,
"shared": true,
"flushToDiskInterval": "00:00:01"
}
}
]
},
"AllowedHosts": "*",
"FileDirectory": "Files" // 文件存储目录
}
```
### 开发环境配置 (appsettings.Development.json)
```json
{
"Serilog": {
"MinimumLevel": {
"Default": "Debug",
"Override": {
"Microsoft": "Information",
"System": "Information"
}
},
"WriteTo": [
{
"Name": "Console",
"Args": {
"outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}"
}
},
{
"Name": "File",
"Args": {
"path": "Logs/debug-{Date:yyyy-MM-dd}.log",
"rollingInterval": "Day",
"fileSizeLimitBytes": 10485760,
"retainedFileCountLimit": 30,
"rollOnFileSizeLimit": true,
"shared": true,
"flushToDiskInterval": "00:00:01"
}
}
]
}
}
```
### 公共配置 (ConfigHelper.cs)
```csharp
public static class ConfigHelper
{
public const long MaxFileSize = 10_737_418_240; // 10GB
public static TimeSpan MaxTimeout = TimeSpan.FromHours(2); // 2小时
public static int BufferSize = 512 * 1024; // 512KB
public static long MaxRequestBufferSize = 8 * 1024 * 1024; // 8MB
public static long MaxResponseBufferSize = 8 * 1024 * 1024; // 8MB
public static int MaxRetries = 3; // 最大重试次数
public static TimeSpan RetryDelay = TimeSpan.FromSeconds(5); // 重试延迟
public static TimeSpan KeepAliveTimeout = TimeSpan.FromMinutes(5); // 连接保持时间
public static int MaxConnections = 100; // 最大连接数
}
```
### 客户端配置
- 下载目录：`[程序所在目录]\Downloads`
- 服务器地址：默认 `http://localhost:5000`
- 按钮状态管理：根据下载任务列表自动启用/禁用暂停和取消按钮
## 使用说明
### 服务端
1. 运行服务端程序
2. 将文件放入 `Files` 目录
3. 或使用Web界面上传文件
4. 查看日志文件：`FileServer/Logs/*.log` (生产环境) 或 `FileServer/Logs/debug-*.log` (开发环境)
### 客户端
1. 运行客户端程序
2. 输入服务器地址并连接
3. 选择要下载的文件
4. 查看下载进度
5. 支持暂停/继续下载和取消下载
6. 按钮状态会根据下载任务自动调整
### Web界面
1. **访问界面**: 在浏览器中访问 `http://localhost:5000`
2. **上传文件**:
- 拖拽文件到上传区域
- 或点击"选择文件"按钮选择文件
3. **查看进度**: 上传过程中会显示实时进度条和百分比
4. **管理文件**: 页面下方显示服务器所有文件列表
5. **下载文件**: 点击文件列表中的"下载"按钮下载文件
6. **删除文件**: 点击文件列表中的"删除"按钮删除文件（需要确认）
## 特性优势
1. **断点续传**: 网络中断后可从断点继续下载
2. **多任务下载**: 支持同时下载多个文件
3. **实时进度**: 显示下载进度、速度和剩余时间
4. **用户友好**: 图形化界面，操作简单
5. **稳定可靠**: 完善的错误处理和异常恢复
6. **跨平台**: 服务端支持多平台，客户端支持Windows
7. **模块化设计**: 公共类库提供共享模型，便于维护和扩展
8. **代码复用**: 服务端和客户端共享相同的数据结构定义
9. **Web界面**: 现代化的Web界面上传体验
10. **拖拽上传**: 直观的文件拖拽上传功能
11. **实时反馈**: 上传进度条和状态提示
12. **响应式设计**: 适配不同屏幕尺寸的界面
13. **智能UI**: 按钮状态根据任务状态自动调整
14. **资源管理**: 窗体关闭时自动清理资源
## 注意事项
1. **磁盘空间**: 确保服务端有足够的磁盘空间存储文件（最大支持10GB单个文件）
2. **网络连接**: 大文件下载时建议使用有线网络连接，避免WiFi不稳定导致频繁断点续传
3. **权限要求**:
- 服务端Files目录需要有读写权限
- 客户端下载目录需要有写入权限
4. **配置调整**:
- 最大文件大小可在 `Common/Utils/ConfigHelper.cs` 中调整 `MaxFileSize`
- 缓冲区大小可在 `ConfigHelper.cs` 中调整 `BufferSize`
- 超时时间可在 `ConfigHelper.cs` 中调整 `MaxTimeout`
- 重试次数可在 `ConfigHelper.cs` 中调整 `MaxRetries`
5. **临时文件**: 下载过程中会在下载目录生成 `.tmp` 和 `.resume` 文件，请勿手动删除
6. **并发限制**: 客户端支持多文件同时下载，但建议控制并发数量避免服务器压力过大
7. **断点续传**: 系统支持自动重试和断点续传，网络中断后会自动从断点继续下载
8. **错误处理**: 完善的错误处理机制，包括连接超时、文件不完整等情况的自动恢复
9. **Web界面**:
- 支持现代浏览器（Chrome、Firefox、Safari、Edge）
- 文件上传支持拖拽和点击选择两种方式
- 上传进度实时显示，支持大文件上传
- 文件列表自动刷新，显示最新上传的文件
10. **前端文件**: CSS和JavaScript文件已分离到独立目录，便于维护和扩展
11. **日志管理**: 支持按日期滚动的日志文件，自动清理旧日志
12. **日志监控**: 可通过日志文件监控系统运行状态和排查问题
13. **日志配置**: 日志设置完全通过配置文件管理，支持不同环境的差异化配置
14. **窗体事件**: 客户端窗体关闭时会自动取消所有下载任务并释放资源
## 开发环境
- Visual Studio 2022 或 VS Code
- .NET 8.0 SDK
- Windows 10/11 (客户端)
- 现代浏览器 (Web界面开发)
## 日志系统
### 服务端日志配置
项目使用 Serilog 作为日志框架，支持同时输出到控制台和文件。所有日志配置都从 `appsettings.json` 和 `appsettings.Development.json` 文件中读取，支持环境特定的配置。
**配置说明**：
- 使用统一的 Serilog 配置，避免与传统 Logging 配置冲突
- 支持环境变量覆盖配置
- 配置文件支持热重载（修改后重启生效）
- 日志文件命名策略：
- 生产环境：使用纯日期格式 `{yyyy-MM-dd}.log`，简洁明了
- 开发环境：使用 `debug-{yyyy-MM-dd}.log` 格式，便于区分
### 客户端日志配置
客户端使用 NLog 作为日志系统，日志配置文件为 `FileClient/NLog.config`，支持异步写入、日志文件按天分割、自动归档和控制台输出。
**NLog 配置说明**：
- 日志文件路径：`FileClient/Logs/{yyyy-MM-dd}.log`
- 归档目录：`FileClient/Logs/archives/`
- 滚动策略：每天创建新文件，最多保留30天归档
- 同时输出到控制台和文件，便于开发调试
- 配置文件可自定义日志格式和归档策略
**日志目录结构示例**：
```
FileClient/Logs/
├── 2024-01-15.log # 日志文件
├── 2024-01-16.log
└── archives/
├── 1.log
├── 2.log
└── ...
```
**NLog.config 示例片段**：
```xml
```
### 日志文件
- **生产环境**: `FileServer/Logs/{yyyy-MM-dd}.log` (例如: 2024-01-15.log)
- **开发环境**: `FileServer/Logs/debug-{yyyy-MM-dd}.log` (例如: debug-2024-01-15.log)
- **滚动策略**: 按日期滚动，每天创建新文件
- **文件大小限制**: 10MB
- **保留策略**: 保留最近30天的日志文件
- **日志级别**:
- 生产环境: Information (默认), Warning (Microsoft/System)
- 开发环境: Debug (默认), Information (Microsoft/System)
### 日志内容
- 服务器启动和关闭信息
- 文件上传/下载操作记录
- 错误和异常信息
- 性能监控数据
- API请求响应日志
### 日志示例
```
[2024-01-15 10:30:15 INF] 启动文件传输服务器...
[2024-01-15 10:30:16 INF] 文件传输服务器启动完成，监听地址: http://localhost:5000
[2024-01-15 10:35:22 INF] 开始处理文件上传请求
[2024-01-15 10:35:22 INF] 文件信息: 名称=test.zip, 大小=1048576 字节
[2024-01-15 10:35:25 INF] 文件上传成功: test.zip, 大小: 1048576 字节, 路径: Files\test.zip
```
**日志文件命名示例**：
- 生产环境: `2024-01-15.log`
- 开发环境: `debug-2024-01-15.log`
**日志目录结构示例**：
```
Logs/
├── 2024-01-15.log # 生产环境日志
├── 2024-01-16.log
├── debug-2024-01-15.log # 开发环境日志
└── debug-2024-01-16.log
```
## Web界面技术实现
### 文件结构
```
FileServer/wwwroot/
├── index.html # 主页面
├── styles/
│ └── index.css # 样式文件
└── scripts/
└── index.js # 脚本文件
```
### 技术特点
- **模块化设计**: CSS和JavaScript分离到独立文件，便于维护
- **进度监控**: 使用XMLHttpRequest实现上传进度实时显示
- **拖拽上传**: 支持HTML5拖拽API，提供直观的上传体验
- **响应式布局**: CSS3媒体查询，适配不同屏幕尺寸
- **动画效果**: CSS3动画和过渡效果，提升用户体验
- **错误处理**: 完善的JavaScript错误处理和用户反馈
### 主要功能
- ✅ 文件拖拽上传
- ✅ 实时进度显示
- ✅ 文件列表管理
- ✅ 一键下载功能
- ✅ 文件删除功能
- ✅ 状态消息提示
- ✅ 文件大小格式化显示
## 客户端UI特性
### 界面布局
- **服务器设置面板**: 服务器地址输入和连接/刷新按钮
- **文件列表面板**: 显示服务器文件列表，支持多选下载
- **下载进度面板**: 显示下载任务进度、速度、剩余时间和状态
### 智能按钮管理
- **暂停/继续按钮**: 根据下载任务状态自动切换文本和功能
- **取消按钮**: 支持取消选中的下载任务
- **按钮状态**: 根据下载任务列表自动启用/禁用按钮
### 事件处理
- **窗体关闭事件**: 自动取消所有下载任务并释放资源
- **下载进度事件**: 实时更新下载进度和速度显示
- **下载完成事件**: 自动清理任务并更新UI状态
## 依赖包
### 服务端依赖 (FileServer.csproj)
```xml
```
### 客户端依赖 (FileClient.csproj)
```xml
```
### 公共类库依赖 (Common.csproj)
- 无外部依赖包，仅使用.NET 8.0内置功能
## 许可证
MIT License