腾讯云 COS 存储策略教程

这一篇覆盖什么

这一篇按完整流程讲怎么把 AsterDrive 文件写到腾讯云 COS：准备 bucket、创建 tencent_cos 存储策略、配置策略组规则、绑定用户或团队、验收上传下载，并说明 COS 数据万象原生处理的开关、后缀和计费边界。

适合什么时候用

腾讯云 COS 适合这些场景：

你已经在腾讯云上使用 COS，想让 AsterDrive 直接写入 COS bucket
文件较多或较大，希望把容量和带宽交给对象存储承接
希望按存储策略启用 COS 数据万象能力，例如图片缩略图或媒体信息解析
希望前端和后台明确显示“腾讯云 COS”，而不是把它混在普通 S3-compatible 后端里

如果你只需要一个通用 S3 兼容对象存储，而且不需要腾讯云数据万象能力，看 S3 / MinIO / R2 存储策略教程更合适。

COS 和 S3-compatible 的关系

AsterDrive 里 tencent_cos 是独立的存储后端类型，但它不是从零实现一套对象存储逻辑。

也就是说：

普通对象读写能力和 S3-compatible 类似
腾讯云 COS 在后台和前端会独立显示为 tencent_cos
数据万象等腾讯云原生能力只挂在 tencent_cos driver 上，不挂在通用 s3 driver 上

如果你要使用 COS 数据万象能力，创建策略时请选择 腾讯云 COS，不要把 COS 当普通 s3 策略配置。

先分清你要配哪几层

只创建 COS 存储策略还不够。用户或团队上传时，会先命中策略组，再由策略组规则分配到某条存储策略。

这篇用到的入口

你要做什么	入口
创建 COS 策略	`管理 -> 存储策略 -> 新建策略`
测试 COS 连接	`管理 -> 存储策略 -> 测试连接`
创建分流规则	`管理 -> 策略组`
给用户绑定策略组	`管理 -> 用户 -> 用户详情`
给团队绑定策略组	`管理 -> 团队 -> 团队详情`
配置全局媒体处理	`管理 -> 系统设置 -> 文件处理`

1. 准备 bucket 和 prefix

先在腾讯云 COS 控制台创建一个专用 bucket，例如：

text

asterdrive-prod-1250000000

建议给 AsterDrive 单独规划 prefix：

text

prod/

这样对象最终会在 bucket 里按 AsterDrive 的内容寻址路径继续展开。不要让多个 AsterDrive 实例写同一个 prefix，除非你明确知道它们不会互相覆盖或清理对象。

不建议人工移动 bucket 里的对象

AsterDrive 数据库记录了对象路径。人工移动、重命名或删除 COS 里的对象，会让数据库里的文件记录和真实对象不一致。

2. 准备访问凭证

给 AsterDrive 准备一组只用于这个 bucket / prefix 的腾讯云访问凭证。

最少需要覆盖：

读取对象
写入对象
删除对象
multipart upload 相关操作
访问目标 bucket / prefix 的必要权限

如果你要启用 COS 数据万象，还要确认这组凭证可以发起对应 CI 处理请求，例如图片处理或媒体信息解析。权限名和控制台入口会随腾讯云产品调整，按腾讯云最新文档和控制台为准。

3. 先选上传和下载方式

第一次接入建议先用保守路线：

方向	建议初始值	原因
上传方式	`relay_stream`	浏览器不需要直连 COS，少踩 CORS
下载方式	`relay_stream`	下载也先由 AsterDrive 中继，便于排查

确认基本读写没问题后，再考虑切换到：

上传 presigned
下载 presigned

`relay_stream` 怎么工作

上传时：

下载时：

好处是入口集中，排查简单。代价是应用节点要承接上传和下载带宽。

`presigned` 怎么工作

上传时：

下载时：

好处是减轻 AsterDrive 节点带宽压力。前提是浏览器能访问 COS endpoint，并且 COS CORS 配置正确。

4. 配置 COS CORS

如果你只使用 relay_stream，浏览器不会直接请求 COS，CORS 不是第一优先级。

如果要使用 presigned 上传，COS bucket 需要允许浏览器跨域上传。最少关注：

