常见原因集中于API密钥无效或存储桶权限策略未正确授予，需依次验证密钥状态与最小权限、检查Bucket Policy显式拒绝规则、确认子账号CAM授权链完整、核对Endpoint与Region配置一致性，并排查STS临时凭证时效及权限边界问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在配置WorkBuddy接入腾讯云COS时遇到连接失败，常见原因集中于API密钥无效或存储桶权限策略未正确授予。以下是针对性排查与修复步骤：
一、验证API密钥有效性及作用域范围
WorkBuddy依赖AccessKey ID与SecretKey完成身份认证，若密钥已禁用、过期、权限不足或存在空格等不可见字符，将直接导致403或401错误。
1、登录腾讯云控制台，进入API密钥管理页面，确认所用密钥状态为“启用”且未被轮换失效。
2、检查密钥是否绑定最小权限策略：点击密钥操作列的“查看策略”，确认其关联策略中包含cos:PutObject、cos:GetObject、cos:ListObjectsV2三项核心动作，资源限制应精确到目标Bucket路径（如qcs::cos:ap-shanghai:uid/1250000000:bucket-1250000000-1250000000/*）。
3、复制密钥值后，在文本编辑器中全选并查看末尾是否有不可见空格或换行符；若使用剪贴板管理工具，请清空缓存后重新复制。
4、在WorkBuddy部署服务器上执行curl测试：运行curl -H "Authorization: <strong><font color="green">替换为实际签名串</font></strong>" "https://your-bucket-1250000000.cos.ap-shanghai.myqcloud.com/?list-type=2&max-keys=1"，观察是否返回XML格式对象列表或明确的403 Forbidden提示。
二、检查存储桶策略（Bucket Policy）是否显式拒绝请求
即使API密钥具备权限，若存储桶策略中存在"Effect": "Deny"规则且匹配当前请求主体（Principal）、IP或Referer，COS仍将返回403错误，该拒绝优先于任何Allow声明。
1、进入腾讯云COS控制台，定位目标存储桶，点击左侧菜单“权限管理”→“Bucket Policy”。
2、检查策略JSON中是否存在针对当前调用方UIN或临时凭证Role的显式拒绝语句，特别关注Condition块内是否设置了aws:SourceIp白名单但未包含WorkBuddy服务出口IP，或referer限制未放行后端域名。
3、若策略中存在"Resource": "arn:aws:s3:::*"或"Action": "*"等宽泛授权，请立即删除；应严格限定为"Resource": ["arn:aws:s3:::your-bucket-name", "arn:aws:s3:::your-bucket-name/*"]及必要动作。
4、确认策略语法合法：粘贴当前Policy至Policy Sentry Validator校验JSON结构与COS策略规范兼容性。
三、核对子账号授权链完整性
当使用子账号密钥时，主账号必须通过CAM完成显式授权，否则子账号即使拥有密钥也无法继承任何COS操作权限。
1、以主账号登录控制台，进入“访问管理（CAM）”→“用户”，搜索并打开对应子账号详情页。
腾讯云跨账号资源迁移工具，支持将账号A的VPC、CLB、NAT、CVM、安全组等资源迁移至账号B，通过CCN云联网实现跨账号网络互通，提供自动扫描、配置生成、Terraform部署功能。
2、切换至“授权策略”标签页，确认已绑定至少一个自定义策略，且该策略的Effect为Allow、Action包含cos:*或细分动作、Resource精确指向目标Bucket ARN。
3、若策略通过“用户组”间接授予，请点击用户组名称，进入其策略列表，逐项验证每条策略是否生效且无冲突。
4、在子账号详情页的“安全设置”中，确认“编程访问”开关已开启，并记录该子账号UIN（10位数字），用于后续Policy中Principal字段比对。
四、验证Endpoint与Region配置一致性
COS服务采用区域化部署，若application.yml中配置的region与实际Bucket所在地域不一致，或Endpoint域名未匹配该地域标准格式，会导致签名计算失败并触发403。
1、在COS控制台打开目标存储桶，查看顶部导航栏显示的“地域”（如“华东地区（上海）”），对应标准Region缩写为ap-shanghai。
2、确认application.yml中storage.cos.region字段值与之完全一致，不得使用中文、别名或拼写错误（如shanghai或cn-shanghai）。
3、检查storage.cos.endpoint是否采用官方推荐格式：https://cos.[region].myqcloud.com（如https://cos.ap-shanghai.myqcloud.com），禁止混用s3.前缀或非标准端口。
4、若Bucket为多AZ部署或启用了全球加速，请勿使用加速域名替代标准Endpoint，WorkBuddy SDK不支持自动解析加速路由。
五、排查临时凭证（STS）时效与权限边界
若WorkBuddy移动端或后端通过STS获取临时密钥访问COS，过期时间不足、SessionName冲突或Policy权限收缩过度均会导致连接中断。
1、检查后端调用GetFederationToken接口时传入的DurationSeconds参数，确保不低于900秒（15分钟），避免高频刷新引发限流。
2、确认下发至客户端的Token字段（即SecurityToken）已完整传递，且SDK初始化时将其与TmpSecretId、TmpSecretKey一同载入，缺失Token将视为永久密钥校验。
3、审查STS调用时附带的Policy文档，验证其中Resource是否覆盖上传路径前缀（如"arn:aws:s3:::bucket-name/video/workbuddy/${uid}/*"），且未使用${}变量未被后端正确渲染。
4、在客户端日志中捕获STS凭证的Expiration时间戳，与系统当前时间比对，若差值小于300秒，需调整后端刷新逻辑或延长DurationSeconds。
