gouploader

package module
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 30, 2026 License: MIT Imports: 13 Imported by: 0

README

gouploader

生产级文件上传工具包，适用于 Gin 框架。

📖 完整架构设计与生产级维度说明请看 docs/ARCHITECTURE.md

功能特性

  • 普通上传 — 单文件上传，流式 I/O，内存恒定
  • 分片上传 — 大文件拆分为分片，并行上传 + 断点续传
  • 秒传 — 基于整文件哈希索引，命中即零流量上传（需注入 HashStore）
  • 云原生 Multipart 直传（方案 A） — 服务端只签名，客户端 PUT 直连云端，大文件不过服务器带宽
  • STS 前端直传（方案 B） — 客户端用云厂商 JS SDK 直连云端
  • 可插拔存储 — 本地磁盘 / S3 兼容（MinIO、AWS）/ 三家云独立子 module（按需引入，主包零污染）
  • 自定义存储 — 实现 Storage / MultipartStorage 接口对接任意后端
  • Feature Flag 灰度 — Multipart 路径按请求动态切换
  • 悬挂 Multipart 清理 — 后台 worker 自动扫描 + Abort，防止云厂商费用泄漏
  • 完整性校验 — MD5 / SHA256 校验；Complete 前服务端二次校验云端 ETag
  • 安全防护 — 目录穿越防护、预签名 URL 参数锁死、表单字段大小限制
  • 并发与内存安全 — 会话级互斥锁、原子文件写入、幂等上传、全链路流式 I/O
  • 跨域支持 / 回调机制 — 内置 CORS 中间件、上传完成钩子

安装

# 主包（所有场景必装）
go get github.com/gtkit/gouploader

# 按需引入云厂商 adapter（三选一或多选，主包不会被污染）
go get github.com/gtkit/gouploader/aliyun   # 阿里云 OSS
go get github.com/gtkit/gouploader/tencent  # 腾讯云 COS
go get github.com/gtkit/gouploader/huawei   # 华为云 OBS

三条上传路径

路径 数据流 前端依赖 使用场景
代理上传 Client → Server → Storage 纯 HTTP 小文件、本地磁盘 / MinIO
Multipart 直传（方案 A） Client → Cloud（Server 只签名） 纯 HTTP（PUT 预签名 URL） 大文件、阿里 / 腾讯 / 华为云
STS 直传（方案 B） Client → Cloud（Server 只签 STS） 云厂商 JS SDK 浏览器、前端可引入云 SDK

三条路径共享同一套协议（/chunk/init、/chunk/resume、/chunk/complete、/chunk/abort），前端无需感知当前走哪条——由 /chunk/init 响应中的 upload_path 字段指示。

快速开始

package main

import (
    "log"

    "github.com/gin-gonic/gin"
    "github.com/gtkit/gouploader"
)