AllowedOrigin：你的 AsterDrive 公开站点地址
AllowedMethod：包含 PUT
AllowedHeader：允许上传请求用到的请求头
ExposeHeader：包含 ETag

如果要使用 presigned 下载，也要确认浏览器可以访问 COS 返回的下载地址，并且你接受下载响应头、缓存行为更多由 COS 决定。

用 AsterDrive 自动配置 CORS

AsterDrive 可以在管理后台为 Tencent COS 策略执行存储动作：

text

管理 -> 存储策略 -> 目标 COS 策略 -> 配置 CORS

这个动作对应后端 action：

json

{
  "action": "configure_tencent_cos_cors"
}

动作不会让前端传 AllowedOrigin。后端会读取运行时配置 public_site_url，把里面所有公开来源都写进同一条 COS CORS 规则。如果这里还没配置公开站点地址，动作会失败并返回 policy.action_parameter_required。

先到这里配置公开站点来源：

text

管理 -> 系统设置 -> 站点配置 -> 公开站点地址

例如：

json

["https://drive.example.com", "https://panel.example.com"]

public_site_url 只接受精确 HTTP(S) origin，不能带路径、查询、通配符或 *。这个配置虽然会被 CORS action 读取，但它本身不是 AsterDrive API 的 CORS 白名单；AsterDrive API 跨域仍然看系统设置里的网络访问配置。

自动配置写入的规则使用固定 ID：

text

asterdrive-presigned-access

规则内容：

项	值
`AllowedOrigin`	`public_site_url` 中的全部来源
`AllowedMethod`	`PUT`、`GET`、`HEAD`
`AllowedHeader`	``、`Content-Type`、`Range`、`x-cos-`
`ExposeHeader`	`ETag`、`Content-Length`、`Content-Range`、`Content-Disposition`、`Accept-Ranges`、`x-cos-request-id`、`x-cos-hash-crc64ecma`
`MaxAgeSeconds`	`600`
`ResponseVary`	`true`

腾讯云 COS 没有“只追加一条 CORS 规则”的原子 append 接口。AsterDrive 的实现是读取现有 CORS、保留其他规则、替换或新增 asterdrive-presigned-access，然后把完整配置写回 COS。也就是说：

其他规则会保留
同 ID 的旧 AsterDrive 规则会被替换
如果有人在读取和写入之间同时修改 bucket CORS，最后一次写入会覆盖那段时间内的并发变更

执行这个动作的腾讯云凭证需要能读取和写入 bucket CORS。写入至少需要 name/cos:PutBucketCORS 权限；如果 CAM 策略限制较细，也要确认读取当前 CORS 配置的权限已经放行。

和腾讯云官方接口的关系

AsterDrive 调用的是腾讯云 COS GET Bucket cors 和 PUT Bucket cors。PUT Bucket cors 需要 Content-MD5 请求头，AsterDrive 会计算 CORS XML 的 MD5 并把它一起纳入 COS 签名。

成功响应会返回实际写入的来源、COS request id，以及是否替换了旧规则：

json

{
  "action": "configure_tencent_cos_cors",
  "tencent_cos_cors": {
    "rule_id": "asterdrive-presigned-access",
    "allowed_origins": ["https://drive.example.com", "https://panel.example.com"],
    "request_id": "...",
    "preserved_rule_count": 0,
    "replaced_existing_rule": true,
    "response_vary": true
  }
}

常见失败处理：

现象	优先检查
`policy.action_parameter_required`	`public_site_url` 是否为空
`policy.action_parameter_invalid`	`public_site_url` 来源格式是否正确，以及后端派生出的 action 参数是否合法
`policy.action_unsupported`	当前策略是否真的是 `tencent_cos`
`storage.auth_failed`	Access Key / Secret Key 是否正确
`storage.permission_denied` 或 `storage.permission`	CAM 是否允许读取和写入 bucket CORS
`storage.misconfigured`	Bucket、endpoint、地域、请求头或 COS XML 是否被网关 / 代理改坏

5. 在 AsterDrive 创建 Tencent COS 存储策略

进入：

text

管理 -> 存储策略 -> 新建策略

选择驱动类型：

text

腾讯云 COS

