零拷贝闭环：Axum 流式文件下载实战（GB+ 大文件）

RustFS Team
04 Apr, 2026

Photos provided by Unsplash OR Pexels

零拷贝的优雅之舞：Rust 文件下载实战指南（从上传到下载的完美闭环）

在上篇上传指南中，我们实现了数据从网络 → 磁盘的流式零拷贝，避免了全量加载大文件导致的内存爆炸。下载场景则正好反过来：数据从磁盘 → 网络。同样，传统方式（先把整个文件读成 Vec<u8> 或 Bytes 再返回）会带来两次重大拷贝和巨大内存峰值，而零拷贝下载的核心是流式响应（Streaming Response）——文件以 chunk 为单位边读边发，服务器内存占用恒定在缓冲区大小（通常几 KB 到几十 KB）。

在 Rust + Axum 中，这主要依赖：

tokio::fs::File（AsyncRead）
tokio_util::io::ReaderStream（将 AsyncRead 转为 Stream<Item = Result<Bytes, _>>）
axum::body::StreamBody（转为 HTTP Body）

最终，Hyper（Axum 底层）会把这些 Bytes chunk 高效写入网络 socket，最大限度减少用户态拷贝。Linux 等平台下，内核还会进一步优化（类似 sendfile 机制的思想），实现接近零拷贝的传输。

这篇指南延续上篇风格，手把手带你实现生产级文件下载，支持大文件（GB+）、正确 MIME 类型、下载提示头，并对比传统方式的性能差异。

1. 为什么下载也要零拷贝？

传统方式：fs::read() 或 file.read_to_end() → 全量 Vec<u8> → Body::from(vec) → 内存 O(N)，大文件直接 OOM 或高延迟。
零拷贝/流式方式：打开文件 → ReaderStream → StreamBody → chunk-by-chunk 发送 → 内存 O(1)，支持并发下载百 GB 文件，CPU 压力大幅降低。
收益：内存峰值从 GB 级降到 MB 级以下，吞吐量提升显著，尤其适合视频、模型、备份文件等场景。

2. 项目依赖（延续上传项目）

在之前的 Cargo.toml 基础上，添加/确保以下依赖：

[dependencies]
axum = { version = "0.7", features = ["multipart"] }
tokio = { version = "1", features = ["full"] }
tokio-util = { version = "0.7", features = ["io"] }  # ReaderStream
futures-util = "0.3"
tower-http = { version = "0.6", features = ["fs", "limit"] }  # 可选 ServeDir
mime_guess = "2.0"  # MIME 类型猜测

3. 核心代码：流式零拷贝下载 Handler

src/main.rs（完整示例，包含上传 + 下载）：

use axum::{
    body::StreamBody,
    extract::Path,
    http::{header, StatusCode},
    response::IntoResponse,
    routing::{get, post},
    Router,
};
use futures_util::TryStreamExt; // 如果需要额外流处理
use std::path::Path as StdPath;
use tokio::fs::File;
use tokio_util::io::ReaderStream;
use tower_http::limit::RequestBodyLimitLayer;

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/upload", post(upload_handler))
        .route("/download/{filename}", get(download_handler))
        .layer(RequestBodyLimitLayer::max(2 * 1024 * 1024 * 1024)); // 上传限制

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("🚀 零拷贝上传/下载服务启动: http://localhost:3000");
    axum::serve(listener, app).await.unwrap();
}

// 上篇上传代码（省略，保持一致）...
async fn upload_handler(/* ... */) -> /* ... */ { /* ... */ }

// 🔥 零拷贝下载核心
async fn download_handler(Path(filename): Path<String>) -> Result<impl IntoResponse, StatusCode> {
    let filepath = StdPath::new("uploads").join(&filename);

    // 安全检查：防止路径穿越
    if !filepath.starts_with("uploads/") {
        return Err(StatusCode::BAD_REQUEST);
    }

    let file = match File::open(&filepath).await {
        Ok(f) => f,
        Err(_) => return Err(StatusCode::NOT_FOUND),
    };

    // 获取文件元数据（用于 Content-Length，可选但推荐）
    let metadata = file.metadata().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
    let file_size = metadata.len();

    // MIME 类型猜测
    let content_type = mime_guess::from_path(&filepath)
        .first_raw()
        .unwrap_or("application/octet-stream");

    // 🔥 关键：AsyncRead → Stream → StreamBody
    let stream = ReaderStream::new(file);           // 产生 Bytes chunk 流
    let body = StreamBody::new(stream);             // 转为 Axum Body

    let headers = [
        (header::CONTENT_TYPE, content_type),
        (header::CONTENT_DISPOSITION, &format!("attachment; filename=\"{}\"", filename)),
        (header::CONTENT_LENGTH, &file_size.to_string()), // 让客户端显示进度条
    ];

    Ok((headers, body))
}

运行测试：

mkdir -p uploads
# 先上传一个大文件测试，再访问：
# curl -O http://localhost:3000/download/your_large_file.bin
# 或浏览器直接访问
cargo run

观察服务器内存：即使下载 10GB 文件，占用也几乎不变——这就是流式的力量。

4. 进阶优化（让下载更优雅、更快）

使用 tower_http::services::ServeDir：
最简单方式，直接服务整个目录（内部已优化流式）：
```
use tower_http::services::ServeDir;
let app = Router::new().nest_service("/static", ServeDir::new("uploads"));
```
它会自动处理 MIME、ETag、If-Modified-Since 等，生产推荐。
Range 请求支持（断点续传、视频流）：解析 Range 头，结合 file.seek() + 流式返回部分内容。适合大视频/模型文件。
极致性能（内核级零拷贝）：
- Linux 下，底层 Hyper + Tokio 网络栈会尽量利用 sendfile / splice 等机制（用户态几乎零拷贝）。
- 若需手动控制，可探索 sendfile crate（需底层 socket 访问，Axum 中较复杂，目前 tower-http ServeFile 尚未原生集成）。
- 云存储直传：从 S3 等直接流式转发到客户端，避免本地磁盘落地。
性能对比：
- 传统 fs::read() + Body::from(vec)：1GB 文件 → 峰值内存 ~1GB+，延迟高。
- 本文流式方案：峰值内存 < 几十 KB，适合高并发。
错误处理与安全：
- 文件存在性检查、路径 sanitization。
- 添加 Content-Length 让客户端显示下载进度。
- 大文件限流（tower_http rate limit）防止滥用。