文件微服务

切换主题

☁️ 腾讯云对象存储(COS) ​

腾讯云对象存储COS是一种海量、安全、低成本、高可靠的云端存储服务，提供99.9999999999%的数据持久性。

📋 配置示例 ​

yaml
files:
  - business-type: demo
    file-type: cos
    business-folder: demo-files
    http-access-path: https://cdn.example.com
    access-key-id: AKIDxxxxxxxxxxxxxxxx
    access-key-secret: xxxxxxxxxxxxxxxxxxxxxxxx
    bucket: my-bucket-1251238510
    endpoint: ap-chengdu
    max-size: 2GB
    chunk-size: 10MB
    allowed-upload-suffix: jpg,png,pdf,doc,docx,mp4
    allow-delete: true
yaml
files:
  # 视频文件
  - business-type: video
    file-type: cos
    business-folder: videos
    bucket: video-bucket-1251238510
    endpoint: ap-chengdu
    chunk-size: 10MB
    max-size: 5GB
    
  # 图片文件
  - business-type: image
    file-type: cos
    business-folder: images
    bucket: image-bucket-1251238510
    endpoint: ap-chengdu
    chunk-size: 2MB
    max-size: 10MB

📝 参数说明 ​

参数必填说明示例
business-type是业务类型标识demo
file-type是固定值：coscos
business-folder否业务文件夹前缀demo-files
http-access-path是文件访问域名（CDN或COS域名）https://cdn.example.com
access-key-id是腾讯云SecretIdAKIDxxxxxxxxxxxxxxxx
access-key-secret是腾讯云SecretKeyxxxxxxxxxxxxxxxx
bucket是COS存储桶名称（含APPID）my-bucket-1251238510
endpoint是COS地域标识ap-chengdu
max-size否单文件大小限制2GB
chunk-size否分片上传大小（默认5MB）10MB
allowed-upload-suffix否允许的文件后缀jpg,png,pdf
allow-no-suffix否是否允许无后缀文件false
allow-delete否是否允许删除true

注意

  • Bucket名称格式：{name}-{APPID}，例如 my-bucket-1251238510
  • APPID可在账号信息中查看
  • Endpoint只需填写地域标识，如 ap-chengdu，不需要完整域名

🚀 快速开始 ​

步骤1: 创建COS存储桶 ​

  1. 登录 腾讯云COS控制台
  2. 点击 创建存储桶
  3. 配置存储桶：
    • 名称：如 my-app-files（系统会自动添加APPID后缀）
    • 所属地域：选择就近地域，如 成都
    • 访问权限：私有读写（推荐）
    • 存储类型：标准存储
  4. 点击确定创建
  5. 记录完整的Bucket名称（含APPID）

步骤2: 获取访问密钥 ​

  1. 访问 API密钥管理
  2. 创建密钥（推荐使用子账号）：
    • 点击 新建密钥
    • 保存 SecretId 和 SecretKey
  3. 或使用子账号：
    • 访问 用户列表
    • 创建子用户并授予COS权限
    • 为子用户创建API密钥

安全建议

  • 强烈建议使用子账号，不要使用主账号密钥
  • 仅授予必要的COS权限
  • 定期轮换密钥
  • 开启MFA多因素认证

步骤3: 配置CDN加速（可选） ​

  1. 在COS控制台选择存储桶
  2. 点击 域名与传输管理 > 自定义CDN加速域名
  3. 添加自定义域名
  4. 配置HTTPS证书
  5. 将 http-access-path 设置为CDN域名

🌍 地域列表 ​

中国大陆 ​

地域名称地域标识完整Endpoint
北京ap-beijingcos.ap-beijing.myqcloud.com
南京ap-nanjingcos.ap-nanjing.myqcloud.com
上海ap-shanghaicos.ap-shanghai.myqcloud.com
广州ap-guangzhoucos.ap-guangzhou.myqcloud.com
成都ap-chengducos.ap-chengdu.myqcloud.com
重庆ap-chongqingcos.ap-chongqing.myqcloud.com

中国香港及海外 ​

