大文件上传技术：断点续传与TUS协议实践-代码聚汇网

大文件上传技术：断点续传与TUS协议实践

菩提自性

1. 大文件上传的痛点与解决方案

大文件上传一直是Web开发中的常见挑战。想象一下，你正在上传一个3GB的视频文件，进度已经达到95%，突然网络波动导致上传中断。传统方案下，你不得不重新开始整个上传过程，这不仅浪费带宽，更消耗用户耐心。

断点续传技术正是为解决这一问题而生。其核心原理是将大文件分割成多个小块（chunk），每个小块独立上传。服务器会记录已成功接收的块，当上传中断后，客户端只需上传剩余部分即可。这种机制带来三个显著优势：

网络容错性：单个块上传失败不影响其他块
带宽利用率：可并行上传多个块
用户体验：进度可实时保存和恢复

在PHP生态中，实现断点续传主要有两种技术路线：

原生实现：通过PHP文件处理函数手动管理分块
协议化方案：采用TUS等标准化协议

提示：当文件超过100MB时就应该考虑分块上传，超过1GB则必须实现断点续传功能

2. 基于TUS协议的技术实现

2.1 TUS协议核心概念

TUS是一种基于HTTP的开放协议，专为文件上传优化设计。其最新版本1.0.0定义了以下关键机制：

分块传输：支持将文件拆分为任意大小的块
断点恢复：通过Upload-Offset头标识续传位置
完整性校验：最终合并时验证文件SHA256哈希值
过期机制：未完成的上传可设置保留期限

协议的工作流程如下：

code复制客户端                              服务器
  |---- POST (创建上传) ------------>|
  |<---- 201 Created (返回URL) ------|
  |---- PATCH (上传分块1) ---------->|
  |<---- 204 No Content (确认) ------|
  |---- PATCH (上传分块2) ---------->|
  |<---- 204 No Content (确认) ------|
  |---- HEAD (查询进度) ------------>|
  |<---- 200 OK (返回已接收字节) ----|

2.2 服务端配置

使用tus-php库搭建服务端需要以下步骤：

安装依赖：

bash复制composer require ankitpokhrel/tus-php

创建入口文件server.php：

php复制<?php
require __DIR__.'/vendor/autoload.php';

$server = new \TusPhp\Tus\Server('redis');
$server->setApiPath('/files') // 接口前缀
       ->setUploadDir('/var/uploads'); // 存储目录

$response = $server->serve();
$response->send();

Nginx配置示例：

nginx复制location /files {
    client_max_body_size 0; # 禁用大小限制
    proxy_request_buffering off;
    
    try_files $uri $uri/ /server.php?$query_string;
}

关键配置说明：

client_max_body_size 0 允许无限大小的请求体
proxy_request_buffering off 禁用缓冲以实现实时传输
Redis用于存储上传元数据，确保多服务器场景下的状态同步

2.3 客户端实现

前端可采用Uppy.js集成TUS插件：

javascript复制import Uppy from '@uppy/core'
import Tus from '@uppy/tus'

const uppy = new Uppy({
  restrictions: {
    maxFileSize: 5 * 1024 * 1024 * 1024 // 5GB
  }
})

uppy.use(Tus, {
  endpoint: '/files',
  chunkSize: 10 * 1024 * 1024, // 10MB/块
  retryDelays: [0, 1000, 3000, 5000]
})

PHP客户端示例：

php复制$client = new \TusPhp\Tus\Client('http://yourserver.com');

// 设置元数据
$client->setMetadata([
    'filename' => basename($filePath),
    'filetype' => mime_content_type($filePath)
]);

// 分块上传（5MB/块）
$bytesUploaded = $client->setKey($uniqueId)
                       ->file($filePath)
                       ->upload(5 * 1024 * 1024);

3. 原生PHP实现方案

3.1 分块处理逻辑

对于无法使用TUS的环境，可手动实现分块上传：

前端分块处理：

javascript复制const chunkSize = 5 * 1024 * 1024; // 5MB
let offset = 0;

function uploadChunk(file, chunkNumber) {
  const chunk = file.slice(offset, offset + chunkSize);
  
  const formData = new FormData();
  formData.append('chunk', chunk);
  formData.append('chunkNumber', chunkNumber);
  formData.append('totalChunks', Math.ceil(file.size / chunkSize));
  
  return fetch('/upload.php', {
    method: 'POST',
    body: formData
  });
}

服务端合并逻辑：

