管理文件系统 layer 和 checkpoint
在 TiDB Cloud Filesystem 中，layer 会将文件更改与基础文件系统隔离，直到你提交这些更改。你可以使用 checkpoint 保留中间状态，并使用派生来独立探索更改。有关底层概念，请参见Layers and Checkpoints。
前提条件
开始之前，请确保：
- 安装 TiDB Cloud CLI。
- 拥有一个所有者 Token，或一个在现有目录上具有
read,list,write,delete权限的范围受限 Token。示例会在该目录下创建并删除一个子目录。 - 选择文件系统，并使其 Token 可供
ti使用。有关可用的访问方式，请参见访问现有文件系统。 - 使用 Bash 或 Zsh，并在整个示例过程中保持使用同一个 shell 会话。
创建 layer
在你的 Token 作用域内选择一个现有目录。使用所有者 Token 时可使用 /，或者将其替换为你的范围受限 Token 允许访问的目录，例如 /workspace。为本示例创建一个唯一的子目录：
parent_path="/"
base_path="${parent_path%/}/layer-example-$(date +%s)-$$"
ti fs create-directory --path "$base_path"
然后创建一个 layer：
ti fs create-layer \
--base-root-path "$base_path" \
--layer-name agent-task \
--durability-mode restore-safe \
--tag task=review
--base-root-path 用于确定 layer 覆盖基础文件系统的哪一部分。
当前 CLI 仅接受 restore-safe 作为 --durability-mode 的值。有关所有可用选项，请参见 create-layer 命令参考。
保存返回的 layer_id，供后续命令使用：
layer_id="<returned-layer-id>"
请使用 ID，而不是 layer 名称，因为 layer 名称可能不是唯一的。
使用并检查 layer 更改
使用返回的 layer ID 向 layer 写入一个示例文件：
printf 'Layer review proposal\n' | ti fs copy-file \
--from-stdin \
--to-remote "$base_path/proposal.md" \
--layer-id "$layer_id"
检查该 layer 及其更改：
ti fs describe-layer --layer-id "$layer_id"
ti fs diff-layer --layer-id "$layer_id"
列出所选文件系统中的所有 layer：
ti fs list-layers --output text
尚未提交的更改会保留在 layer 中。不选择 layer 的文件操作会访问基础文件系统，因此不会显示其中未提交的更改。
只有 copy-file、find-files 和 search-file-content 支持 --layer-id。read-file、list-files、describe-file、delete-file、move-file 和 create-directory 始终作用于基础文件系统。要读取 layer 中文件的内容，请按挂载可写 layer 或验证 checkpoint 的文件内容中的说明进行操作。
挂载可写 layer
要使用本地工具，请先完成 FUSE 前提条件，然后挂载该 layer。WebDAV 不支持 layer 或 checkpoint。
layer_mount="$(mktemp -d "$HOME/ti-fs-layer.XXXXXX")"
ti fs mount-file-system \
--mount-path "$layer_mount" \
--remote-path "$base_path" \
--layer-ref "$layer_id" \
--driver fuse
cat "$layer_mount/proposal.md"
预期输出：Layer review proposal。要验证隔离，请在不选择 layer 的情况下从基础文件系统读取：
ti fs read-file --path "$base_path/proposal.md"
预期会出现 not-found 错误，因为该 layer 尚未提交。如果该文件在基础文件系统中可见，请先停止操作并检查 layer 选择是否正确，然后再继续。
创建 checkpoint
checkpoint 会保留 layer 持久历史中的某个时间点。
如果该 layer 已有可写的 FUSE 挂载，请在创建 checkpoint 之前停止写入、关闭打开的文件，并对刷写挂载：
ti fs drain-file-system \
--mount-path "$layer_mount"
然后创建 checkpoint：
ti fs create-layer-checkpoint \
--layer-id "$layer_id" \
--checkpoint-id seed \
--label "before review"
要验证 checkpoint 的文件内容，请将其挂载到另一个本地路径：
checkpoint_mount="$(mktemp -d "$HOME/ti-fs-checkpoint.XXXXXX")"
ti fs mount-file-system \
--mount-path "$checkpoint_mount" \
--remote-path "$base_path" \
--layer-ref "$layer_id" \
--checkpoint-id seed \
--driver fuse
cat "$checkpoint_mount/proposal.md"
ti fs unmount-file-system --mount-path "$checkpoint_mount"
预期输出：Layer review proposal。checkpoint 挂载为只读。如果读取时发生假死，请参见挂载故障排查。
派生 layer
如果你希望基于该 checkpoint 继续独立工作，请派生一个新的可写 layer。否则，请跳转到提交或丢弃 layer 更改。
ti fs fork-layer \
--parent-layer-ref "$layer_id" \
--layer-name experiment \
--checkpoint-id seed
单独保存派生后返回的 layer_id：
forked_layer_id="<returned-forked-layer-id>"
要检查该派生 layer 固定的祖先链：
ti fs list-layer-chain --layer-ref "$forked_layer_id"
创建派生后，对父 layer 和子 layer 所做的更改彼此独立。
提交或丢弃 layer 更改
如果该 layer 具有可写的 FUSE 挂载点，请先停止写入方、关闭已打开的文件，并在选择后续操作前将其卸载：
ti fs unmount-file-system \
--mount-path "$layer_mount"
优雅的卸载会自动刷写待处理的写入。
选择以下其中一种结果：commit 会将更改应用到基础文件系统；rollback 会丢弃这些更改。要提交，请执行：
ti fs commit-layer --layer-id "$layer_id"
提交成功后，通过基础文件系统验证内容：
ti fs read-file --path "$base_path/proposal.md"
预期输出：Layer review proposal。
提交会将该 layer 的有效更改应用到基础文件系统。如果该 layer 是通过派生另一个 layer 创建的，提交它不会将更改合并回其父 layer。
如果基础文件系统中存在冲突更改，提交可能会失败，而不是自动合并这些更改。在决定如何继续之前，请保留该 layer，并检查其更改以及基础文件系统。
如果你选择丢弃更改，请执行以下命令，而不是提交：
ti fs rollback-layer --layer-id "$layer_id"
回滚会丢弃当前 layer 的更改。它不会将该 layer 重置到更早的 checkpoint。若要从某个 checkpoint 继续，请从该 checkpoint 派生一个新的 layer。
删除 layer
如果你创建了一个派生 layer，请先删除它，再删除其父 layer：
ti fs delete-layer --layer-ref "$forked_layer_id"
然后删除父 layer：
ti fs delete-layer --layer-ref "$layer_id"
删除 layer 会放弃该 layer，但不会立即擦除其全部历史记录。如果该 layer 仍有活动的子孙 layer，默认情况下该命令会失败。
或者，如果要同时放弃某个 layer 及其所有活动的子孙 layer，请使用 --cascade：
ti fs delete-layer \
--layer-ref "$layer_id" \
--cascade
仅当你也打算放弃这些子孙 layer 时，才使用 --cascade。
在卸载示例挂载点并删除示例 layer 后，删除基础目录：
ti fs delete-file --path "${base_path:?Set the example directory first}" --recursive
ti fs describe-file --path "$base_path"
预期 describe-file 会返回 not-found 错误。成功卸载后，使用 rmdir "$layer_mount" 和 rmdir "$checkpoint_mount" 删除你创建的本地目录。删除示例文件不会立即擦除已放弃 layer 的历史记录。