func main() {
    r := gin.Default()

    uploader, err := gouploader.New(
        gouploader.WithLocalStorage("./uploads"),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer uploader.Close()

    uploader.RegisterRoutes(r.Group("/api/v1/upload"))
    r.Run(":8080")
}

生产级配置示例（方案 A：Multipart 直传 + 秒传 + 灰度）

import (
    "time"
    "github.com/gtkit/gouploader"
    "github.com/gtkit/gouploader/aliyun"  // 按需引入，主包不会拉这个依赖
)

// 1. 创建云原生 Storage
ossStorage, _ := aliyun.NewStorage(aliyun.Config{
    Endpoint:        "oss-cn-hangzhou.aliyuncs.com",
    AccessKeyID:     os.Getenv("OSS_AK"),
    AccessKeySecret: os.Getenv("OSS_SK"),
    Bucket:          "my-bucket",
    Region:          "cn-hangzhou",
})

// 2. 实现 HashStore（秒传索引）- 业务方按需用 DB/Redis 实现
type dbHashStore struct{ db *gorm.DB }
func (s *dbHashStore) LookupByHash(ctx context.Context, algo, hash string) (*gouploader.HashedFile, error) { ... }
func (s *dbHashStore) Register(ctx context.Context, entry *gouploader.HashedFile) error { ... }

// 3. 组装
uploader, _ := gouploader.New(
    gouploader.WithStorage(ossStorage),               // 云原生 Storage，自动启用 Multipart 直传
    gouploader.WithHashStore(&dbHashStore{db: db}),   // 秒传

    // Multipart 直传配置
    gouploader.WithMultipartThreshold(100 << 20),     // 大于 100MB 走直传；小于等于走代理
    gouploader.WithPartSignTTL(15 * time.Minute),     // 单 URL 有效期

    // 灰度 Feature Flag
    gouploader.WithMultipartFeatureFlag(func(ctx, ginCtx, req) bool {
        uid := ginCtx.GetString("user_id")
        return hashMod(uid, 100) < 10   // 10% 灰度
    }),

    // 用户隔离
    gouploader.WithUserIDFn(func(c *gin.Context) string {
        return c.GetString("user_id")
    }),
    gouploader.WithMultipartKeyPrefix(func(c *gin.Context, userID string) string {
        return fmt.Sprintf("user-%s/%s/", userID, time.Now().Format("2006-01-02"))
    }),

    // 悬挂 Multipart 清理 worker
    gouploader.WithOrphanCleanup(24*time.Hour, 1*time.Hour),

    // 业务回调
    gouploader.WithOnUploadComplete(func(r *gouploader.UploadResult) {
        db.SaveFile(r.FileID, r.StorageKey, r.Checksum)
    }),
)
defer uploader.Close()

生产建议：无论是否启用 WithOrphanCleanup，都强烈建议在 Bucket 层面配置生命周期规则（AbortIncompleteMultipartUpload, 建议 7 天），做应用级 + 云级双保险。

配置选项

所有选项通过函数式选项传入 gouploader.New()：

uploader, err := gouploader.New(
    // 存储后端（三选一）
    gouploader.WithLocalStorage("./uploads"),
    // 或
    gouploader.WithS3Storage(gouploader.S3Config{...}),
    // 或
    gouploader.WithStorage(myCustomStorage),

    // 上传限制
    gouploader.WithMaxFileSize(10 << 30),                        // 10GB，默认 10GB
    gouploader.WithAllowedTypes(".jpg", ".png", ".mp4", ".pdf"), // 空=允许所有类型
    gouploader.WithHashAlgorithm("sha256"),                      // "md5" 或 "sha256"，默认 "sha256"

    // 分片设置
    gouploader.WithChunkTempDir("./tmp/chunks"),                 // 默认 "./tmp/chunks"
    gouploader.WithChunkSize(5<<20, 1<<20, 20<<20),             // 默认/最小/最大，默认 5MB/1MB/20MB
    gouploader.WithChunkSessionTTL(24 * time.Hour),              // 默认 24 小时
    gouploader.WithChunkCleanupInterval(1 * time.Hour),          // 默认 1 小时

    // STS 直传（可选，配置后启用前端直传云存储）
    gouploader.WithAliyunSTS(gouploader.AliyunSTSConfig{
        AccessKeyID:     "LTAI...",
        AccessKeySecret: "xxx",
        RoleArn:         "acs:ram::123456:role/oss-upload-role",
        OSSEndpoint:     "oss-cn-hangzhou.aliyuncs.com",
        Bucket:          "my-bucket",
        Region:          "cn-hangzhou",
    }),
    gouploader.WithOnDirectUploadComplete(func(result *gouploader.DirectUploadResult) {
        db.SaveDirectFile(result.Key, result.Size)
    }),

    // 回调
    gouploader.WithOnUploadComplete(func(result *gouploader.UploadResult) {
        // 每次上传成功后触发（普通上传和分片合并均触发）
        // 用途：存数据库、发通知、触发后续处理等
        db.SaveFile(result.FileID, result.FileName, result.StorageKey, result.Checksum)
    }),
)
选项参考

基础选项

选项 默认值 说明
WithLocalStorage(path) "./uploads" 本地磁盘存储
WithS3Storage(S3Config) - S3 兼容对象存储（MinIO / AWS）
WithStorage(Storage) - 自定义 Storage 实现（含子 module 的云 adapter）
WithMaxFileSize(bytes) 10GB 允许的最大文件大小
WithAllowedTypes(exts...) 全部 允许的文件扩展名
WithHashAlgorithm(algo) "sha256" 校验和算法
WithChunkTempDir(dir) "./tmp/chunks" 分片临时目录（代理路径用）
WithChunkSize(默认, 最小, 最大) 5MB/1MB/20MB 分片大小限制
WithChunkSessionTTL(duration) 24h 上传会话过期时间
WithChunkCleanupInterval(duration) 1h 过期会话清理间隔
WithOnUploadComplete(fn) - 上传完成回调（成功路径）
WithOnUploadInit(fn) - 会话初始化成功钩子（不含秒传命中）
WithOnUploadError(fn) - 任一阶段失败钩子（Stage 区分失败环节）
WithOnUploadAbort(fn) - 会话被中止钩子
WithOnInstantHit(fn) - 秒传命中钩子
WithPublicURLBuilder(fn) - 注入"对外可见 URL"拼装策略；所有上传完成路径回显到 result.URL（详见下文「上传完成 URL 回显」）

Multipart 直传 & 秒传选项

选项 默认值 说明
WithHashStore(HashStore) - 秒传索引存储（DB/Redis/自定义）。未注入时秒传关闭
WithHashStoreRegisterTimeout(d) 30s HashStore.Register 异步注册超时；HashStore 实现卡死时防止后台 goroutine 累积
WithMultipartThreshold(bytes) 100MB 走 Multipart 直传的最小文件大小
WithMultipartFeatureFlag(fn) - 按请求动态决定是否走 Multipart 路径（灰度用）
WithMultipartDisabled() - 强制关闭 Multipart 直传（降级/回滚用）
WithPartSignTTL(duration) 15min 单个 part 预签名 URL 有效期
WithUserIDFn(fn) →"anon" 从 Gin 上下文提取用户标识；配置后自动启用会话所有权校验
WithMultipartKeyPrefix(fn) 按日期 生成对象键前缀（建议加用户 ID 隔离）
WithOrphanCleanup(ttl, interval) - 启用悬挂 Multipart 清理 worker

S3 兼容存储

一套实现覆盖所有 S3 兼容服务，只需修改 Endpoint：

// MinIO
gouploader.WithS3Storage(gouploader.S3Config{
    Endpoint:  "127.0.0.1:9000",
    AccessKey: "minioadmin",
    SecretKey: "minioadmin",
    Bucket:    "uploads",
    UseSSL:    false,
})

// 阿里云 OSS
gouploader.WithS3Storage(gouploader.S3Config{
    Endpoint:  "oss-cn-hangzhou.aliyuncs.com",
    AccessKey: "your-access-key",
    SecretKey: "your-secret-key",
    Bucket:    "my-bucket",
    Region:    "oss-cn-hangzhou",
    UseSSL:    true,
})

// 腾讯云 COS
gouploader.WithS3Storage(gouploader.S3Config{
    Endpoint:  "cos.ap-guangzhou.myqcloud.com",
    AccessKey: "your-access-key",
    SecretKey: "your-secret-key",
    Bucket:    "my-bucket-1250000000",
    Region:    "ap-guangzhou",
    UseSSL:    true,
})

// 华为云 OBS
gouploader.WithS3Storage(gouploader.S3Config{
    Endpoint:  "obs.cn-north-4.myhuaweicloud.com",
    AccessKey: "your-access-key",
    SecretKey: "your-secret-key",
    Bucket:    "my-bucket",
    Region:    "cn-north-4",
    UseSSL:    true,
})

// AWS S3
gouploader.WithS3Storage(gouploader.S3Config{
    Endpoint:  "s3.us-east-1.amazonaws.com",
    AccessKey: "AKIAIOSFODNN7EXAMPLE",
    SecretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    Bucket:    "my-bucket",
    Region:    "us-east-1",
    UseSSL:    true,
})

自定义存储

实现 Storage 接口即可对接任意后端：

type Storage interface {
    Save(ctx context.Context, key string, reader io.Reader, size int64) error
    Get(ctx context.Context, key string) (io.ReadCloser, error)
    Delete(ctx context.Context, key string) error
    Exists(ctx context.Context, key string) (bool, error)
}

uploader, _ := gouploader.New(
    gouploader.WithStorage(myFTPStorage),
)

跨域配置

内置 CORS 中间件，支持前端跨域请求：

group := r.Group("/api/v1/upload")
group.Use(gouploader.CORS(gouploader.CORSConfig{
    AllowOrigins:     []string{"https://your-frontend.com"},
    AllowCredentials: true,
}))
uploader.RegisterRoutes(group)

路由注册

自动注册（推荐）
uploader.RegisterRoutes(r.Group("/api/v1/upload"))

注册以下路由：

方法 路径 使用路径 说明
POST /api/v1/upload - 普通单文件上传
POST /api/v1/upload/chunk/init 全部 初始化分片上传（响应含 upload_path 指示路径）
POST /api/v1/upload/chunk/resume 全部 秒传 + 断点续传查询（按 file_hash 查找）
POST /api/v1/upload/chunk proxy 上传单个分片（multipart/form-data）
GET /api/v1/upload/chunk/status/:upload_id proxy 查询上传进度（断点续传）
POST /api/v1/upload/chunk/merge/:upload_id proxy 合并所有分片
POST /api/v1/upload/chunk/parts/sign multipart 按需签发一组 part 的预签名 URL
POST /api/v1/upload/chunk/parts/report multipart 客户端上报单片 PUT 成功后的 ETag
POST /api/v1/upload/chunk/complete multipart 合并分片（携带全部 parts + ETag）
DELETE /api/v1/upload/chunk/:upload_id 全部 中止（Multipart 路径同时 Abort 云端）

如果配置了 STS 直传，还会注册：

方法 路径 说明
POST /api/v1/upload/direct/token 签发 STS 临时凭证
POST /api/v1/upload/direct/complete 前端确认上传完成
POST /api/v1/upload/direct/callback 云存储回调（仅当 Provider 实现了 CallbackVerifier 时注册，详见下文「云存储回调验签」）
手动注册（搭配自定义中间件）
auth := myAuthMiddleware()

r.POST("/upload",                        auth, uploader.HandleUpload())
r.POST("/upload/chunk/init",             auth, uploader.HandleChunkInit())
r.POST("/upload/chunk",                  auth, uploader.HandleChunkUpload())
r.GET("/upload/chunk/status/:upload_id", auth, uploader.HandleChunkStatus())
r.POST("/upload/chunk/merge/:upload_id", auth, uploader.HandleChunkMerge())
r.DELETE("/upload/chunk/:upload_id",     auth, uploader.HandleChunkAbort())

接口文档

普通上传

POST /api/v1/upload — multipart/form-data

字段 类型 必填 说明
file file 是 要上传的文件
checksum string 否 期望的文件哈希值
algorithm string 否 哈希算法：md5 或 sha256

响应：

{
  "code": 0,
  "message": "ok",
  "data": {
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_name": "photo.jpg",
    "file_size": 1048576,
    "storage_key": "2026/04/09/550e8400-e29b-41d4-a716-446655440000.jpg",
    "checksum": "a1b2c3d4...",
    "url": "https://static.example.com/2026/04/09/550e8400-e29b-41d4-a716-446655440000.jpg"
  }
}

url 字段在配置 WithPublicURLBuilder 后填充，未配置时不输出（适用于所有上传完成路径）。

分片上传 — 初始化

POST /api/v1/upload/chunk/init — application/json

{
  "file_name": "video.mp4",
  "file_size": 1073741824,
  "chunk_size": 5242880,
  "checksum": "整个文件的sha256",
  "algorithm": "sha256"
}

响应（按命中路径不同）：

// 普通代理 / Multipart 直传：基础字段
{
  "code": 0,
  "data": {
    "upload_id": "550e8400-...",
    "chunk_size": 5242880,
    "total_chunks": 205,
    "upload_path": "proxy"          // 或 "multipart"
  }
}

// 秒传命中：instant=true，前端无需上传
{
  "code": 0,
  "data": {
    "instant": true,
    "upload_path": "instant",
    "storage_key": "2026/04/09/abc.jpg",
    "file_id": "...",
    "url": "https://static.example.com/2026/04/09/abc.jpg"  // 配置 WithPublicURLBuilder 后填充
  }
}

// Multipart 直传额外字段（upload_path=multipart 时）：
//   "part_urls": { "1": "<presigned-url>", "2": "...", ... }
//   "part_sign_ttl": 900
//   "recommend_concurrency": 6
分片上传 — 上传分片

POST /api/v1/upload/chunk — multipart/form-data

重要： upload_id 和 chunk_index 字段必须在 chunk 字段之前。

字段 类型 必填 说明
upload_id string 是 初始化返回的会话 ID
chunk_index int 是 分片索引（从 0 开始）
chunk_checksum string 否 该分片的哈希值
chunk file 是 分片二进制数据

响应：

{
  "code": 0,
  "data": {
    "upload_id": "550e8400-...",
    "chunk_index": 3,
    "uploaded_count": 4,
    "total_chunks": 205
  }
}
分片上传 — 查询状态（断点续传）

GET /api/v1/upload/chunk/status/:upload_id

响应：

{
  "code": 0,
  "data": {
    "upload_id": "550e8400-...",
    "total_chunks": 205,
    "uploaded_chunks": [0, 1, 2, 3, 7, 8],
    "missing_chunks": [4, 5, 6, 9, 10, 11]
  }
}
分片上传 — 合并

POST /api/v1/upload/chunk/merge/:upload_id（代理路径） POST /api/v1/upload/chunk/complete（Multipart 直传路径，body 携带 parts + ETag）

响应（两条路径字段一致）：

{
  "code": 0,
  "data": {
    "file_id": "f17c99c7-...",
    "file_name": "video.mp4",
    "file_size": 1073741824,
    "storage_key": "2026/04/09/f17c99c7-....mp4",
    "checksum": "a1b2c3d4...",
    "url": "https://static.example.com/2026/04/09/f17c99c7-....mp4"
  }
}
分片上传 — 中止

DELETE /api/v1/upload/chunk/:upload_id

响应：

{
  "code": 0,
  "message": "ok"
}
分片上传 — 秒传 / 断点续传查询

POST /api/v1/upload/chunk/resume — application/json

{
  "file_hash": "整个文件的sha256",
  "algorithm": "sha256",
  "file_size": 1073741824
}

响应分三种：

// 秒传命中
{
  "code": 0,
  "data": {
    "instant": true,
    "storage_key": "2026/04/09/abc.mp4",
    "file_id": "...",
    "url": "https://static.example.com/2026/04/09/abc.mp4"  // 配置 WithPublicURLBuilder 后填充
  }
}

// 找到未完成 session（断点续传）
{
  "code": 0,
  "data": {
    "upload_id": "550e8400-...",
    "upload_path": "proxy",
    "total_chunks": 205,
    "uploaded_parts": [0, 1, 2, ...],
    "missing_parts": [50, 51, 52, ...]
  }
}

// 都未命中（前端走正常 /chunk/init）
{ "code": 0, "data": {} }
前端直传 — 获取 STS 凭证

POST /api/v1/upload/direct/token — application/json

{
  "file_name": "photo.jpg",
  "file_size": 1048576
}

响应：

{
  "code": 0,
  "data": {
    "access_key_id": "STS.xxx",
    "access_key_secret": "xxx",
    "security_token": "xxx",
    "expiration": "2026-04-09T02:00:00Z",
    "region": "cn-hangzhou",
    "bucket": "my-bucket",
    "endpoint": "oss-cn-hangzhou.aliyuncs.com",
    "key_prefix": "direct/2026/04/09/",
    "key": "direct/2026/04/09/550e8400-....jpg"
  }
}
前端直传 — 确认完成

POST /api/v1/upload/direct/complete — application/json

{
  "key": "direct/2026/04/09/550e8400-....jpg",
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
}

响应：

{
  "code": 0,
  "data": {
    "bucket": "my-bucket",
    "key": "direct/2026/04/09/550e8400-....jpg",
    "size": 1048576,
    "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
    "url": "https://static.example.com/direct/2026/04/09/550e8400-....jpg"
  }
}
前端直传 — 云存储回调

POST /api/v1/upload/direct/callback — 由云厂商上报；只在 STSProvider 实现了 CallbackVerifier 时注册。

由云存储直接调用，不是前端调用。验签算法因厂商而异（OSS RSA / OBS HMAC-SHA256 / COS Token），详见 云存储回调验签。

响应字段与 /direct/complete 一致，url 字段在配置 WithPublicURLBuilder 后填充。

错误响应

所有错误遵循统一格式：

{
  "code": 10001,
  "message": "文件超过大小限制",
  "details": "最大允许: 10737418240 字节"
}
错误码 HTTP 状态码 说明
10001 413 文件超过大小限制
10002 400 文件类型不允许
10003 400 校验和不匹配
10005 400 参数无效
10006 400 multipart 解析错误
20001 404 上传会话不存在
20002 410 上传会话已过期
20003 400 分片索引越界
20005 400 分片校验和不匹配
20006 409 分片未全部上传
20007 500 合并后文件校验失败
30001 500 存储写入失败
30002 500 存储读取失败
40001 503 STS 直传未配置
40002 500 STS 凭证签发失败
40003 403 回调验签失败
40004 404 直传文件不存在
50001 501 当前存储不支持 Multipart 直传
50002 500 云端 Multipart 初始化失败
50003 500 预签名 URL 生成失败
50004 500 云端 Multipart 合并失败
50005 500 云端 Multipart 中止失败
50006 400 服务端二次校验 parts 失败
50007 400 客户端上报 ETag 与云端不一致
50008 403 无权访问该会话（身份 ≠ session.UserID）

前端对接

普通上传（JavaScript）
async function uploadFile(file) {
  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch('/api/v1/upload', {
    method: 'POST',
    body: formData,
  });
  return response.json();
}
分片断点续传（JavaScript）
const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB

async function uploadLargeFile(file) {
  // 第一步：计算文件哈希（可选，用于完整性校验）
  const checksum = await calculateSHA256(file);

  // 第二步：初始化上传会话
  const initRes = await fetch('/api/v1/upload/chunk/init', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      file_name: file.name,
      file_size: file.size,
      chunk_size: CHUNK_SIZE,
      checksum: checksum,
      algorithm: 'sha256',
    }),
  }).then(r => r.json());

  const { upload_id, total_chunks } = initRes.data;

  // 第三步：查询已上传的分片（用于断点续传）
  const statusRes = await fetch(`/api/v1/upload/chunk/status/${upload_id}`)
    .then(r => r.json());
  const missingChunks = statusRes.data.missing_chunks;

  // 第四步：并发上传缺失的分片
  const CONCURRENCY = 3;
  const queue = [...missingChunks];

  async function uploadWorker() {
    while (queue.length > 0) {
      const index = queue.shift();
      const start = index * CHUNK_SIZE;
      const end = Math.min(start + CHUNK_SIZE, file.size);
      const blob = file.slice(start, end);

      const formData = new FormData();
      formData.append('upload_id', upload_id);
      formData.append('chunk_index', String(index));
      formData.append('chunk', blob);

      const res = await fetch('/api/v1/upload/chunk', {
        method: 'POST',
        body: formData,
      }).then(r => r.json());

      console.log(`分片 ${index}/${total_chunks} 完成，共 ${res.data.uploaded_count} 片`);
    }
  }

  await Promise.all(Array.from({ length: CONCURRENCY }, () => uploadWorker()));

  // 第五步：合并
  const mergeRes = await fetch(`/api/v1/upload/chunk/merge/${upload_id}`, {
    method: 'POST',
  }).then(r => r.json());

  console.log('上传完成:', mergeRes.data);
  return mergeRes.data;
}
Multipart 直传（方案 A，JavaScript，统一协议）

