火山引擎对象存储 TOS 入门到上手

TOS 是什么

TOS（Volcengine Object Storage） 是火山引擎提供的对象存储服务，对标 AWS S3、阿里云 OSS、腾讯云 COS。最大特点是完全兼容 S3 协议——意味着你能用任何 S3 SDK 直接接 TOS，迁移成本几乎为零。

一句话定位：存海量非结构化数据（图片、视频、日志、备份、模型权重），按量计费、几乎无限容量、不挂本地磁盘。

三个核心概念

AccessKey 三件套

TOS 用 AccessKey ID + Secret AccessKey 鉴权。永远别把这对密钥硬编码进前端。

控制台三步上手

1. 火山引擎控制台 → 对象存储 TOS → 创建桶
   • 选区域（离用户最近的那个）
   • 选存储类型：标准 / 低频 / 归档（归档取回慢、便宜）
   • 权限：私有读写（默认）/ 公有读 / 公有读写（不要用公有读写）
2. 访问控制 IAM → 用户 → 创建 AccessKey
   • 只授予这一个桶的读写权限（最小权限原则）
   • 立即下载 AK 凭据，关闭页面就再也看不到 SecretAccessKey 了
3. 桶设置 → 跨域 CORS / 防盗链 / 生命周期规则

Node.js 上传（官方 SDK）

npm install @volcengine/sdk
# 或用 AWS SDK（协议兼容）：
# npm install @aws-sdk/client-s3

最小可跑上传：

import { TosClient } from "@volcengine/sdk";

const client = new TosClient({
  accessKeyId: process.env.TOS_AK!,
  accessKeySecret: process.env.TOS_SK!,
  region: "cn-beijing",
  endpoint: "tos-cn-beijing.volces.com",
});

await client.putObject({
  bucket: "my-prod",
  key: `uploads/${Date.now()}-${file.name}`,
  body: file.stream(),
  contentType: file.type,
});

Presigned URL（最常用的对接姿势）

Presigned URL = 把一次操作（PUT / GET / DELETE）的鉴权签名直接打到 URL 里，持 URL 的人就有权限，过期即失效。

import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

// 上传 URL（5 分钟有效）
const uploadUrl = await getSignedUrl(
  client,
  new PutObjectCommand({ Bucket: "my-prod", Key: key, ContentType: mime }),
  { expiresIn: 300 }
);

// 下载 URL（私有文件也能直接给浏览器用）
const downloadUrl = await getSignedUrl(
  client,
  new GetObjectCommand({ Bucket: "my-prod", Key: key }),
  { expiresIn: 3600 }
);

大文件断点续传

超过 100MB 的文件用分段上传：

• 分片大小：5MB–5GB，推荐 5–20MB
• 片数限制：最多 10000 片，超过就要放大单片
• 断点重传：客户端记录已成功片的 partNumber + ETag，下次续传直接跳过成功的片
• 失败清理：服务端用 lifecycle 规则自动清理未完成的分段上传（见下）

生命周期规则（省钱 + 自洁）

桶级规则，按前缀匹配批量处理：

{
  "Rules": [
    {
      "ID": "log-auto-clean",
      "Filter": { "Prefix": "logs/" },
      "Status": "Enabled",
      "Expiration": { "Days": 365 }
    },
    {
      "ID": "kill-aborted-uploads",
      "Filter": { "Prefix": "" },
      "Status": "Enabled",
      "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 14 }
    }
  ]
}

CORS（前端直传必开）

桶的「跨域设置」加：

AllowedOrigin:  https://your-site.com
AllowedMethod:  PUT, GET, HEAD, POST
AllowedHeader:  *
ExposeHeader:   ETag, Content-Length

最小权限 IAM 策略

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "tos:GetObject",
        "tos:PutObject",
        "tos:DeleteObject",
        "tos:InitiateMultipartUpload",
        "tos:ListMultipartUploadParts",
        "tos:UploadPart",
        "tos:CompleteMultipartUpload",
        "tos:AbortMultipartUpload"
      ],
      "Resource": ["trn:tos:::my-prod/*", "trn:tos:::my-prod"]
    }
  ]
}

要点：

• 只授权业务实际用到的桶
• 只给操作对象的权限，不给 tos:ListAllMyBuckets
• 如果只是「前端签名」，后端只需要 tos:PutObject 之类；ListBuckets / DeleteBucket 这种管理类 API 不下发

防盗链

私有桶 + Presigned URL 已经能挡 99% 的盗链。公有读桶才需要 referer：

Referer 白名单：  https://your-site.com
空 Referer 行为： 拒绝

计量计费口径

省钱三招：

1. 同地域用内网：服务在 cn-beijing 就建 cn-beijing 的桶，公网流量 = 钱
2. 挂 CDN：TOS 直接做源站，CDN 发静态内容，回源流量便宜一个数量级
3. 归档化冷数据：超过 90 天不读就丢归档

常见坑

速查表

TOS 用起来像 S3，费用像水电，密钥一旦泄露像裸奔——前三件事做好了，后面就是白嫖。