保存前或保存后，都建议先点一次 测试连接。编辑已有策略时，如果 Access Key 或 Secret Key 字段留空，草稿连接测试会复用这条策略已经保存的凭据。这样你可以先测试 endpoint、bucket、基础路径、上传方式或 COS CI 开关的变更，不必每次重新粘贴 secret。新建策略没有可复用凭据，仍然必须填完整。

连接测试失败时，后台会优先展示后端返回的诊断说明。脚本或 API 客户端可以读取标准错误响应里的 error.diagnostic.message；这里会尽量保留 COS 返回的可排查信息，同时脱敏 secret、SAS、account key 等敏感值。

常见字段：

字段	示例
Endpoint	`https://asterdrive-prod-1250000000.cos.ap-guangzhou.myqcloud.com`
Bucket	`asterdrive-prod-1250000000`
Access Key	腾讯云访问密钥 ID
Secret Key	腾讯云访问密钥 Secret
Prefix / 基础路径	`prod/`
上传方式	初次建议 `relay_stream`
下载方式	初次建议 `relay_stream`

AsterDrive 会把 COS endpoint 和 bucket 规范化，并按 COS 虚拟托管风格处理底层 S3-compatible 请求。你不需要手动把 COS 当普通 S3 path-style 策略调。

6. 保存前先测试连接

保存前或保存后，先用后台的连接测试确认：

AsterDrive 服务器能访问 COS endpoint
bucket 名正确
凭证能读写目标 prefix
bucket 地域和 endpoint 匹配
服务器时间准确

如果连接测试失败，不要继续把用户切到这条策略。先按下面顺序查：

Endpoint 从 AsterDrive 服务器能不能访问
HTTPS 证书是否可信
Bucket 名是否正确
Access Key / Secret Key 是否正确
凭证权限是否覆盖目标 bucket / prefix
AsterDrive 服务器时间是否准确
Bucket 是否启用了需要的 COS / CI 能力

7. 配置存储原生处理

开启前先确认费用

存储原生处理会调用腾讯云 COS 数据万象。AsterDrive 会缓存生成后的缩略图、媒体信息等结果，避免每次访问都重新处理；但首次生成和云厂商侧处理请求仍可能产生费用。

入口在 COS 存储策略编辑页的 存储原生处理 区域。

总开关

启用存储原生处理 是当前策略的总开关。关闭时，这条策略不会调用 COS 数据万象能力。

原生缩略图

原生缩略图由这些条件共同决定：

启用存储原生处理 已开启
缩略图处理器为 storage_native
原生缩略图后缀 匹配当前文件名
当前 driver 支持 COS 原生缩略图

后缀是每条策略自己的配置。例如：

text

jpg, jpeg, png, webp, gif

不匹配的文件会继续走全局媒体处理器。

原生媒体信息

原生媒体信息解析由这些条件共同决定：

启用存储原生处理 已开启
启用原生媒体信息 已开启
原生媒体信息后缀 匹配当前文件名
当前 driver 支持 COS 原生媒体信息

后缀列表默认不填写。即使打开 启用原生媒体信息，后缀为空也不会触发 COS GetMediainfo / ci-process=videoinfo 请求。

你需要在每条 COS 策略里自行填写确认要交给 COS 解析的音视频后缀，例如：

text

mp4, mov, m4v, mkv, webm, mp3, m4a, flac, wav

不要把不确定的后缀一股脑全填进去。AsterDrive 的媒体信息有缓存，但第一次解析仍会发起 COS 数据万象请求。

文档预览

AsterDrive 当前不提供 COS 文档 HTML 预览，也不会从存储策略调用 COS 文档预览接口。这个能力不放入默认实现，主要是因为腾讯云当前公开价格页没有给文档 HTML 预览免费额度，误配后更容易产生不可控费用。

如果后续重新引入，应该单独做显式开关和独立后缀列表，不应复用当前的存储原生处理总开关直接放开。

8. 免费额度和计费边界

最近核对时间：2026-06-02（以腾讯云最新页面为准）。

按腾讯云当前公开口径：