前端通用逻辑——根据 /chunk/init 返回的 upload_path 自动分流，支持三种情形：秒传 / 代理 / 直传。前端零耦合云厂商。

async function smartUpload(file) {
  // 1. 计算整文件哈希（支持秒传和断点续传）
  const fileHash = await sha256(file);

  // 2. 查询秒传 + 断点续传
  const resume = await fetch('/api/v1/upload/chunk/resume', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ file_hash: fileHash, file_name: file.name, file_size: file.size }),
  }).then(r => r.json()).then(r => r.data);

  if (resume.instant) {
    console.log('秒传命中！', resume.storage_key);
    return resume;
  }

  let upload_id = resume.upload_id;
  let upload_path = resume.upload_path;
  let total_chunks = resume.total_chunks;
  let part_urls = null;
  let uploaded = resume.uploaded_parts || [];

  // 3. 未命中 resume 则走 init
  if (!upload_id) {
    const init = await fetch('/api/v1/upload/chunk/init', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        file_name: file.name,
        file_size: file.size,
        file_hash: fileHash,
        algorithm: 'sha256',
      }),
    }).then(r => r.json()).then(r => r.data);

    if (init.instant) return init;  // init 也会触发秒传

    upload_id = init.upload_id;
    upload_path = init.upload_path;
    total_chunks = init.total_chunks;
    part_urls = init.part_urls;
  }

  // 4. 分流：proxy 走 POST，multipart 走 PUT
  if (upload_path === 'multipart') {
    return uploadViaMultipart(file, upload_id, total_chunks, part_urls, uploaded);
  }
  return uploadViaProxy(file, upload_id, total_chunks, uploaded);
}

// ——————— Multipart 直传实现 ———————
async function uploadViaMultipart(file, upload_id, total_chunks, part_urls, uploadedSet) {
  const chunkSize = Math.ceil(file.size / total_chunks);
  const partEtags = [];
  const uploadedSetObj = new Set(uploadedSet);

  // 按需签名：首批 URL 由 init 下发，后续批次调 /chunk/parts/sign
  async function urlFor(partNum) {
    if (part_urls && part_urls[partNum]) return part_urls[partNum];
    const batch = [];
    for (let i = partNum; i < Math.min(partNum + 10, total_chunks + 1); i++) batch.push(i);
    const res = await fetch('/api/v1/upload/chunk/parts/sign', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ upload_id, part_numbers: batch }),
    }).then(r => r.json()).then(r => r.data);
    part_urls = { ...part_urls, ...res.urls };
    return part_urls[partNum];
  }

  // 并发 PUT（前端自控并发度）
  const CONCURRENCY = 6;
  const tasks = [];
  for (let n = 1; n <= total_chunks; n++) {
    if (uploadedSetObj.has(n - 1)) continue;  // 断点续传：跳过已传
    tasks.push(n);
  }
  const results = {};
  await Promise.all(
    Array.from({ length: CONCURRENCY }, async () => {
      while (tasks.length) {
        const n = tasks.shift();
        const url = await urlFor(n);
        const start = (n - 1) * chunkSize;
        const end = Math.min(start + chunkSize, file.size);
        const blob = file.slice(start, end);
        const resp = await fetch(url, { method: 'PUT', body: blob });
        const etag = resp.headers.get('ETag');
        results[n] = etag;
        // 上报 ETag（可选——Complete 时也会带）
        fetch('/api/v1/upload/chunk/parts/report', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ upload_id, part_num: n, etag }),
        });
      }
    })
  );

  // Complete 合并
  const parts = Object.keys(results).map(n => ({ part_num: +n, etag: results[n] })).sort((a, b) => a.part_num - b.part_num);
  return fetch('/api/v1/upload/chunk/complete', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ upload_id, parts }),
  }).then(r => r.json()).then(r => r.data);
}

// ——————— 代理路径（沿用旧协议） ———————
async function uploadViaProxy(file, upload_id, total_chunks, uploadedSet) {
  // ... 参见 "分片断点续传（JavaScript）" 节
}
前端直传云存储（JavaScript）
async function directUpload(file) {
  // 第一步：从后端获取 STS 临时凭证
  const tokenRes = await fetch('/api/v1/upload/direct/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      file_name: file.name,
      file_size: file.size,
    }),
  }).then(r => r.json());

  const { access_key_id, access_key_secret, security_token, endpoint, bucket, key } = tokenRes.data;

  // 第二步：直传到云存储（以阿里云 OSS 为例）
  const ossUrl = `https://${bucket}.${endpoint}/${key}`;
  await fetch(ossUrl, {
    method: 'PUT',
    headers: {
      'Authorization': '...', // 使用 STS 凭证签名（建议使用阿里云 OSS JS SDK）
      'x-oss-security-token': security_token,
    },
    body: file,
  });

  // 第三步：通知后端上传完成
  const completeRes = await fetch('/api/v1/upload/direct/complete', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ key }),
  }).then(r => r.json());

  console.log('直传完成:', completeRes.data);
  return completeRes.data;
}

分片上传流程

前端                                  后端
 |                                     |
 |-- POST /chunk/init --------------->|  创建会话，返回 upload_id
 |<-- { upload_id, total_chunks } ----|
 |                                     |
 |-- POST /chunk（并发 x N）---------->|  流式写入每个分片到磁盘
 |   { upload_id, chunk_index, data } |  校验分片哈希
 |<-- { uploaded_count } -------------|  标记分片已上传（幂等）
 |                                     |
 |   （网络中断、应用重启）              |
 |                                     |
 |-- GET /chunk/status/:id ---------->|  返回已上传和缺失的分片列表
 |<-- { missing_chunks: [4,5,6] } ----|
 |                                     |
 |-- POST /chunk（仅缺失分片）-------->|  只补传断开的部分
 |                                     |
 |-- POST /chunk/merge/:id ---------->|  流式合并所有分片
 |                                     |  校验最终文件哈希
 |<-- { storage_key, checksum } ------|  清理临时数据

前端直传流程

