GCS存储桶特定文件夹PNG图片上传异常排查求助

权限与身份验证 #

• 检查K8s环境使用的GCS服务账号权限：确认是否持有storage.objects.create和storage.objects.list权限，重点验证目标存储桶前缀（GCS无实际文件夹，仅为对象前缀）的权限范围
• 对比本地与K8s的身份凭证：本地可能使用个人密钥或默认应用凭证，K8s通常用Workload Identity或挂载的Secret密钥，确认两类凭证对应的GCP项目、存储桶是否完全一致
• 排查条件性IAM策略：检查存储桶IAM是否设置了IP限制、时间窗口等规则，确认K8s集群的出口IP在允许范围内

路径与命名校验 #

• 验证目标前缀的大小写与格式：GCS路径大小写敏感，检查K8s代码中指定的目标前缀是否和本地完全一致（包括首尾斜杠、大小写）
• 排查前缀冲突：确认存储桶中是否存在与目标前缀同名的对象（例如存在名为target-folder/的对象，会干扰前缀匹配的列表展示）
• 核对文件名处理逻辑：检查K8s环境中获取的文件名是否存在特殊字符转义错误，或环境变量注入的文件名与本地测试数据不一致

WriteChannel使用细节 #

• 确认WriteChannel是否正确关闭：flush()仅刷新缓冲区，必须调用close()才能完成对象上传。本地调试时JVM退出会自动回收资源，但K8s长进程中未主动关闭会导致上传未完成
• 对比写入字节数：检查本地与K8s环境中实际写入GCS的字节数是否一致，排查K8s中数据流提前终止、读取不完整的情况
• 检查分块上传状态：若启用分块上传，确认所有分块已上传并完成提交，避免出现分块上传未收尾的情况

K8s环境特定排查 #

• 检查网络代理/防火墙：确认K8s集群的出站流量是否经过代理，是否对storage.googleapis.com域名做了拦截或篡改，导致请求日志显示成功但实际未抵达GCS
• 验证容器文件系统：若上传的是容器内文件，检查文件是否存在、可读，PVC挂载的文件权限是否与本地测试环境一致
• 校验日志准确性：确认K8s日志中是否捕获了GCS返回的200/201成功状态码，而非仅打印代码中的“上传成功”提示（避免代码逻辑错误导致误判）

GCS端隐藏问题 #

• 检查版本控制状态：若存储桶启用版本控制，确认是否存在旧版本覆盖新版本的情况，或控制台默认展示的版本与实际上传版本不符
• 排查对象保留策略：检查存储桶或目标前缀是否设置了对象保留策略，导致上传的对象无法被列出
• 使用gsutil验证：在K8s容器中安装gsutil工具，使用相同凭证执行上传、列表操作，复现问题以排除代码层面的逻辑错误

内容的提问来源于stack exchange，提问作者Mentee