php复制$targetDir = "uploads/{$_POST['uploadId']}";
$chunkPath = "{$targetDir}/{$_POST['chunkNumber']}";

// 保存分块
move_uploaded_file($_FILES['chunk']['tmp_name'], $chunkPath);

// 检查是否全部完成
$totalChunks = (int)$_POST['totalChunks'];
$uploadedChunks = count(glob("{$targetDir}/*"));

if ($uploadedChunks === $totalChunks) {
    // 按序号合并所有分块
    $finalPath = "uploads/{$_POST['filename']}";
    for ($i = 1; $i <= $totalChunks; $i++) {
        file_put_contents(
            $finalPath,
            file_get_contents("{$targetDir}/{$i}"),
            FILE_APPEND
        );
    }
    
    // 清理临时文件
    array_map('unlink', glob("{$targetDir}/*"));
    rmdir($targetDir);
}

3.2 断点续传实现

实现断点续传需要三个关键步骤：

文件标识：使用文件内容哈希作为唯一ID

php复制$fileId = hash_file('md5', $tmpPath);

进度记录：数据库存储结构示例

sql复制CREATE TABLE uploads (
    id VARCHAR(32) PRIMARY KEY,
    filename VARCHAR(255),
    total_size BIGINT,
    uploaded BIGINT,
    status ENUM('pending','completed'),
    created_at TIMESTAMP
);

进度查询接口：

php复制$stmt = $pdo->prepare("SELECT uploaded FROM uploads WHERE id = ?");
$stmt->execute([$_GET['fileId']]);
$progress = $stmt->fetchColumn();

header('Content-Type: application/json');
echo json_encode(['uploaded' => $progress]);

4. 性能优化与问题排查

4.1 上传性能优化

并行上传：浏览器端可同时发起多个分块请求

javascript复制// 同时上传3个分块
const parallel = 3;
for (let i = 0; i < parallel; i++) {
    uploadChunk(file, currentChunk++);
}

动态分块大小：根据网络质量调整

javascript复制// 根据平均上传速度调整分块大小
let chunkSize = navigator.connection.downlink > 5 
    ? 10 * 1024 * 1024 
    : 2 * 1024 * 1024;

内存优化：服务端使用流处理

php复制$input = fopen('php://input', 'rb');
$target = fopen($chunkPath, 'ab');

stream_copy_to_stream($input, $target);

fclose($input);
fclose($target);

4.2 常见问题解决方案

问题1：分块上传后合并失败

可能原因：

分块顺序错乱
分块大小不一致

解决方案：

php复制// 合并前按数字序号排序
$chunks = glob("{$targetDir}/*");
natsort($chunks);

foreach ($chunks as $chunk) {
    // 合并操作
}

问题2：大文件上传超时

调整PHP配置：

ini复制max_execution_time = 0
upload_max_filesize = 1024M
post_max_size = 1025M

问题3：进度显示不准确

改进方案：

javascript复制// 使用XMLHttpRequest的progress事件
xhr.upload.addEventListener('progress', (e) => {
    const percent = Math.round((e.loaded + prevLoaded) / totalSize * 100);
    updateProgress(percent);
});

5. 安全防护措施

文件校验：

php复制// 验证文件类型
$finfo = new finfo(FILEINFO_MIME_TYPE);
$mime = $finfo->file($tmpPath);

if (!in_array($mime, ['video/mp4', 'image/jpeg'])) {
    throw new Exception('Invalid file type');
}

// 验证文件内容
if (strpos(file_get_contents($tmpPath, false, null, 0, 100), '<?php') !== false) {
    unlink($tmpPath);
    throw new Exception('Security check failed');
}

权限控制：

php复制// 设置上传目录不可执行
chmod($uploadDir, 0750);
ini_set('disable_functions', 'exec,passthru,shell_exec,system');

防DoS攻击：

nginx复制# 限制上传速率
limit_rate 500k;
# 限制并发连接数
limit_conn upload 10;

在实际项目中，我们团队发现使用TUS协议相比原生实现可以节省约30%的开发时间，特别是在跨设备续传等复杂场景下。但要注意TUS的PHP客户端在处理大于2GB文件时可能出现内存问题，这时可以考虑改用分块校验模式：

php复制$client->setChecksumAlgorithm('crc32')->upload($chunkSize);

对于超大规模文件存储（如视频平台），建议将最终合并后的文件直接转存到对象存储（如S3），避免服务器本地磁盘压力：

php复制$s3->putObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'uploads/'.$fileId,
    'Body'   => fopen($mergedPath, 'r')
]);