Rust SFTP客户端库 russh-sftp 使用指南

概述

russh-sftp 是一个基于 Rust 语言开发的 SFTP（SSH File Transfer Protocol）客户端库，提供安全高效的文件传输和远程操作功能。该库构建在 russh SSH 库之上，支持完整的 SFTP 协议操作。

主要特性

• 安全的 SSH 连接和身份验证
• 完整的 SFTP 操作支持
• 异步/同步文件传输
• 目录操作和管理
• 文件权限和属性管理
• 高性能的并发传输

安装方法

在 Cargo.toml 中添加依赖：

[dependencies]
russh-sftp = "0.4"
tokio = { version = "1.0", features = ["full"] }

基本使用方法

1. 建立 SFTP 连接

use russh_sftp::client::{SftpClient, SftpOptions};
use russh_sftp::protocol::FileOpenOptions;
use tokio::net::TcpStream;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 建立 TCP 连接
    let stream = TcpStream::connect("example.com:22").await?;
    
    // 创建 SFTP 客户端
    let mut client = SftpClient::new(
        stream,
        SftpOptions::default()
            .username("your_username")
            .password("your_password")
    ).await?;
    
    // 执行操作...
    
    Ok(())
}

2. 文件上传示例

async fn upload_file(client: &mut SftpClient, local_path: &str, remote_path: &str) -> Result<(), Box<dyn std::error::Error>> {
    // 打开本地文件
    let mut file = tokio::fs::File::open(local_path).await?;
    
    // 创建远程文件
    let remote_file = client
        .open(
            remote_path,
            FileOpenOptions::new()
                .write(true)
                .create(true)
                .truncate(true),
        )
        .await?;
    
    // 读取本地文件内容并写入远程文件
    let mut contents = Vec::new();
    file.read_to_end(&mut contents).await?;
    remote_file.write_all(&contents).await?;
    
    println!("文件上传成功: {}", remote_path);
    Ok(())
}

3. 文件下载示例

async fn download_file(client: &mut SftpClient, remote_path: &str, local_path: &str) -> Result<(), Box<dyn std::error::Error>> {
    // 打开远程文件
    let mut remote_file = client
        .open(remote_path, FileOpenOptions::new().read(true))
        .await?;
    
    // 创建本地文件
    let mut local_file = tokio::fs::File::create(local_path).await?;
    
    // 读取远程文件内容并写入本地文件
    let mut contents = Vec::new();
    remote_file.read_to_end(&mut contents).await?;
    local_file.write_all(&contents).await?;
    
    println!("文件下载成功: {}", local_path);
    Ok(())
}

4. 目录操作示例

async fn list_directory(client: &mut SftpClient, path: &str) -> Result<(), Box<dyn std::error::Error>> {
    // 列出目录内容
    let entries = client.readdir(path).await?;
    
    for entry in entries {
        println!("名称: {}, 类型: {:?}, 大小: {} bytes", 
                entry.filename, 
                entry.attrs.file_type(),
                entry.attrs.size.unwrap_or(0));
    }
    
    Ok(())
}

async fn create_directory(client: &mut SftpClient, path: &str) -> Result<(), Box<dyn std::error::Error>> {
    client.mkdir(path, 0o755).await?;
    println!("目录创建成功: {}", path);
    Ok(())
}

5. 文件操作示例

async fn file_operations(client: &mut SftpClient) -> Result<(), Box<dyn std::error::Error>> {
    // 重命名文件
    client.rename("old_name.txt", "new_name.txt").await?;
    
    // 删除文件
    client.remove("file_to_delete.txt").await?;
    
    // 获取文件属性
    let attrs = client.stat("some_file.txt").await?;
    println!("文件大小: {} bytes", attrs.size.unwrap_or(0));
    
    Ok(())
}

错误处理

async fn handle_errors(client: &mut SftpClient) {
    match client.stat("nonexistent_file.txt").await {
        Ok(attrs) => println!("文件存在，大小: {}", attrs.size.unwrap_or(0)),
        Err(russh_sftp::error::Error::Sftp(russh_sftp::protocol::Status::NoSuchFile)) => {
            println!("文件不存在")
        }
        Err(e) => eprintln!("发生错误: {}", e),
    }
}

完整示例代码