前端                                后端                        云存储
 |                                   |                            |
 |-- POST /direct/token ----------->|                            |
 |   { file_name, file_size }       | 生成 keyPrefix + key       |
 |                                   | 调用 STSProvider 签发凭证  |
 |<-- { credential, key } ----------|                            |
 |                                   |                            |
 |-- PUT 直传到云存储 ------------------------------------------>|
 |   使用 STS 临时凭证签名            |                            |
 |<-- 200 OK ---------------------------------------------------|
 |                                   |                            |
 |-- POST /direct/complete -------->|                            |
 |   { key }                         | 验证文件存在               |
 |                                   | 触发 onDirectUploadComplete|
 |<-- { key, etag } ----------------|                            |

项目结构

gouploader/                       主 module (零云 SDK 依赖)
├── gouploader.go                 # 入口：Uploader + New() + RegisterRoutes()
├── options.go                  # 函数式选项：WithXxx()
├── storage.go                  # Storage 接口（公共类型）
├── model.go                    # 请求/响应类型（公共类型）
├── errors.go                   # 错误码（公共类型）
├── cors.go                     # CORS 中间件
├── docs/
│   └── ARCHITECTURE.md         # 架构设计 + 生产级维度
├── internal/
│   ├── types/
│   │   ├── storage.go          # Storage 接口
│   │   ├── multipart.go        # MultipartStorage 扩展接口
│   │   ├── hashstore.go        # HashStore 接口（秒传）
│   │   ├── errors.go           # 错误类型 + 错误码
│   │   ├── model.go            # 数据传输对象
│   │   ├── sts.go              # STS 凭证 & Provider
│   │   └── sanitize.go         # 目录穿越防护
│   ├── hash/                   # 流式 MD5/SHA256 计算
│   ├── response/               # 统一 JSON 响应
│   ├── chunk/
│   │   ├── store.go            # ChunkStore 接口 + HashIndex 扩展接口
│   │   └── filestore.go        # 文件系统实现
│   ├── store/
│   │   ├── local.go            # 本地磁盘存储
│   │   └── s3.go               # S3 兼容存储（MinIO / AWS）
│   ├── service/
│   │   ├── upload.go           # 普通上传业务逻辑
│   │   ├── chunk_upload.go     # 分片上传（自动分流 proxy / multipart）
│   │   ├── direct_upload.go    # STS 直传业务逻辑
│   │   └── orphan_cleaner.go   # 悬挂 Multipart 清理 worker
│   ├── handler/
│   │   ├── upload.go           # 普通上传 Gin 处理器
│   │   ├── chunk_upload.go     # 分片上传 Gin 处理器
│   │   └── direct_upload.go    # STS 直传 Gin 处理器
│   └── sts/                    # 各家 STS Provider 实现
│       ├── aliyun.go / tencent.go / huawei.go / aws.go
│
# —— 以下为独立子 module，按需引入 ——
├── aliyun/                       独立 module: github.com/gtkit/gouploader/aliyun
│   ├── go.mod                  # 依赖 aliyun-oss-go-sdk（用户开通后再拉）
│   └── aliyun.go               # Storage + MultipartStorage 实现
├── tencent/                      独立 module: github.com/gtkit/gouploader/tencent
└── huawei/                       独立 module: github.com/gtkit/gouploader/huawei

依赖隔离：只用阿里云时，go.mod 只会拉 aliyun-oss-go-sdk，其他云 SDK 不进依赖图。

设计决策

内存安全
  • 所有 Handler 使用 multipart.NewReader() 而非 c.FormFile()，避免 Gin 默认的 32MB 内存缓冲
  • io.TeeReader 在流式传输的同时计算哈希——无需二次读取
  • io.LimitReader 在 I/O 层面强制文件/分片大小限制
  • io.MultiReader 合并分片时不将其加载到内存
  • 表单字段读取限制为 1KB，防止内存耗尽攻击
并发安全
  • 每个 Session 有 sync.Mutex 保护元数据更新（亚毫秒级持锁）
  • sync.Map 缓存活跃会话，避免每次分片上传都读磁盘
  • 分片数据文件按索引命名——不同分片的并行写入互不冲突
  • 唯一临时文件名（通过 atomic.Int64）防止同一分片的覆盖竞态
  • 分片上传幂等——重复上传已存在的分片直接返回成功
可靠性
  • 所有文件写入使用 写临时文件 + fsync + rename 实现原子性
  • 合并操作幂等——失败重试返回相同结果
  • 合并失败时保留会话，分片不会丢失
  • 过期会话由后台协程自动清理

生命周期钩子

基于"库只暴露事件、业务自己决定怎么用"的原则，提供 5 个钩子覆盖全部关键事件。你可以基于这些钩子自行接入 Prometheus / 审计库 / 告警通道，库本身不依赖任何监控框架。

钩子触发表
钩子 触发时机 Payload
OnUploadComplete 普通上传 / 代理合并 / Multipart 合并 成功后 *UploadResult
OnUploadInit 会话初始化成功后（proxy 或 multipart）；秒传命中时不触发 *UploadInitEvent
OnUploadError 任一阶段失败（init / part / merge / complete / abort） *UploadErrorEvent（含 Stage）
OnUploadAbort 客户端 DELETE /chunk/:id 清理完 session 后 *UploadAbortEvent
OnInstantHit HashStore 命中、秒传成功 *InstantHitEvent
Stage 常量（用于 UploadErrorEvent.Stage）
常量 对应阶段
StageInit 会话初始化（参数校验 / 云端 InitMultipart）
StagePart 分片上传（代理 POST 或直传 Report ETag）
StageMerge 代理合并（本地分片 → 最终对象）
StageComplete 直传 Complete（云端 CompleteMultipart）
StageAbort 中止阶段（云端 Abort 失败）
使用示例
uploader, _ := gouploader.New(
    gouploader.WithStorage(storage),

    // 会话初始化 → 审计埋点
    gouploader.WithOnUploadInit(func(ctx context.Context, ev *gouploader.UploadInitEvent) {
        audit.Record(ctx, "upload_init", ev.UserID, ev.UploadID, ev.FileSize)
    }),

    // 失败 → Prometheus counter
    gouploader.WithOnUploadError(func(ctx context.Context, ev *gouploader.UploadErrorEvent) {
        metrics.UploadErrors.
            WithLabelValues(ev.Stage, ev.UserID).
            Inc()
    }),

    // 中止 → 回收业务配额
    gouploader.WithOnUploadAbort(func(ctx context.Context, ev *gouploader.UploadAbortEvent) {
        quota.Refund(ctx, ev.UserID, ev.UploadID)
    }),

    // 秒传命中 → 流量节省统计
    gouploader.WithOnInstantHit(func(ctx context.Context, ev *gouploader.InstantHitEvent) {
        metrics.BytesSavedByInstant.Add(float64(ev.FileSize))
    }),

    // 成功 → 存文件元数据
    gouploader.WithOnUploadComplete(func(r *gouploader.UploadResult) {
        db.SaveFile(r)
    }),
)
关键约束
  • 同步调用：钩子返回后主流程才继续。要异步处理请在钩子内 go func(){...}()
  • 要轻量：钩子里做阻塞 I/O 会拖慢上传 RT
  • Panic 会被隔离：钩子内 panic 被 recover + 打 Error 日志，不影响上传。但别依赖这个兜底——发现 钩子 panic 已被隔离 日志要马上修
  • 可选：不配置任何钩子时行为等价于未引入钩子机制前的版本

上传完成 URL 回显

业务方注入 WithPublicURLBuilder 后，所有上传完成路径返回的 result（包括钩子 payload 与 HTTP JSON 响应）的 URL 字段会被自动填充。

覆盖路径：

HTTP 说明 字段
POST / 普通上传 data.url
POST /chunk/merge/:upload_id 代理分片合并 data.url
POST /chunk/complete Multipart 直传合并 data.url
POST /chunk/init 秒传命中（Instant=true 时） data.url
POST /chunk/resume 秒传命中 data.url
POST /direct/complete STS 直传完成 data.url
POST /direct/callback 云存储回调 data.url 
gouploader.New(
    gouploader.WithStorage(storage),
    // 简单 CDN 前缀拼接
    gouploader.WithPublicURLBuilder(func(key string) string {
        return "https://static.example.com/" + key
    }),
)

私有 bucket 临时签 URL（业务自行调云 SDK，注意 builder 应保持轻量）：

gouploader.WithPublicURLBuilder(func(key string) string {
    url, _ := storage.GetSignedGetURL(context.Background(), key, 15*time.Minute)
    return url
})

不配置时所有 result.URL 字段为空字符串，JSON 因 omitempty 不输出，行为等价于未引入此特性的旧版本。

builder 内 panic 被 recover 隔离，不影响主流程；但 URL 字段会为空，并打 Error 日志 PublicURLBuilder panic 已隔离。

生产部署须知

上线前请逐项确认：

🔴 会话所有权授权

本包通过 WithUserIDFn 自动启用会话所有权校验。启用后，以下端点在请求身份 ≠ session 创建者时返回 HTTP 403 + CodeUnauthorized (50008)：

  • POST /chunk · GET /chunk/status/:id · POST /chunk/merge/:id
  • POST /chunk/complete · POST /chunk/parts/sign · POST /chunk/parts/report
  • DELETE /chunk/:id
gouploader.WithUserIDFn(func(c *gin.Context) string {
    return c.GetString("user_id")  // 由业务中间件注入
})

不配置 WithUserIDFn 等于关闭授权保护。对外服务务必配置。

🔴 云存储回调验签

POST /direct/callback 端点接收云厂商上报的"上传完成"回调。未启用验签时，攻击者可伪造回调写入任意元数据——必须按以下方式启用：

厂商 算法 启用方式
阿里云 OSS RSA + MD5 PKCS1v15 调用 WithAliyunSTS(cfg) 即自动启用，公钥 URL 严格校验白名单
华为云 OBS HMAC-SHA256（密钥 SecretAccessKey） 调用 WithHuaweiSTS(cfg) 即自动启用
腾讯云 COS Token + IP 白名单（COS 无 RSA 链路） WithTencentSTS(cfg) 时必须配置 cfg.CallbackToken（≥32 字节随机）

