tencentcloud-cos

腾讯云 COS（对象存储）

通过官方的 cos-python-sdk-v5 客户端管理腾讯云 COS 存储桶和对象。

**设置：**有关 SecretId / SecretKey / 地域的设置，请参阅 腾讯云认证。SDK 会从环境变量中读取 TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY / TENCENTCLOUD_REGION。

CLI（首选）

该技能附带 scripts/cos.py——一个独立的 CLI，可封装下方的所有 COS 操作。当用户的请求与某个子命令直接对应时，优先使用此 CLI，而不要手动编写 SDK 调用；维护中的代码路径都会使用它进行测试。

# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block).
COS="$SKILL_DIR/scripts/cos.py"; [ -f "$COS" ] || COS=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/cos.py' 2>/dev/null | head -1)
[ -f "$COS" ] || { echo "tencentcloud-cos script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }

python3 $COS buckets                                  # list all buckets
python3 $COS ls mydata-1250000000 --prefix images/    # list objects
python3 $COS upload mydata-1250000000 ./report.pdf --key docs/report-2026.pdf
python3 $COS download mydata-1250000000 docs/report-2026.pdf --output ./out.pdf
python3 $COS url mydata-1250000000 docs/report-2026.pdf --expires 3600
python3 $COS du mydata-1250000000 --prefix logs/
python3 $COS cp mydata-1250000000 old/path.txt new/path.txt
python3 $COS batch-delete mydata-1250000000 --prefix temp/old/ --dry-run
python3 $COS batch-delete mydata-1250000000 --prefix temp/old/   # actually delete
python3 $COS info mydata-1250000000 docs/report-2026.pdf

运行 python3 $COS --help（或 python3 $COS <cmd> --help）查看完整参数。传入 --region <region> 可针对单次调用覆盖地域。

适用场景

• 列出账号下的所有 COS 存储桶
• 列出存储桶中的对象（按前缀 / 分隔符筛选）
• 上传 / 下载文件
• 删除单个对象，或按前缀批量删除
• 生成预签名下载 URL（用于共享私有存储桶中的文件）
• 计算存储桶 / 前缀的存储用量
• 在存储桶内复制对象

依赖项

pip install cos-python-sdk-v5

存储桶命名

腾讯云存储桶名称始终以 -<APPID> 结尾，例如 mydata-1250000000。APPID 是数字形式的账号标识符。SDK 在任何需要指定存储桶名称的地方都要求使用完整的 name-APPID 格式。

快速开始

import os
from qcloud_cos import CosConfig, CosS3Client

config = CosConfig(
    Region=os.environ["TENCENTCLOUD_REGION"],
    SecretId=os.environ["TENCENTCLOUD_SECRET_ID"],
    SecretKey=os.environ["TENCENTCLOUD_SECRET_KEY"],
    Scheme="https",
)
client = CosS3Client(config)

工作流

列出所有存储桶

resp = client.list_buckets()
for b in resp["Buckets"]["Bucket"]:
    print(b["Name"], b["Location"], b["CreationDate"])

列出存储桶中的对象

# Single page (max 1000 objects)
resp = client.list_objects(Bucket="mydata-1250000000", Prefix="images/", Delimiter="/")
for obj in resp.get("Contents", []):
    print(obj["Key"], int(obj["Size"]), obj["LastModified"])

# Paginate through everything
marker = ""
while True:
    resp = client.list_objects(Bucket="mydata-1250000000", Prefix="logs/", Marker=marker, MaxKeys=1000)
    for obj in resp.get("Contents", []):
        print(obj["Key"])
    if resp.get("IsTruncated") != "true":
        break
    marker = resp["NextMarker"]

上传文件

# Streaming upload — handles multipart / resumes / 5GB+ files transparently
client.upload_file(
    Bucket="mydata-1250000000",
    Key="uploads/2026/report.pdf",
    LocalFilePath="./report.pdf",
)

下载文件

client.download_file(
    Bucket="mydata-1250000000",
    Key="uploads/2026/report.pdf",
    DestFilePath="./report.pdf",
)

生成预签名下载 URL

# Default expiry 1 hour; pass Expired=86400 for 24h, etc.
url = client.get_presigned_url(
    Method="GET",
    Bucket="mydata-1250000000",
    Key="uploads/2026/report.pdf",
    Expired=3600,
)
print(url)

删除单个对象

client.delete_object(Bucket="mydata-1250000000", Key="uploads/old-file.txt")

按前缀批量删除（提供试运行保护）

# 1) Always preview first
to_delete = []
marker = ""
while True:
    resp = client.list_objects(Bucket="mydata-1250000000", Prefix="temp/old/", Marker=marker, MaxKeys=1000)
    for obj in resp.get("Contents", []):
        to_delete.append({"Key": obj["Key"]})
    if resp.get("IsTruncated") != "true":
        break
    marker = resp["NextMarker"]

print(f"Would delete {len(to_delete)} objects")
for o in to_delete[:10]:
    print("  -", o["Key"])

# 2) Confirm with the user before running this:
# resp = client.delete_objects(Bucket="mydata-1250000000", Delete={"Object": to_delete, "Quiet": "false"})
# print("Deleted:", len(resp.get("Deleted", [])))

计算存储桶 / 前缀大小（du）

total_bytes = 0
total_count = 0
marker = ""
while True:
    resp = client.list_objects(Bucket="mydata-1250000000", Prefix="logs/", Marker=marker, MaxKeys=1000)
    for obj in resp.get("Contents", []):
        total_bytes += int(obj["Size"])
        total_count += 1
    if resp.get("IsTruncated") != "true":
        break
    marker = resp["NextMarker"]

print(f"{total_count} objects, {total_bytes / 1024 / 1024:.1f} MiB")

在存储桶内复制对象

client.copy_object(
    Bucket="mydata-1250000000",
    Key="new/path.txt",
    CopySource={
        "Bucket": "mydata-1250000000",
        "Key": "old/path.txt",
        "Region": os.environ["TENCENTCLOUD_REGION"],
    },
)

安全注意事项

• 执行批量删除前，请与用户确认。delete_objects 调用不可撤销——COS 默认不提供回收站。
• 预签名 URL 是持有者令牌——任何拥有该 URL 的人都可以在其过期前访问对象。除非用户明确要求更长的有效期，否则默认设置较短的有效期（1 小时）。
• 跨地域操作需要在 CopySource 中指定源 / 目标地域。地域不匹配会触发 NoSuchBucket。
• download_file 会直接覆盖目标文件，不会事先询问。使用循环编写脚本时，请谨慎选择 DestFilePath。

错误模式

症状	可能原因
NoSuchBucket	地域错误，或存储桶名称中的 APPID 后缀错误
AccessDenied	子账号缺少 QcloudCOSReadOnlyAccess / QcloudCOSDataReadOnly 等权限
SignatureDoesNotMatch	粘贴 SecretKey 时带有前导 / 尾随空格，或系统时钟误差超过 5 分钟
RequestTimeTooSkewed	同上——时钟偏差

控制台链接

• COS 控制台：https://console.cloud.tencent.com/cos/bucket
• API 参考：https://www.tencentcloud.com/document/product/436/41330