use russh_sftp::client::{SftpClient, SftpOptions};
use russh_sftp::protocol::FileOpenOptions;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 建立 SFTP 连接
    let stream = TcpStream::connect("example.com:22").await?;
    
    let mut client = SftpClient::new(
        stream,
        SftpOptions::default()
            .username("your_username")
            .password("your_password")
    ).await?;

    // 创建测试目录
    create_directory(&mut client, "test_dir").await?;
    
    // 列出目录内容
    list_directory(&mut client, ".").await?;
    
    // 文件上传
    upload_file(&mut client, "local_file.txt", "test_dir/remote_file.txt").await?;
    
    // 文件下载
    download_file(&mut client, "test_dir/remote_file.txt", "downloaded_file.txt").await?;
    
    // 文件操作
    file_operations(&mut client).await?;
    
    // 错误处理示例
    handle_errors(&mut client).await;

    Ok(())
}

async fn upload_file(client: &mut SftpClient, local_path: &str, remote_path: &str) -> Result<(), Box<dyn std::error::Error>> {
    let mut file = tokio::fs::File::open(local_path).await?;
    let remote_file = client
        .open(
            remote_path,
            FileOpenOptions::new()
                .write(true)
                .create(true)
                .truncate(true),
        )
        .await?;
    
    let mut contents = Vec::new();
    file.read_to_end(&mut contents).await?;
    remote_file.write_all(&contents).await?;
    
    println!("文件上传成功: {}", remote_path);
    Ok(())
}

async fn download_file(client: &mut SftpClient, remote_path: &str, local_path: &str) -> Result<(), Box<dyn std::error::Error>> {
    let mut remote_file = client
        .open(remote_path, FileOpenOptions::new().read(true))
        .await?;
    
    let mut local_file = tokio::fs::File::create(local_path).await?;
    
    let mut contents = Vec::new();
    remote_file.read_to_end(&mut contents).await?;
    local_file.write_all(&contents).await?;
    
    println!("文件下载成功: {}", local_path);
    Ok(())
}

async fn list_directory(client: &mut SftpClient, path: &str) -> Result<(), Box<dyn std::error::Error>> {
    let entries = client.readdir(path).await?;
    
    println!("目录 {} 内容:", path);
    for entry in entries {
        println!("名称: {}, 类型: {:?}, 大小: {} bytes", 
                entry.filename, 
                entry.attrs.file_type(),
                entry.attrs.size.unwrap_or(0));
    }
    
    Ok(())
}

async fn create_directory(client: &mut SftpClient, path: &str) -> Result<(), Box<dyn std::error::Error>> {
    client.mkdir(path, 0o755).await?;
    println!("目录创建成功: {}", path);
    Ok(())
}

async fn file_operations(client: &mut SftpClient) -> Result<(), Box<dyn std::error::Error>> {
    // 创建测试文件
    let test_file = client
        .open(
            "test_file.txt",
            FileOpenOptions::new()
                .write(true)
                .create(true),
        )
        .await?;
    test_file.write_all(b"Hello, SFTP!").await?;
    
    // 重命名文件
    client.rename("test_file.txt", "renamed_file.txt").await?;
    
    // 获取文件属性
    let attrs = client.stat("renamed_file.txt").await?;
    println!("重命名文件大小: {} bytes", attrs.size.unwrap_or(0));
    
    // 删除文件
    client.remove("renamed_file.txt").await?;
    
    Ok(())
}

async fn handle_errors(client: &mut SftpClient) {
    match client.stat("nonexistent_file.txt").await {
        Ok(attrs) => println!("文件存在，大小: {}", attrs.size.unwrap_or(0)),
        Err(russh_sftp::error::Error::Sftp(russh_sftp::protocol::Status::NoSuchFile)) => {
            println!("文件不存在")
        }
        Err(e) => eprintln!("发生错误: {}", e),
    }
}

性能优化建议

1. 使用缓冲区：对于大文件传输，使用适当的缓冲区大小
2. 并发传输：利用异步特性进行多个文件的并发传输
3. 连接复用：保持连接打开以进行多个操作
4. 错误重试：实现适当的重试机制处理网络波动

注意事项

• 确保服务器支持 SFTP 协议
• 正确处理连接超时和重连
• 注意文件权限和所有权问题
• 在生产环境中使用适当的日志记录和监控

这个库提供了强大而灵活的 SFTP 操作功能，结合 Rust 的安全性和性能优势，是构建可靠文件传输应用的优秀选择。