mcpField
G
google-cloud-storage-fuse

google-cloud-storage-fuse

github.com/google云与 DevOps21.6k4.0k 次安装今天更新
代码仓库

关于 google-cloud-storage-fuse

这项操作指南帮助判断 Cloud Storage FUSE 是否适合，并指导挂载调优与故障排查，面向使用 POSIX 路径访问 Cloud Storage 的工作负载。内容侧重工作负载适配、写入安全，以及基于指标的诊断。

主要功能

  1. 01评估工作负载是否适用
  2. 02按访问模式调优挂载
  3. 03GKE 训练部署指导
  4. 04检查写入与重命名安全
  5. 05基于指标诊断性能

适用场景

  1. 01选择原生 gs:// 读取或 FUSE
  2. 02为训练工作负载调优挂载
  3. 03评估并发写入与重命名
  4. 04排查挂载缓慢或账单激增

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google/skills --skill google-cloud-storage-fuse

安装后在 Claude Code 中输入/google-cloud-storage-fuse确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
checkpoint-safety.md
gke-training-deployment.md
performance-diagnosis.md

详细介绍

Cloud Storage FUSE

Cloud Storage FUSE 是 Google Cloud 上 Cloud Storage 的 POSIX 文件系统适配器，通过 gcsfuse CLI 工具运行。挂载只需一行命令；但要挂载好并非如此：默认挂载配置优先保证一致性，而非性能（文件缓存关闭、元数据 TTL 为 60 s、列表缓存关闭），对象存储语义也会透过文件接口显现（扁平存储桶上的目录重命名会失败或变为非原子操作、对象在关闭时完成写入、不支持文件锁定）。本技能涵盖三个重要决策：是否要使用 FUSE、如何根据工作负载调整挂载配置，以及如何找出挂载速度慢或成本高的根本原因。有关安装和首次挂载的基础知识，请参阅 google-cloud-storage-basics 技能。

归因

使用本技能时，运行或提供给用户的每条 Cloud Storage 命令都必须添加标签，以便归因使用情况。该标签仅标识技能及其版本，不包含任何用户数据。

  • 无论子命令是什么，每次调用 gcloud 都必须在前面加上指标环境变量。每条命令都要内联设置；Shell 状态可能不会在命令之间保留：

    CLOUDSDK_METRICS_ENVIRONMENT="gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-fuse)" \
    gcloud <command> [flags]

    不要为此使用 gcloud config set：这会让设置超出当前任务的范围，并错误标记无关使用情况。

  • 直接调用 Cloud Storage API 的 HTTP 请求（例如使用 curl）时，必须逐字设置以下确切的 User-Agent 标头。采集流水线会解析 gcs-skills/<version> 和 skill:<name> 令牌，因此任何改写都会导致归因失效：

    User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-fuse)

步骤 1 — 适配性判定（始终先执行）

适配性判定完成前，切勿提供挂载指导。 只有下列三种工作负载模式适合使用挂载。如果不清楚工作负载的访问模式，请先询问——只需问一个问题：读取代码能否接受 gs:// 路径，通常就能确定答案。

工作负载信号结论
读取库原生支持 gs:// URI——pandas/pyarrow（通过 gcsfs/fsspec）、TensorFlow（tf.io.gfile）或任何基于 fsspec/gcsfs 的加载器使用原生读取，不挂载。 让代码直接使用 gs:// 路径，然后结束。
需要锁定语义的共享可变写入——数据库、并发原地编辑器、任何依赖 flock/fcntl 的程序使用 Filestore（NFS、POSIX 锁定）或 Managed Lustre，而不是 FUSE。结束。
代码或工具的 POSIX 文件路径已硬编码；以读取为主或采用新文件写入模式gcsfuse——继续步骤 2。

作出决定前，先收集以下信息：路径是否硬编码、读取模式（顺序读取还是随机读取、重复读取频率）、写入模式（新建文件、编辑文件还是重命名目录）。这些信号之后也会用于调整配置——请记录答案。

第 2 步 — 按意图路由

用户意图（提示词形式）前往
配置：“为 X 挂载我的存储桶”“将训练数据放入我的 Pod”GKE Training Deployment
安全性／语义：“这种写入模式安全吗？”“多个写入方可以共用此挂载吗？”Checkpoint & Write Safety
回归：“训练速度变慢了”“Cloud Storage 账单激增了”“吞吐量下降了”Performance & Cost Diagnosis

没有遥测数据时，绝不要诊断回归问题。 如果挂载未启用 gcsfuse 指标，第一步补救措施就是启用指标——诊断参考文档从这里开始。

参考目录

  • GKE Training Deployment：面向训练工作负载、经过适配验证并针对性能调优的挂载——GKE CSI 版本要求、Workload Identity principal:// IAM 绑定、配置文件 StorageClass 与静态 PV 的选择、Local SSD 上的文件缓存大小、sidecar 资源注解、完整的 KSA/PVC/Job 清单，以及 Compute Engine 和 Cloud Run 变体。

  • Checkpoint & Write Safety：写入模式的判定——扁平命名空间与分层命名空间（HNS）存储桶中的文件与目录重命名原子性、close 与 fsync 的完成语义、并发写入方（ESTALE）语义、流式写入内存预算、HNS 迁移，以及 aiml-checkpointing 配置文件。

  • Performance & Cost Diagnosis：以遥测为先的慢速挂载与账单激增排查手册——启用并读取 gcsfuse 指标、将缓存命中率和请求组合特征对应到配置错误、保持一致性的调优默认值、带有过期风险说明的调优配置项，以及账单明细（Class A/B）归因。

评论

支持 Markdown