腾讯云配置示例：

gouploader.WithTencentSTS(gouploader.TencentSTSConfig{
    SecretId:           "AKID...",
    SecretKey:          "...",
    Region:             "ap-guangzhou",
    Bucket:             "my-bucket-1250000000",
    AppId:              "1250000000",
    // 必须：用足够熵的随机串作为回调共享密钥
    CallbackToken:      "your-32+-byte-random-token",
    // 可选：进一步限制回调来源 IP / CIDR
    CallbackAllowedIPs: []string{"43.128.0.0/16"},
})

通过控制台配置 COS 回调时，把 CallbackToken 透传到回调 body 模板的 callback_token 字段（或通过 X-Callback-Token 请求头），服务端 constant-time 比对。

回调消息体统一使用以下 JSON 格式（在云厂商控制台的回调模板里配置）：

{"bucket":"${bucket}","object":"${object}","size":${size},"etag":${etag}}

object 与 key 字段任一非空即可。

🔴 单实例部署限制

默认 FileStore 基于本地文件系统，不支持多实例水平扩展：分片 session 存在本地磁盘，节点间不共享。

多实例场景（两种方案）：

  1. 粘性路由（最简单）：负载均衡按 upload_id 一致性哈希，同一 session 始终路由到同一节点
  2. 注入分布式 Store（更弹性）：实现 chunk.Store 接口对接 Redis / etcd，通过 WithStorage 相关机制注入

单实例环境（如 K8s 单 Pod、单机部署）可直接用默认 FileStore。

🔴 AWS S3 的 chunkSize 要求

AWS S3 Multipart 规则：最小分片 5 MiB（最后一片除外）。本包默认 ChunkMinSize=1MB 对 AWS S3 不够，用户选 AWS 时必须显式配置：

gouploader.WithChunkSize(5<<20, 5<<20, 100<<20) // 默认/最小/最大 = 5/5/100 MiB

阿里 OSS（100KB）/腾讯 COS（1MB）/华为 OBS（100KB）默认配置可用，但建议至少 5MB 以减少分片数。

🟡 钩子的 Context 生命周期

钩子回调收到的 ctx 是 HTTP 请求的 ctx，请求结束后立即 cancel。钩子内若需异步处理（DB 写入、发 MQ）：

gouploader.WithOnUploadComplete(func(r *gouploader.UploadResult) {
    go func() {
        // ❌ 错误：主请求已结束，ctx 已 cancel
        // db.Save(origCtx, r)

        // ✅ 正确：新建独立 ctx
        bgCtx := context.Background()
        db.Save(bgCtx, r)
    }()
})

Go 1.21+ 还可以用 context.WithoutCancel(origCtx) 保留 trace_id 等 value 但移除 cancel 信号。

🟡 HashStore 实现约束

秒传命中时本包已内置 fileSize 一致性校验（hit.FileSize ≠ req.FileSize 时视为未命中），防止 hash 冲突攻击。业务方实现 HashStore.LookupByHash 时：

  • 返回准确的 FileSize — 不能返回 0 或估算值
  • 对象删除后及时同步删除索引条目 — 防止返回已被删除的 StorageKey
🟢 悬挂 Multipart 清理

应用内已有 WithOrphanCleanup，但仍建议在云 Bucket 层面配置生命周期规则兜底（应用挂了时兜底）。参见各子 module 的 README。

优雅关闭

使用完毕后必须调用 Close() 以停止后台清理协程（包括悬挂 Multipart 清理 worker）：

uploader, _ := gouploader.New(...)
defer uploader.Close()

生产级落地清单

本包在设计上覆盖以下六大维度的生产级考量（🔴 必做 / 🟡 应做 / 🟢 可选）。完整说明见 docs/ARCHITECTURE.md。

可靠性
  • 🔴 秒传：整文件哈希索引（WithHashStore）
  • 🔴 断点续传：/chunk/resume 按 hash 找回未完成会话
  • 🔴 悬挂 Multipart 清理：WithOrphanCleanup + Bucket 生命周期规则双保险
  • 🟡 Complete 二次校验：调云端 ListParts 比对客户端上报 ETag，防伪造
  • 🟡 失败可恢复：合并失败不删 session，支持重试
安全
  • 🔴 预签名 URL 参数锁死：签名时固定 partNum + Content-Length（各 adapter 实现）
  • 🔴 按需签名：/chunk/parts/sign 滑动窗口签发，降低 URL 泄漏影响
  • 🔴 keyPrefix 强隔离：WithUserIDFn + WithMultipartKeyPrefix 按用户隔离对象键
  • 🟡 MIME sniffing：Complete 后可在业务回调中跑 http.DetectContentType
  • 🟡 病毒扫描 hook：OnUploadComplete 中异步触发扫描
性能
  • 🟡 客户端自适应 partSize：/chunk/init 返回 recommend_concurrency，前端测速后调整
  • 🟡 并发窗口：前端 PUT 限流（默认 6）
  • 🟢 单 part 失败重试：前端重签 URL + 指数退避
可观测性
  • 🔴 Prometheus metrics 接入点：service/chunk_upload.go 关键路径都有结构化日志
  • 🔴 结构化日志：zap with upload_id / cloud_upload_id / key
  • 🟡 审计日志：通过 WithOnUploadComplete 钩子落独立 audit 表
  • 🟡 慢请求告警：单 part > 10s 打告警
成本
  • 🔴 悬挂清理双保险：应用 worker + Bucket 生命周期规则
  • 🟡 秒传命中率监控：HashStore.LookupByHash 返回值可埋点
UX & 运维
  • 🔴 Feature Flag 灰度：WithMultipartFeatureFlag 按请求分流
  • 🟡 接口版本化预留：主包 Version 常量；路由可在 group prefix 加 /v1/
  • 🟢 WebSocket 进度推送：OnUploadComplete 中主动推

版本与迭代

当前版本已完成 M1（最小可用生产版）的全部核心工作：

  • ✅ 主 module：接口/协议/调度/灰度/秒传/清理 worker 全部就绪
  • ✅ aliyun/：完整对接 aliyun-oss-go-sdk，Storage + MultipartStorage + 单元测试 + E2E
  • ✅ tencent/：完整对接 cos-go-sdk-v5，Storage + MultipartStorage + 单元测试 + E2E
  • ✅ huawei/：完整对接 huaweicloud-sdk-go-obs，Storage + MultipartStorage + 单元测试 + E2E

三家 adapter 使用 SDK 自家签名（非 minio-go 的 S3 V4 通用层），解决了 OBS 部分 region 签名不兼容、OSS Callback 丢失、COS 元数据 header 被改写等已知兼容性问题。

下一步 M2（可选增强）：Prometheus metrics 接入、审计日志落库、MIME sniffing、跨厂商迁移工具等。详细路线图见 docs/ARCHITECTURE.md 第 6 节。

各 adapter 的 E2E 验证
# 阿里云
OSS_ENDPOINT=... OSS_BUCKET=... OSS_AK=... OSS_SK=... \
    go test -v -run TestIntegration ./aliyun/...

# 腾讯云
COS_BUCKET_URL=... COS_SECRET_ID=... COS_SECRET_KEY=... \
    go test -v -run TestIntegration ./tencent/...

# 华为云
OBS_ENDPOINT=... OBS_BUCKET=... OBS_AK=... OBS_SK=... \
    go test -v -run TestIntegration ./huawei/...

许可证

MIT

Documentation

Overview

Package gouploader 提供生产级文件上传工具包，适用于 Gin 框架。

功能特性：

  • 普通单文件上传（流式传输，内存恒定）
  • 分片上传，支持断点续传
  • 秒传（基于文件哈希索引，需注入 HashStore）
  • 云原生 Multipart 直传（需使用 aliyun/tencent/huawei 子 module 的 Storage 实现）
  • STS 前端直传（客户端使用云厂商 JS SDK 直连云端）
  • 可插拔存储：本地磁盘、S3 兼容（MinIO/AWS S3）、各云厂商（独立子 module）
  • 文件完整性校验（MD5/SHA256）、并发安全、流式 I/O

快速开始（代理路径，最简）： 

uploader, err := gouploader.New(
    gouploader.WithLocalStorage("./uploads"),
)
uploader.RegisterRoutes(r.Group("/api/v1/upload"))

生产场景（Multipart 直传 + 秒传 + 灰度）： 

import "github.com/gtkit/gouploader/aliyun"

ossStorage, _ := aliyun.NewStorage(aliyun.Config{...})
uploader, _ := gouploader.New(
    gouploader.WithStorage(ossStorage),
    gouploader.WithHashStore(myHashStore),
    gouploader.WithMultipartThreshold(100 << 20),
    gouploader.WithMultipartFeatureFlag(gradualRollout),
    gouploader.WithOrphanCleanup(24*time.Hour, 1*time.Hour),
)
Example (Basic)

Example_basic demonstrates the simplest usage with local storage. 

package main

import (
	"fmt"
	"log"

	"github.com/gin-gonic/gin"
	"github.com/gtkit/gouploader"
)

func main() {
	r := gin.Default()

	uploader, err := gouploader.New(
		gouploader.WithLocalStorage("./uploads"),
	)
	if err != nil {
		log.Fatal(err)
	}

	uploader.RegisterRoutes(r.Group("/api/v1/upload"))
	defer uploader.Close()
	// r.Run(":8080")
	fmt.Println("routes registered")
}

Output:
routes registered
Example (CustomRoutes)

Example_customRoutes demonstrates registering routes individually with custom middleware. 

package main

import (
	"fmt"
	"log"

	"github.com/gin-gonic/gin"
	"github.com/gtkit/gouploader"
)