能力	免费额度口径	AsterDrive 侧说明
基础图片处理	每月 10 TB 免费额度	原生图片缩略图会用到；超出或不符合免费额度规则后按腾讯云计费
视频元信息获取	首次使用后 6000 次 / 2 个月	原生媒体信息解析会用到 COS `GetMediainfo` / `ci-process=videoinfo`
视频截帧	首次使用后 6000 次 / 2 个月	后续如果启用 COS 视频缩略图，需要按这个口径评估
文档 HTML 预览	无免费额度	AsterDrive 当前不实现；后续如启用需要单独开关

腾讯云价格、免费额度、到期规则和区域差异可能变化。上线前请以腾讯云 COS / 数据万象最新价格页和控制台提示为准。

参考资料：

9. 创建测试策略组

不要一上来直接改默认策略组。建议先创建一个测试策略组。

进入：

text

管理 -> 策略组

创建策略组，例如：

text

COS Test Group

添加一条规则：

字段	建议
存储策略	刚创建的 COS 策略
优先级	保持默认或设为最先命中
文件大小范围	先覆盖所有大小，方便测试

10. 绑定测试用户或测试团队

绑定用户

进入：

text

管理 -> 用户 -> 用户详情

把测试用户的策略组改成刚才创建的 COS Test Group。

绑定团队

进入：

text

管理 -> 团队 -> 团队详情

把测试团队的策略组改成 COS Test Group。

团队空间上传时会按团队策略组走，不按个人用户策略组走。

11. 做一轮真实验收

用测试账号完成这些操作：

上传小文件
上传大文件
下载文件
预览图片
如果启用了原生缩略图，上传匹配后缀的图片并查看缩略图任务
如果启用了原生媒体信息，上传匹配后缀的音视频并查看文件信息面板
删除文件
从回收站恢复
分享文件并下载

验收时同时观察：

后台任务是否成功
COS bucket 里对象是否写到预期 prefix
浏览器控制台是否有 CORS 报错
AsterDrive 日志是否有 COS 403 / 404 / 签名错误
腾讯云控制台是否出现预期的 CI 调用记录或费用统计

12. 切真实流量

确认测试策略组没有问题后，再把真实用户或团队迁到目标策略组。

如果要迁移已有文件，不要直接改旧策略的 bucket、endpoint 或 prefix。正确做法是：

新建 COS 策略
测试连接和真实上传下载
用 管理 -> 存储策略 -> 迁移数据 创建迁移任务
迁移完成后调整策略组规则

已写入文件的策略，不要直接改真实落点

Bucket、endpoint、prefix 决定旧文件在哪里。直接改掉，旧文件可能会全部找不到。

腾讯云 COS 存储策略教程 ​

适合什么时候用 ​

COS 和 S3-compatible 的关系 ​

先分清你要配哪几层 ​

这篇用到的入口 ​

1. 准备 bucket 和 prefix ​

2. 准备访问凭证 ​

3. 先选上传和下载方式 ​

relay_stream 怎么工作 ​

presigned 怎么工作 ​

4. 配置 COS CORS ​

用 AsterDrive 自动配置 CORS ​

5. 在 AsterDrive 创建 Tencent COS 存储策略 ​

6. 保存前先测试连接 ​

7. 配置存储原生处理 ​

总开关 ​

原生缩略图 ​

原生媒体信息 ​

文档预览 ​

8. 免费额度和计费边界 ​

9. 创建测试策略组 ​

10. 绑定测试用户或测试团队 ​

绑定用户 ​

绑定团队 ​

11. 做一轮真实验收 ​

12. 切真实流量 ​

腾讯云 COS 存储策略教程

适合什么时候用

COS 和 S3-compatible 的关系

先分清你要配哪几层

这篇用到的入口

1. 准备 bucket 和 prefix

2. 准备访问凭证

3. 先选上传和下载方式

`relay_stream` 怎么工作

`presigned` 怎么工作

4. 配置 COS CORS

用 AsterDrive 自动配置 CORS

5. 在 AsterDrive 创建 Tencent COS 存储策略

6. 保存前先测试连接

7. 配置存储原生处理

总开关

原生缩略图

原生媒体信息

文档预览

8. 免费额度和计费边界

9. 创建测试策略组

10. 绑定测试用户或测试团队

绑定用户

绑定团队

11. 做一轮真实验收

12. 切真实流量