149 lines
3.7 KiB
Markdown
149 lines
3.7 KiB
Markdown
# UPFS - Upload File to Server
|
||
|
||
一个用于向UPFS服务器上传文件的Rust命令行工具，现在支持实时进度跟踪和上传速度显示。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 文件上传到远程服务器
|
||
- ✅ 用户认证（用户名/密码）
|
||
- ✅ **新增**: 实时上传进度跟踪
|
||
- ✅ **新增**: 上传速度计算和显示
|
||
- ✅ **新增**: 剩余时间估算
|
||
- ✅ **新增**: 可视化进度条
|
||
- ✅ **新增**: 灵活的进度回调API
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd upfs
|
||
cargo build --release
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基本用法
|
||
|
||
```bash
|
||
./upfs -f <文件路径> -r <远程路径> -u <用户名> -p <密码>
|
||
```
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
# 上传文件（默认显示进度）
|
||
./upfs -f ./large_file.zip -r /backup/large_file.zip -u admin -p mypassword
|
||
|
||
# 上传文件（不带密码参数，会交互式输入）
|
||
./upfs -f ./document.pdf -r /documents/doc.pdf -u admin
|
||
```
|
||
|
||
## 进度显示格式
|
||
|
||
默认情况下，所有上传都会显示实时的上传进度：
|
||
|
||
```
|
||
[=========> ] 45.2% | 2.3 MB/s | 12s | 预计剩余 14s | 4.5 MB/10.0 MB
|
||
```
|
||
|
||
进度条包含以下信息：
|
||
- **进度条**: 可视化显示上传进度
|
||
- **百分比**: 当前的完成百分比
|
||
- **速度**: 当前上传速度（B/s, KB/s, MB/s, GB/s）
|
||
- **已用时间**: 从开始上传到现在的时间
|
||
- **剩余时间**: 预计完成上传还需要的时间
|
||
- **已上传/总大小**: 已上传的数据量和总文件大小
|
||
|
||
## API 使用
|
||
|
||
### 基本上传
|
||
|
||
```rust
|
||
use upfs::update::upload_file;
|
||
|
||
// 直接上传，不显示进度
|
||
let result = upload_file(token, "file.txt", "/remote/path.txt").await?;
|
||
```
|
||
|
||
### 带进度回调的上传
|
||
|
||
```rust
|
||
use upfs::update::{upload_file_with_progress, UploadProgress};
|
||
|
||
// 带进度跟踪的上传
|
||
let result = upload_file_with_progress(
|
||
token,
|
||
"large_file.zip",
|
||
"/remote/large_file.zip",
|
||
|progress| {
|
||
println!("进度: {:.1}%", progress.percentage);
|
||
println!("速度: {}", progress.format_speed());
|
||
println!("剩余时间: {}", progress.format_remaining_time());
|
||
}
|
||
).await?;
|
||
```
|
||
|
||
### UploadProgress 结构体
|
||
|
||
```rust
|
||
pub struct UploadProgress {
|
||
pub bytes_uploaded: u64, // 已上传字节数
|
||
pub total_bytes: u64, // 总字节数
|
||
pub percentage: f64, // 完成百分比 (0.0-100.0)
|
||
pub speed_bps: f64, // 上传速度（字节/秒）
|
||
pub elapsed_time: Duration, // 已用时间
|
||
}
|
||
```
|
||
|
||
### UploadProgress 方法
|
||
|
||
- `format_speed()`: 格式化速度显示（如 "2.3 MB/s"）
|
||
- `format_bytes()`: 格式化字节大小（如 "10.5 MB"）
|
||
- `format_elapsed_time()`: 格式化已用时间（如 "2m 15s"）
|
||
- `format_remaining_time()`: 格式化剩余时间（如 "预计剩余 1m 30s"）
|
||
- `estimate_remaining_time()`: 估算剩余时间
|
||
|
||
## 命令行参数
|
||
|
||
| 参数 | 简写 | 长参数 | 描述 | 默认值 |
|
||
|------|------|--------|------|--------|
|
||
| 文件路径 | `-f` | `--file` | 要上传的文件路径 | 必需 |
|
||
| 远程路径 | `-r` | `--remote-path` | 服务器上的远程路径 | 必需 |
|
||
| 用户名 | `-u` | `--username` | 认证用户名 | "admin" |
|
||
| 密码 | `-p` | `--password` | 认证密码 | 可选（交互式输入） |
|
||
|
||
## 示例程序
|
||
|
||
查看 `examples/progress_demo.rs` 获取完整的使用示例：
|
||
|
||
```bash
|
||
cargo run --example progress_demo
|
||
```
|
||
|
||
## 开发和构建
|
||
|
||
```bash
|
||
# 检查代码
|
||
cargo check
|
||
|
||
# 运行测试
|
||
cargo test
|
||
|
||
# 构建发布版本
|
||
cargo build --release
|
||
|
||
# 运行示例
|
||
cargo run --example progress_demo
|
||
```
|
||
|
||
## 技术细节
|
||
|
||
- 使用 `reqwest` 进行HTTP请求
|
||
- 使用 `multipart/form-data` 上传文件
|
||
- 使用异步I/O和流式处理实现进度跟踪
|
||
- 支持大文件上传（分块读取）
|
||
- 实时计算上传速度和剩余时间
|
||
|
||
## 贡献
|
||
|
||
欢迎提交Issue和Pull Request来改进这个项目！ |