文档目标:指导用户将指定服务器上的图片文件夹迁移至腾讯云对象存储(COS)中,支持断点续传、增量同步,确保数据完整、安全。
前置条件:
1、已通过 SSH 登录到待迁移的服务器(可以是任意云厂商或本地机器)。
2、已拥有腾讯云账号,并创建了目标存储桶(Bucket)。
3、已获取腾讯云账号的 SecretId 和 SecretKey(可在控制台“访问管理”->“API密钥管理”中获取)

第一步:下载与安装 COSCLI 工具
1、下载二进制文件(以 Linux x86_64 为例):wget https://cosbrowser.cloud.tencent.com/software/coscli/coscli-linux
2、移动至系统路径并赋予执行权限:
mv coscli-linux /usr/local/bin/coscli
chmod 755 /usr/local/bin/coscli
3、验证安装:coscli --version
如果显示版本号,说明安装成功。

第二步:初始配置
1、运行配置向导:
coscli config
2、根据提示依次输入以下信息:
Input Your SecretId: 输入您的 SecretId
Input Your SecretKey: 输入您的 SecretKey(输入时不显示字符)
Input Your Session Token: 直接按回车跳过(永久密钥无需填写)
Input Your Mode: 直接按回车(使用默认的 SecretKey 模式)
Input Your Cvm Role Name: 直接按回车跳过
Input Auto Switch Host: 直接按回车跳过(使用默认 false)
Input Your Bucket's Name:存储桶名称(概览页面复制)
Input Bucket's Alias: 直接按回车跳过(使用存储桶原名)
Input Your Endpoint: 输入您存储桶所在的地域 Endpoint,例如 cos.ap-beijing.myqcloud.com(具体格式见下文)
如何获取 Endpoint?
登录腾讯云控制台,进入目标存储桶的“概览”页,在“基本信息”中找到“访问域名”,格式为 <BucketName-APPID>.cos.ap-beijing.myqcloud.com,取 cos.ap-beijing.myqcloud.com 部分填入。
3、配置文件保存位置:
配置完成后,信息将保存在 ~/.cos.yaml 文件中。如需修改,可再次运行 coscli config 或直接编辑该文件。
第三步:测试连接
使用 ls 命令列出存储桶内容,验证配置是否正确。
coscli ls cos://your-bucket-name
将 your-bucket-name 替换为您的真实存储桶名称(例如 example-1250000000)。
预期输出:如果连接成功,会显示存储桶中的文件列表;若报错,请检查 SecretId/SecretKey 和 Endpoint 是否正确。
第四步:执行图片迁移
4.1 基本同步命令
使用 sync 命令进行递归同步(推荐):
coscli sync <本地文件夹路径> cos://<存储桶名称>/<云端目标路径> -r -e <Endpoint>
-r:递归处理所有子文件夹,必须添加。
-e:指定 Endpoint(如果配置时已填写,可省略;若省略,需确保配置文件中的 Endpoint 正确)。
示例(将服务器 /data/wwwroot/mysite/uploads/2025/ 同步到存储桶的 images/2025/ 目录):
coscli sync /data/wwwroot/mysite/uploads/2025/ cos://example-1250000000/images/2025/ -r -e cos.ap-beijing.myqcloud.com
4.2 增量同步与断点续传
sync 命令会自动对比本地与云端的文件(基于 CRC64 校验),只上传新增或修改过的文件。若传输中断,重新运行 相同命令,它会从中断处继续,不会重复上传已成功的文件。
4.3 只上传特定类型文件
通过 --include 参数筛选文件类型(支持正则表达式):
coscli sync /data/wwwroot/mysite/uploads/ cos://example-1250000000/images/ -r --include ".*\.(jpg|png|gif)$"
以上命令只上传 .jpg、.png、.gif 文件。
第五步:验证迁移结果
1、查看云端文件:
coscli ls cos://example-1250000000/images/ -r
2、登录腾讯云控制台,进入对应存储桶,对比文件数量与大小,确保与源文件夹一致。
注意事项与常见问题
1、权限问题:如果遇到 AccessDenied 错误,请检查您的 SecretId/SecretKey 是否有该存储桶的写入权限。建议使用子账号并授予 QcloudCOSDataFullControl 策略。
2、Endpoint 选择:
如果您的服务器是腾讯云 CVM,且与存储桶位于同一地域,建议使用内网 Endpoint(如 cos.ap-beijing.myqcloud.com 无需修改,内网自动解析),可免流量且速度更快。
如果服务器在阿里云或其他云厂商,请使用公网 Endpoint(同上格式)。
3、测试先行:首次迁移前,建议先同步一个小文件夹(如只包含几张图片),确认速度、权限无误后,再对整个大文件夹执行。
4、断点续传保障:sync 命令天生支持断点续传,迁移中断时无需担心,直接重新运行命令即可。
5、安全提示:SecretId 和 SecretKey 是账号的核心凭证,请勿泄露。建议使用子账号密钥,并定期轮换。