地域名称地域标识完整Endpoint
中国香港ap-hongkongcos.ap-hongkong.myqcloud.com
新加坡ap-singaporecos.ap-singapore.myqcloud.com
孟买ap-mumbaicos.ap-mumbai.myqcloud.com
首尔ap-seoulcos.ap-seoul.myqcloud.com
曼谷ap-bangkokcos.ap-bangkok.myqcloud.com
东京ap-tokyocos.ap-tokyo.myqcloud.com
硅谷na-siliconvalleycos.na-siliconvalley.myqcloud.com
弗吉尼亚na-ashburncos.na-ashburn.myqcloud.com
法兰克福eu-frankfurtcos.eu-frankfurt.myqcloud.com

查看完整地域列表

📦 分片上传说明 ​

工作原理 ​

COS分片上传使用腾讯云的Multipart Upload功能：

  1. 初始化：调用 InitiateMultipartUpload 获取 UploadId
  2. 上传分片：并发上传各个分片，每个分片有唯一的 PartNumber
  3. 合并分片：调用 CompleteMultipartUpload 完成上传

优势 ​

  • ✅ 断点续传：支持暂停和恢复
  • ✅ 并发上传：多个分片同时上传
  • ✅ 大文件支持：最大支持48.82TB
  • ✅ 成本优化：失败的分片可单独重传
  • ✅ 无临时存储：直接上传到COS

分片大小建议 ​

文件类型建议分片大小说明
视频文件10MB - 20MB大文件
文档文件5MB - 10MB中等文件
图片文件2MB - 5MB小文件

分片限制

  • 最小：1MB（除最后一个分片）
  • 最大：5GB
  • 最多分片数：10000

💡 最佳实践 ​

1. 存储类型选择 ​

存储类型适用场景访问延迟成本
标准存储热点数据毫秒级标准
低频存储较少访问（每月1-2次）毫秒级较低
归档存储长期归档需解冻（分钟级）最低
深度归档极少访问需解冻（小时级）极低

2. 生命周期管理 ​

yaml
# 在COS控制台配置生命周期规则
规则1: 30天后转为低频存储
规则2: 180天后转为归档存储
规则3: 365天后删除

3. 性能优化 ​

yaml
# 根据文件类型优化
files:
  - business-type: video
    chunk-size: 20MB    # 视频使用大分片
    max-size: 10GB
    
  - business-type: image
    chunk-size: 2MB     # 图片使用小分片
    max-size: 10MB

4. 安全配置 ​

防盗链 ​

在COS控制台配置防盗链：

允许的Referer:
- https://www.example.com
- https://app.example.com
空Referer: 拒绝

跨域配置 ​

json
{
  "AllowedOrigins": ["https://www.example.com"],
  "AllowedMethods": ["GET", "POST", "PUT"],
  "AllowedHeaders": ["*"],
  "ExposeHeaders": ["ETag"],
  "MaxAgeSeconds": 3600
}

❓ 常见问题 ​

Q: 上传失败，提示SignatureDoesNotMatch？

A: 检查以下几点：

  1. SecretId和SecretKey是否正确
  2. Bucket名称是否包含APPID
  3. Endpoint地域标识是否正确
  4. 系统时间是否准确（时间偏差>15分钟会失败）
Q: 如何提高上传速度？

A:

  1. 选择就近地域
  2. 使用分片上传
  3. 调整分片大小（10-20MB）
  4. 并发上传3-5个分片
  5. 使用内网域名（CVM同地域）
Q: 如何降低成本？

A:

  1. 使用低频存储或归档存储
  2. 配置生命周期规则
  3. 定期清理无用文件
  4. 使用CDN减少回源流量
  5. 开启智能分层存储
Q: 分片上传中断如何处理？

A:

  1. 保存UploadId继续上传剩余分片
  2. 定期清理未完成的分片（碎片管理）
  3. 设置自动清理规则（7天）

🔗 相关链接 ​

📊 性能参考 ​

指标数值
单文件最大48.82TB
分片最大5GB
最大分片数10000
可用性99.95%
数据持久性99.9999999999%

Copyright © 2017-2026 wueasy.com