tusio/tusd

tusd

镜像概述和主要用途

tusd是tus可恢复上传协议的官方参考实现。tus协议基于HTTP，专为可恢复文件上传设计，允许上传过程在任意时刻中断（如网络问题、服务器宕机或用户主动暂停），并在恢复时无需重新上传已传输的数据。

tusd能够接收任意大小的文件上传，并将其存储在本地磁盘、Google Cloud Storage（GCS）或AWS S3（及其他S3兼容存储系统）中。由于其模块化和可扩展性设计，可轻松添加对其他云存储服务的支持。

协议版本： 1.0.0

注：当前版本为tusd v1。如需查看引入破坏性变更前的主要版本，请参考https://github.com/tus/tusd/tree/0.14.0%E3%80%82

核心功能和特性

• 可恢复上传：支持上传中断后无缝恢复，避免重复传输已上传数据
• 灵活存储：支持本地磁盘、Google Cloud Storage、AWS S3及S3兼容存储系统
• 任意文件大小：无文件大小限制，可处理超大文件上传
• 模块化设计：易于扩展，可添加对其他云存储服务的支持
• HTTP协议基础：基于标准HTTP协议，易于集成到现有Web应用中

使用场景和适用范围

• 大文件上传：如视频、备份文件、数据集等超大文件传输
• 网络不稳定环境：在网络连接不可靠场景下保证上传可靠性
• 用户可控上传：支持用户主动暂停/继续上传操作的应用
• 云存储集成：需要将上传文件直接存储到GCS、S3等云存储的服务
• Web应用后端：作为文件上传服务集成到各类Web应用中

使用方法和配置说明

基本使用（Docker Run）

通过Docker运行tusd服务，默认使用本地磁盘存储：

bash
docker run -d -p 8080:8080 -v /path/to/local/storage:/srv/tusd tusproject/tusd

参数说明：

• -p 8080:8080：将容器的8080端口映射到主机的8080端口
• -v /path/to/local/storage:/srv/tusd：挂载本地目录作为文件存储路径

配置存储后端

AWS S3存储

bash
docker run -d -p 8080:8080 \
  -e AWS_ACCESS_KEY_ID=your-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret-key \
  -e AWS_REGION=us-east-1 \
  tusproject/tusd -s3-bucket=your-bucket-name

Google Cloud Storage

bash
docker run -d -p 8080:8080 \
  -v /path/to/gcs-credentials.json:/credentials.json \
  -e GOOGLE_APPLICATION_CREDENTIALS=/credentials.json \
  tusproject/tusd -gcs-bucket=your-bucket-name

高级配置

监控服务器

tusd提供Prometheus指标端点，可通过-metrics-path参数配置：

bash
docker run -d -p 8080:8080 tusproject/tusd -metrics-path=/metrics

访问http://localhost:8080/metrics获取监控指标。

钩子事件

通过-hooks-http参数配置HTTP钩子，接收上传事件（如上传开始、完成、失败等）：

bash
docker run -d -p 8080:8080 tusproject/tusd -hooks-http=http://your-hook-server/hooks

文档资源

• https://github.com/tus/tusd/blob/master/docs/installation.md
• https://github.com/tus/tusd/blob/master/docs/usage-binary.md
  • https://github.com/tus/tusd/blob/master/docs/monitoring.md
  • https://github.com/tus/tusd/blob/master/docs/hooks.md
• https://github.com/tus/tusd/blob/master/docs/usage-package.md
• https://github.com/tus/tusd/blob/master/docs/faq.md

许可证

本项目采用MIT许可证，详见https://github.com/tus/tusd/blob/master/LICENSE.txt%E3%80%82