func main() {
	r := gin.Default()

	uploader, err := gouploader.New(
		gouploader.WithLocalStorage("./uploads"),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Register routes individually with custom middleware.
	auth := func(c *gin.Context) { c.Next() } // your auth middleware

	v1 := r.Group("/api/v1", auth)
	{
		v1.POST("/upload", uploader.HandleUpload())
		v1.POST("/upload/chunk/init", uploader.HandleChunkInit())
		v1.POST("/upload/chunk", uploader.HandleChunkUpload())
		v1.GET("/upload/chunk/status/:upload_id", uploader.HandleChunkStatus())
		v1.POST("/upload/chunk/merge/:upload_id", uploader.HandleChunkMerge())
		v1.DELETE("/upload/chunk/:upload_id", uploader.HandleChunkAbort())
	}

	fmt.Println("custom routes registered")
}

Output:
custom routes registered
Example (S3)

Example_s3 demonstrates using S3-compatible storage (MinIO/阿里云/腾讯云/华为云). 

package main

import (
	"fmt"
	"log"

	"github.com/gin-gonic/gin"
	"github.com/gtkit/gouploader"
)

func main() {
	r := gin.Default()

	uploader, err := gouploader.New(
		gouploader.WithS3Storage(gouploader.S3Config{
			// MinIO:
			//   Endpoint: "127.0.0.1:9000",
			// 阿里云 OSS:
			//   Endpoint: "oss-cn-hangzhou.aliyuncs.com",
			// 腾讯云 COS:
			//   Endpoint: "cos.ap-guangzhou.myqcloud.com",
			// 华为云 OBS:
			//   Endpoint: "obs.cn-north-4.myhuaweicloud.com",
			Endpoint:  "127.0.0.1:9000",
			AccessKey: "minioadmin",
			SecretKey: "minioadmin",
			Bucket:    "uploads",
			Region:    "us-east-1",
			UseSSL:    false,
		}),
		gouploader.WithMaxFileSize(10<<30), // 10GB
		gouploader.WithChunkSize(
			10<<20, // default: 10MB
			1<<20,  // min: 1MB
			50<<20, // max: 50MB
		),
	)
	if err != nil {
		log.Fatal(err)
	}

	uploader.RegisterRoutes(r.Group("/api/v1/upload"))
	fmt.Println("s3 routes registered")
}
Example (WithCallback)

Example_withCallback demonstrates how to handle post-upload business logic. 

package main

import (
	"fmt"
	"log"

	"github.com/gin-gonic/gin"
	"github.com/gtkit/gouploader"
)

func main() {
	r := gin.Default()

	uploader, err := gouploader.New(
		gouploader.WithLocalStorage("./uploads"),
		gouploader.WithMaxFileSize(2<<30), // 2GB
		gouploader.WithAllowedTypes(".jpg", ".png", ".mp4", ".pdf"),
		gouploader.WithHashAlgorithm("sha256"),
		gouploader.WithOnUploadComplete(func(result *gouploader.UploadResult) {
			// This callback fires after every successful upload.
			// Use it to save metadata to your database, send notifications, etc.
			log.Printf("file uploaded: %s -> %s (checksum: %s)",
				result.FileName, result.StorageKey, result.Checksum)
		}),
	)
	if err != nil {
		log.Fatal(err)
	}

	uploader.RegisterRoutes(r.Group("/api/v1/upload"))
	defer uploader.Close()
	// r.Run(":8080")
	fmt.Println("routes registered")
}

Output:
routes registered

Index

Examples

Constants

View Source 
const (
	CodeFileTooLarge     = types.CodeFileTooLarge     // 文件超过大小限制
	CodeFileTypeNotAllow = types.CodeFileTypeNotAllow // 文件类型不允许
	CodeChecksumMismatch = types.CodeChecksumMismatch // 校验和不匹配
	CodeFileReadError    = types.CodeFileReadError    // 文件读取错误
	CodeInvalidParam     = types.CodeInvalidParam     // 参数无效
	CodeMultipartError   = types.CodeMultipartError   // multipart 解析错误

	CodeSessionNotFound    = types.CodeSessionNotFound    // 上传会话不存在
	CodeSessionExpired     = types.CodeSessionExpired     // 上传会话已过期
	CodeChunkIndexOutRange = types.CodeChunkIndexOutRange // 分片索引越界
	CodeChunkDuplicate     = types.CodeChunkDuplicate     // 分片重复上传
	CodeChunkHashMismatch  = types.CodeChunkHashMismatch  // 分片校验和不匹配
	CodeMergeIncomplete    = types.CodeMergeIncomplete    // 分片未全部上传
	CodeMergeHashFailed    = types.CodeMergeHashFailed    // 合并后校验失败

	CodeStorageWriteFail  = types.CodeStorageWriteFail  // 存储写入失败
	CodeStorageReadFail   = types.CodeStorageReadFail   // 存储读取失败
	CodeStorageDeleteFail = types.CodeStorageDeleteFail // 存储删除失败

	CodeSTSNotConfigured   = types.CodeSTSNotConfigured   // STS 未配置
	CodeSTSIssueFailed     = types.CodeSTSIssueFailed     // STS 凭证签发失败
	CodeCallbackVerifyFail = types.CodeCallbackVerifyFail // 回调验签失败
	CodeDirectFileNotFound = types.CodeDirectFileNotFound // 直传文件不存在

	CodeMultipartNotSupported = types.CodeMultipartNotSupported // 当前存储后端不支持 Multipart 直传
	CodeMultipartInitFailed   = types.CodeMultipartInitFailed   // 云端 Multipart 初始化失败
	CodeMultipartPresignFail  = types.CodeMultipartPresignFail  // 预签名 URL 生成失败
	CodeMultipartCompleteFail = types.CodeMultipartCompleteFail // 云端 Multipart 合并失败
	CodeMultipartAbortFail    = types.CodeMultipartAbortFail    // 云端 Multipart 中止失败
	CodePartVerifyFail        = types.CodePartVerifyFail        // 服务端二次校验 parts 失败
	CodePartETagMismatch      = types.CodePartETagMismatch      // 客户端上报 ETag 与云端不一致
	CodeUnauthorized          = types.CodeUnauthorized          // 无权访问该会话
)

错误码常量。

View Source 
const (
	StageInit     = types.StageInit     // 会话初始化阶段
	StagePart     = types.StagePart     // 分片上传阶段
	StageMerge    = types.StageMerge    // 代理路径合并阶段
	StageComplete = types.StageComplete // Multipart 直传 Complete 阶段
	StageAbort    = types.StageAbort    // 中止阶段
)

Stage 常量：UploadErrorEvent.Stage 字段的合法取值。 这些字符串值可直接作为 Prometheus label 使用。

View Source 
const (
	AbortReasonClientRequest = types.AbortReasonClientRequest
)

中止原因常量：UploadAbortEvent.Reason 字段的取值。

View Source 
const Version = "v1.3.0"

Variables

View Source 
var (
	ErrFileTooLarge     = types.ErrFileTooLarge
	ErrFileTypeNotAllow = types.ErrFileTypeNotAllow
	ErrChecksumMismatch = types.ErrChecksumMismatch
	ErrInvalidParam     = types.ErrInvalidParam
	ErrMultipartError   = types.ErrMultipartError

	ErrSessionNotFound    = types.ErrSessionNotFound
	ErrSessionExpired     = types.ErrSessionExpired
	ErrChunkIndexOutRange = types.ErrChunkIndexOutRange
	ErrChunkHashMismatch  = types.ErrChunkHashMismatch
	ErrMergeIncomplete    = types.ErrMergeIncomplete
	ErrMergeHashFailed    = types.ErrMergeHashFailed

	ErrStorageWrite  = types.ErrStorageWrite
	ErrStorageRead   = types.ErrStorageRead
	ErrStorageDelete = types.ErrStorageDelete

	ErrSTSNotConfigured   = types.ErrSTSNotConfigured
	ErrSTSIssueFailed     = types.ErrSTSIssueFailed
	ErrCallbackVerifyFail = types.ErrCallbackVerifyFail
	ErrDirectFileNotFound = types.ErrDirectFileNotFound

	ErrMultipartNotSupported = types.ErrMultipartNotSupported
	ErrMultipartInitFailed   = types.ErrMultipartInitFailed
	ErrMultipartPresignFail  = types.ErrMultipartPresignFail
	ErrMultipartCompleteFail = types.ErrMultipartCompleteFail
	ErrMultipartAbortFail    = types.ErrMultipartAbortFail
	ErrPartVerifyFail        = types.ErrPartVerifyFail
	ErrPartETagMismatch      = types.ErrPartETagMismatch
	ErrUnauthorized          = types.ErrUnauthorized
)

预定义错误。

Functions

func CORS 

func CORS(cfg CORSConfig) gin.HandlerFunc

CORS 返回处理跨域请求的 Gin 中间件。

用法： 

group := r.Group("/api/v1/upload")
group.Use(gouploader.CORS(gouploader.CORSConfig{
    AllowOrigins: []string{"https://example.com"},
}))
uploader.RegisterRoutes(group)

Types

type AWSSTSConfig 

type AWSSTSConfig = sts.AWSConfig

AWSSTSConfig AWS S3 STS 配置。

type AliyunSTSConfig 

type AliyunSTSConfig = sts.AliyunConfig

AliyunSTSConfig 阿里云 OSS STS 配置。

type CORSConfig 

type CORSConfig struct {
	// AllowOrigins 允许访问的源列表。
	// 使用 "*" 允许所有源（不建议生产环境使用）。
	AllowOrigins []string

	// AllowHeaders 客户端可以发送的额外请求头。
	// 默认请求头（Content-Type, X-Request-ID）始终包含。
	AllowHeaders []string

	// ExposeHeaders 客户端可以读取的额外响应头。
	ExposeHeaders []string

	// AllowCredentials 是否允许携带凭据（Cookie 等）。
	AllowCredentials bool

	// MaxAge 预检请求结果的缓存时间（秒）。默认 86400（24小时）。
	MaxAge int
}

CORSConfig 跨域资源共享配置。

type ChunkCompleteRequest added in v1.2.0 

type ChunkCompleteRequest = types.ChunkCompleteRequest

ChunkCompleteRequest Multipart 直传路径的合并请求体。

type ChunkInitRequest 

type ChunkInitRequest = types.ChunkInitRequest

ChunkInitRequest 初始化分片上传的 JSON 请求体。

type ChunkInitResponse 

type ChunkInitResponse = types.ChunkInitResponse

ChunkInitResponse 分片上传会话创建后的响应。

type ChunkStatusResponse 

type ChunkStatusResponse = types.ChunkStatusResponse

ChunkStatusResponse 查询分片上传状态的响应。

type ChunkUploadResponse 

type ChunkUploadResponse = types.ChunkUploadResponse

ChunkUploadResponse 单个分片上传后的响应。

type CompleteResult added in v1.2.0 

type CompleteResult = types.CompleteResult

CompleteResult Multipart 合并结果。

type DirectCompleteRequest 

type DirectCompleteRequest = types.DirectCompleteRequest

DirectCompleteRequest 前端确认上传完成的请求体。

type DirectTokenRequest 

type DirectTokenRequest = types.DirectTokenRequest

DirectTokenRequest 请求 STS 凭证的请求体。

type DirectTokenResponse 

type DirectTokenResponse = types.DirectTokenResponse

DirectTokenResponse STS 凭证响应。

type DirectUploadResult 

type DirectUploadResult = types.DirectUploadResult

DirectUploadResult 前端直传完成后的结果。

type Error 

type Error = types.Error

Error 统一错误类型。

type HashStore added in v1.2.0 

type HashStore = types.HashStore

HashStore 是秒传索引接口，由业务方实现（MySQL/Redis/Mongo 等）。

type HashedFile added in v1.2.0 

type HashedFile = types.HashedFile

HashedFile 秒传索引条目。

type HuaweiSTSConfig 

type HuaweiSTSConfig = sts.HuaweiConfig

HuaweiSTSConfig 华为云 OBS STS 配置。

type InstantHitEvent added in v1.2.0 

type InstantHitEvent = types.InstantHitEvent

InstantHitEvent 秒传命中时触发的生命周期钩子 payload。

type MultipartMeta added in v1.2.0 

type MultipartMeta = types.MultipartMeta

MultipartMeta 创建 Multipart 时可设置的对象元数据。

type MultipartStorage added in v1.2.0 

type MultipartStorage = types.MultipartStorage

MultipartStorage 是支持云原生 Multipart 直传的存储扩展接口。 由各云厂商 adapter 子 module 实现（aliyun / tencent / huawei）。

type Option 

type Option func(*config)

Option 用于配置 Uploader。

func WithAWSSTS 

func WithAWSSTS(cfg AWSSTSConfig) Option

WithAWSSTS 配置 AWS S3 STS 直传。

func WithAliyunSTS 

func WithAliyunSTS(cfg AliyunSTSConfig) Option

WithAliyunSTS 配置阿里云 OSS STS 直传。

func WithAllowedTypes 

func WithAllowedTypes(types ...string) Option

WithAllowedTypes 设置允许的文件扩展名（如 ".jpg", ".png", ".mp4"）。 空列表表示允许所有类型。

func WithChunkCleanupInterval 

func WithChunkCleanupInterval(interval time.Duration) Option

WithChunkCleanupInterval 设置过期会话的清理间隔。 interval 必须为正数，否则 panic。

func WithChunkSessionTTL 

func WithChunkSessionTTL(ttl time.Duration) Option

WithChunkSessionTTL 设置分片上传会话的过期时间。

func WithChunkSize 

func WithChunkSize(defaultSize, minSize, maxSize int64) Option

WithChunkSize 设置默认、最小和最大分片大小。

func WithChunkTempDir 

func WithChunkTempDir(dir string) Option

WithChunkTempDir 设置分片数据的临时目录。

func WithHashAlgorithm 

func WithHashAlgorithm(algo string) Option

WithHashAlgorithm 设置校验和算法（"md5" 或 "sha256"）。

func WithHashStore added in v1.2.0 

func WithHashStore(hs HashStore) Option

WithHashStore 注入秒传索引存储。nil 时秒传功能关闭。

典型用法： 

type dbHashStore struct{ db *gorm.DB }
func (s *dbHashStore) LookupByHash(ctx, algo, hash) (*HashedFile, error) { ... }
func (s *dbHashStore) Register(ctx, entry *HashedFile) error { ... }

gouploader.WithHashStore(&dbHashStore{db: db})

func WithHashStoreRegisterTimeout added in v1.3.0 

func WithHashStoreRegisterTimeout(d time.Duration) Option

WithHashStoreRegisterTimeout 设置 HashStore.Register 异步注册的最大等待时长。 默认 30 秒。HashStore 实现卡死时，此超时防止后台 goroutine 无限累积。 业务方根据下游存储 SLA 自行调整（如 Redis 一般 100ms，MySQL 写入一般 1-2s）。

func WithHuaweiSTS 

func WithHuaweiSTS(cfg HuaweiSTSConfig) Option

WithHuaweiSTS 配置华为云 OBS STS 直传。

func WithLocalStorage 

func WithLocalStorage(basePath string) Option

WithLocalStorage 配置本地磁盘存储。

func WithMaxFileSize 

func WithMaxFileSize(size int64) Option

WithMaxFileSize 设置允许的最大文件大小（字节）。

func WithMultipartDisabled added in v1.2.0 

func WithMultipartDisabled() Option

WithMultipartDisabled 强制关闭 Multipart 直传路径，所有大文件都走代理合并。 用于灰度回滚或调试。默认启用（前提是 Storage 实现了 MultipartStorage 接口）。

func WithMultipartFeatureFlag added in v1.2.0 

func WithMultipartFeatureFlag(fn func(ctx context.Context, ginCtx *gin.Context, req *ChunkInitRequest) bool) Option

WithMultipartFeatureFlag 注入 Feature Flag 钩子，按请求动态决定是否走 Multipart 路径。 典型用法：灰度发布 / 按用户 ID hash / 按 bucket 分流。 

gouploader.WithMultipartFeatureFlag(func(ctx, ginCtx, req) bool {
    uid := ginCtx.GetString("user_id")
    return hashMod(uid) < 10  // 10% 灰度
})

func WithMultipartKeyPrefix added in v1.2.0 

func WithMultipartKeyPrefix(fn func(c *gin.Context, userID string) string) Option

WithMultipartKeyPrefix 生成 Multipart 路径下的对象键前缀。 默认按日期生成 "{year}/{month}/{day}/"。

典型用法（按用户隔离）： 

gouploader.WithMultipartKeyPrefix(func(c, userID) string {
    return fmt.Sprintf("user-%s/%s/", userID, time.Now().Format("2006-01-02"))
})

func WithMultipartThreshold added in v1.2.0 

func WithMultipartThreshold(bytes int64) Option

WithMultipartThreshold 设置走 Multipart 直传的最小文件大小（字节）。 小于此阈值的文件强制走代理路径——省掉签名开销。默认 100MB。

func WithOnDirectUploadComplete 

func WithOnDirectUploadComplete(fn func(result *DirectUploadResult)) Option

WithOnDirectUploadComplete 注册直传完成后的回调。 在 Complete 或 Callback 确认文件上传成功后触发。

func WithOnInstantHit added in v1.2.0 

func WithOnInstantHit(fn func(ctx context.Context, ev *InstantHitEvent)) Option

WithOnInstantHit 注册秒传命中钩子。 用于统计命中率、节省流量等业务指标。 仅在 HashStore 配置且 LookupByHash 返回非 nil 时触发。

func WithOnUploadAbort added in v1.2.0 

func WithOnUploadAbort(fn func(ctx context.Context, ev *UploadAbortEvent)) Option

WithOnUploadAbort 注册上传中止钩子。 触发时机：客户端 DELETE /chunk/:id 清理完 session 后（云端 Multipart 也已 Abort）。

func WithOnUploadComplete 

func WithOnUploadComplete(fn func(result *UploadResult)) Option

WithOnUploadComplete 注册上传完成后的回调函数。 每次上传成功后触发（包括普通上传和分片合并）。 可用于保存数据库、发送通知等业务逻辑。

func WithOnUploadError added in v1.2.0 

func WithOnUploadError(fn func(ctx context.Context, ev *UploadErrorEvent)) Option

WithOnUploadError 注册上传阶段失败钩子。 触发阶段见 Stage 常量：StageInit / StagePart / StageMerge / StageComplete / StageAbort。

func WithOnUploadInit added in v1.2.0 

func WithOnUploadInit(fn func(ctx context.Context, ev *UploadInitEvent)) Option

WithOnUploadInit 注册上传会话初始化成功钩子。 触发时机：InitiateMultipart（云端）或本地 session 创建成功后。 秒传命中时不触发此钩子，改为触发 WithOnInstantHit。

func WithOrphanCleanup added in v1.2.0 

func WithOrphanCleanup(ttl, interval time.Duration) Option

WithOrphanCleanup 启用悬挂 Multipart 清理 worker。 ttl: 超过此时长未完成的 Multipart 视为悬挂，会被 Abort。默认 24h。 interval: 清理 worker 扫描间隔。默认 1h。

注意：此功能需要 Storage 实现 MultipartStorage 接口（包含 ListOrphans / AbortMultipart）。 建议同时在 bucket 层面配置 AbortIncompleteMultipartUpload 生命周期规则做双保险。

func WithPartSignTTL added in v1.2.0 

func WithPartSignTTL(ttl time.Duration) Option

WithPartSignTTL 设置单个 part 预签名 URL 的有效期。默认 15 分钟。 太短会导致网络慢的客户端 URL 过期，太长会扩大 URL 泄漏的爆炸半径。

func WithPublicURLBuilder added in v1.3.0 

func WithPublicURLBuilder(fn func(storageKey string) string) Option

WithPublicURLBuilder 注入"对外可见 URL"拼装策略。

配置后，所有上传完成路径返回的 result（UploadResult / DirectUploadResult）的 URL 字段会被填充为 builder(storageKey) 的输出。覆盖路径：

  • 普通上传 POST /
  • 代理分片合并 POST /chunk/merge/:upload_id
  • Multipart 直传合并 POST /chunk/complete
  • 秒传命中 POST /chunk/init
  • STS 直传 POST /direct/complete
  • STS 直传回调 POST /direct/callback

builder 应保持轻量（纯字符串拼接），避免阻塞主上传流程。 builder 内 panic 被 recover 隔离，不影响上传；但 URL 字段会为空字符串。

典型用法（CDN 前缀拼接）： 

gouploader.WithPublicURLBuilder(func(key string) string {
    return "https://static.example.com/" + key
})

私有 bucket 临时访问 URL 示例（业务方自行调云 SDK 签名）： 

gouploader.WithPublicURLBuilder(func(key string) string {
    url, _ := storage.GetSignedGetURL(context.Background(), key, 15*time.Minute)
    return url
})

不配置 / 设为 nil 时，所有 result.URL 字段为空，JSON 因 omitempty 不输出， 行为等价于未引入此特性的旧版本。

func WithS3Storage 

func WithS3Storage(s3 S3Config) Option

WithS3Storage 配置 S3 兼容对象存储。

func WithSTSKeyPrefix 

func WithSTSKeyPrefix(fn func(c *gin.Context) string) Option

WithSTSKeyPrefix 设置生成 keyPrefix 的函数。 默认按日期生成，如 "direct/2026/04/09/"。 可用于按用户 ID 隔离：func(c *gin.Context) string { return "user-" + getUserID(c) + "/" }

func WithSTSProvider 

func WithSTSProvider(p STSProvider) Option

WithSTSProvider 设置自定义 STS Provider 实现。

func WithStorage 

func WithStorage(s Storage) Option

WithStorage 设置自定义 Storage 实现。 会覆盖 WithLocalStorage 和 WithS3Storage。

func WithTencentSTS 

func WithTencentSTS(cfg TencentSTSConfig) Option

WithTencentSTS 配置腾讯云 COS STS 直传。

func WithUserIDFn added in v1.2.0 

func WithUserIDFn(fn func(c *gin.Context) string) Option

WithUserIDFn 从 Gin 上下文提取用户标识，用于 keyPrefix 隔离和 hash 索引二级键。 未配置时默认返回 "anon"。

type OrphanMultipart added in v1.2.0 

type OrphanMultipart = types.OrphanMultipart

OrphanMultipart 悬挂 Multipart 元信息。

type PartETag added in v1.2.0 

type PartETag = types.PartETag

PartETag 分片号 + ETag 的键值对，用于 Multipart 合并。

type PartInfo added in v1.2.0 

type PartInfo = types.PartInfo

PartInfo 云端分片元信息。

type PartSignRequest added in v1.2.0 

type PartSignRequest = types.PartSignRequest

PartSignRequest 按需签名请求体。

type PartSignResponse added in v1.2.0 

type PartSignResponse = types.PartSignResponse

PartSignResponse 按需签名响应。

type PresignPartRequest added in v1.2.0 

type PresignPartRequest = types.PresignPartRequest

PresignPartRequest 预签名单片请求。

type ResumeRequest added in v1.2.0 

type ResumeRequest = types.ResumeRequest

ResumeRequest 秒传 + 断点续传查询请求体。

type ResumeResponse added in v1.2.0 

type ResumeResponse = types.ResumeResponse

ResumeResponse 秒传 + 断点续传查询响应。

type S3Config 

type S3Config struct {
	Endpoint  string
	AccessKey string
	SecretKey string
	Bucket    string
	Region    string
	UseSSL    bool
}

S3Config 包含 S3 兼容对象存储的连接参数。

Endpoint 示例： 

MinIO:      "127.0.0.1:9000"
阿里云 OSS:  "oss-cn-hangzhou.aliyuncs.com"
腾讯云 COS:  "cos.ap-guangzhou.myqcloud.com"
华为云 OBS:  "obs.cn-north-4.myhuaweicloud.com"
AWS S3:     "s3.us-east-1.amazonaws.com"

type STSCredential 

type STSCredential = types.STSCredential

STSCredential STS 临时凭证。

type STSProvider 

type STSProvider = types.STSProvider

STSProvider STS 凭证签发接口。

type Storage 

type Storage = types.Storage

Storage 抽象文件持久化层。 所有方法均使用 io.Reader 流式传输，不会将完整文件缓冲到内存。

内置实现：本地磁盘、S3 兼容（MinIO/阿里云/腾讯云/华为云/AWS）。 也可通过 WithStorage 选项提供自定义实现。

type TencentSTSConfig 

type TencentSTSConfig = sts.TencentConfig

TencentSTSConfig 腾讯云 COS STS 配置。

type UploadAbortEvent added in v1.2.0 

type UploadAbortEvent = types.UploadAbortEvent

UploadAbortEvent 会话被中止时触发的生命周期钩子 payload。

type UploadErrorEvent added in v1.2.0 

type UploadErrorEvent = types.UploadErrorEvent

UploadErrorEvent 任一上传阶段失败时触发的生命周期钩子 payload。

type UploadInitEvent added in v1.2.0 

type UploadInitEvent = types.UploadInitEvent

UploadInitEvent 会话初始化成功时触发的生命周期钩子 payload。

type UploadResult 

type UploadResult = types.UploadResult

UploadResult 文件上传完成后返回的结果（普通上传和分片合并）。

type Uploader 

type Uploader struct {
	// contains filtered or unexported fields
}

Uploader 是 gouploader 包的主入口。

func New 

func New(opts ...Option) (*Uploader, error)

New 使用给定的选项创建 Uploader 实例。

func (*Uploader) Close 

func (u *Uploader) Close()

Close 释放 Uploader 持有的资源（停止后台清理协程）。 在 Uploader 不再使用或应用关闭时必须调用。

func (*Uploader) HandleChunkAbort 

func (u *Uploader) HandleChunkAbort() gin.HandlerFunc

HandleChunkAbort 返回中止分片上传的 Gin 处理函数。

func (*Uploader) HandleChunkComplete added in v1.2.0 

func (u *Uploader) HandleChunkComplete() gin.HandlerFunc

HandleChunkComplete 返回 Multipart 路径合并的 Gin 处理函数。

func (*Uploader) HandleChunkInit 

func (u *Uploader) HandleChunkInit() gin.HandlerFunc

HandleChunkInit 返回分片上传初始化的 Gin 处理函数。

func (*Uploader) HandleChunkMerge 

func (u *Uploader) HandleChunkMerge() gin.HandlerFunc

HandleChunkMerge 返回合并分片的 Gin 处理函数。

func (*Uploader) HandleChunkReportPartETag added in v1.2.0 

func (u *Uploader) HandleChunkReportPartETag() gin.HandlerFunc

HandleChunkReportPartETag 返回 Multipart 路径下客户端上报 ETag 的 Gin 处理函数。

func (*Uploader) HandleChunkResume added in v1.2.0 

func (u *Uploader) HandleChunkResume() gin.HandlerFunc

HandleChunkResume 返回秒传 + 断点续传查询的 Gin 处理函数。

func (*Uploader) HandleChunkSignParts added in v1.2.0 

func (u *Uploader) HandleChunkSignParts() gin.HandlerFunc

HandleChunkSignParts 返回按需签发分片预签名 URL 的 Gin 处理函数。

func (*Uploader) HandleChunkStatus 

func (u *Uploader) HandleChunkStatus() gin.HandlerFunc

HandleChunkStatus 返回查询分片上传状态的 Gin 处理函数。

func (*Uploader) HandleChunkUpload 

func (u *Uploader) HandleChunkUpload() gin.HandlerFunc

HandleChunkUpload 返回分片上传的 Gin 处理函数。

func (*Uploader) HandleDirectCallback 

func (u *Uploader) HandleDirectCallback() gin.HandlerFunc

HandleDirectCallback 返回云存储回调的 Gin 处理函数。

func (*Uploader) HandleDirectComplete 

func (u *Uploader) HandleDirectComplete() gin.HandlerFunc

HandleDirectComplete 返回前端确认上传完成的 Gin 处理函数。

func (*Uploader) HandleDirectToken 

func (u *Uploader) HandleDirectToken() gin.HandlerFunc

HandleDirectToken 返回签发 STS 凭证的 Gin 处理函数。

func (*Uploader) HandleUpload 

func (u *Uploader) HandleUpload() gin.HandlerFunc

HandleUpload 返回普通上传的 Gin 处理函数。 用于手动注册路由（搭配自定义中间件）。

func (*Uploader) RegisterRoutes 

func (u *Uploader) RegisterRoutes(group *gin.RouterGroup)

RegisterRoutes 在给定的 Gin 路由组上注册所有上传接口。

基础路由（始终注册）： 

POST   {group}/                         - 普通单文件上传
POST   {group}/chunk/init               - 初始化分片上传（自动探测 proxy / multipart / instant）
POST   {group}/chunk                    - [proxy] 上传单个分片
GET    {group}/chunk/status/:upload_id  - 查询上传进度（断点续传）
POST   {group}/chunk/merge/:upload_id   - [proxy] 合并所有分片
DELETE {group}/chunk/:upload_id         - 中止上传（同时 Abort 云端 Multipart）
POST   {group}/chunk/resume             - 秒传 + 断点续传查询
POST   {group}/chunk/parts/sign         - [multipart] 按需签发分片预签名 URL
POST   {group}/chunk/parts/report       - [multipart] 客户端上报单片 ETag
POST   {group}/chunk/complete           - [multipart] 合并（携带 parts + ETag 列表）

STS 直传路由（仅当配置了 STS Provider 时注册）： 

POST   {group}/direct/token     - 签发 STS 临时凭证
POST   {group}/direct/callback  - 云存储上传完成回调
POST   {group}/direct/complete  - 前端确认上传完成

Source Files

View all Source files

Directories

Path Synopsis
aliyun module
aws module
huawei module
internal
chunk
handler
hash
response
service
store
sts
types
minio module
tencent module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.