命令行工具

本节基于当前仓库源码中的 curvine-cli、build/cv 和 build/bin/dfs 整理 Curvine 的命令行入口。当前主要有三类:

  • 原生 Rust CLI cv:推荐入口,功能最完整,命令树来自 curvine-cli。
  • 兼容包装器 dfs:发行包自带的兼容入口,fs / report 走 Java CurvineShell,保留 Hadoop FsShell 风格。
  • POSIX / FUSE:通过 FUSE 挂载后,直接在挂载点使用标准 Linux 命令。

原生 CLI:cv

查看总览:

cv --help

当前源码对应的顶层命令为:

Usage: cv [OPTIONS] <COMMAND>

Commands:
  bench
  fs
  fsck
  report
  load
  export
  transfer
  load-list
  mount
  umount
  node
  admin
  version

load-status、cancel-load、transfer-status、cancel-transfer 仍然可用,但不再列入 --help;它们作为旧版任务 API 的兼容快捷命令保留。

所有 cv 命令都支持以下全局参数:

全局参数说明
--conf <PATH>仅覆盖本次调用的集群配置文件。未指定时 CLI 使用正常配置路径或 CURVINE_CONF_FILE。
--master-addrs <ADDRS>直接覆盖客户端配置里的 Master 地址列表,例如 m1:8995,m2:8995。

生产环境通常直接使用 cv,因为集群配置已安装,或已通过 CURVINE_CONF_FILE 选择。仅在迁移或诊断时使用 --conf 指向非默认配置。cv mount --config key=value 仍表示 UFS 配置项。

约定:

  • 生产环境将发行包的 bin/ 加入 PATH 后,直接使用 cv。
  • 通过 cargo run -p curvine-cli -- ... 运行时,帮助中的程序名会显示为 curvine-cli。
  • 本文中的 <PATH>、<JOB_ID> 等为位置参数;[OPTION] 表示可选项。

1. report:查看集群状态

用法: cv report [json|all|capacity|used|available]

命令说明
cv report默认概览,包含 active master、容量、inode/block 数和 worker 列表。
cv report json以 JSON 输出完整 MasterInfo。
cv report all --show-workers false文本概览,可关闭 worker 明细。
cv report capacity [WORKER_ADDRESS]查看集群容量,或查看单个 worker 的容量详情。
cv report used输出每个 live worker 的已用容量。
cv report available输出每个 live worker 的可用容量。

示例:

cv report
cv report json
cv report all --show-workers false
cv report capacity
cv report capacity 192.168.1.10
cv report used
cv report available

当前实现里 cv report capacity <WORKER_ADDRESS> 按 worker 的 IP 地址匹配,不是按 hostname:port 匹配。


2. node:管理 Worker 节点

用法: cv node [OPTIONS] [-- <NODES>...]

选项说明
-l, --list列出 live / lost worker。
--versions展示所有在线 worker 的版本分布。
--add-decommission <NODES>...将一个或多个 worker 加入退役列表。
--remove-decommission <NODES>...将一个或多个 worker 从退役列表移除。

<NODES> 支持两种形式:

  • 多个空格分隔参数:host1:8997 host2:8997
  • 单个逗号分隔参数:host1:8997,host2:8997

示例:

cv node -l
cv node --versions
cv node --add-decommission host1:8997 host2:8997
cv node --add-decommission host1:8997,host2:8997
cv node --remove-decommission host1:8997

cv node --versions 打印在线 worker 的版本分布,优先使用心跳上报的结构化 component_info.release_version,回退到旧的 software_version 字符串:

Version Distribution:
----------------------------------------
  0.4.0-alpha              : 3 worker(s)
  0.4.0-beta               : 5 worker(s)
  legacy (0.3.0-test)      : 1 worker(s)
----------------------------------------
  total                    : 9 worker(s)

这些版本的含义以及 master 如何评估混合版本 peer,请参阅版本管理与兼容性。

当前实现会在退役 API 调用前把 hostname:port 截断为 hostname。也就是说,端口主要用于人类可读和输入格式统一。


3. fs:文件系统操作

用法: cv fs [OPTIONS] <COMMAND> [ARGS]

fs 自身额外支持一个全局开关:

选项说明
--cache-only仅查询 / 操作 Curvine 已缓存的数据,关闭统一 UFS 视图。

当前源码里 fs 支持的子命令如下:

命令说明
cv fs ls [PATH]列目录,默认路径 /。
cv fs mkdir <PATH> [-p|--parents]创建目录。
cv fs put <LOCAL_PATH> <REMOTE_PATH> [-n|--no-clobber]上传本地文件到 Curvine;-n 不覆盖已存在的目标。
cv fs get <PATH> <LOCAL_PATH>下载 Curvine 文件到本地。
cv fs cat <PATH> [--offset N] [--length N]输出文件内容,可指定字节范围。
cv fs tail <PATH> [-n|--bytes N]输出文件末尾的字节,默认 1024。
cv fs touch <PATH>创建空文件或更新时间戳。
cv fs rm <PATH> [-r|--recursive] [--skip-trash] [--async] [-f|--force]删除文件或目录。--skip-trash 绕过回收站(如已启用)直接永久删除;--async 立即返回,由 Master 在后台回收(仅限 Curvine 路径);-f 忽略不存在的路径。
cv fs trash ls列出回收站中的条目。
cv fs trash restore <TRASH_PATH> [--dst <PATH>] [--overwrite]将回收站条目(如 /.Trash/1700000000000-42)恢复到原位置,或恢复到 --dst 指定的路径。
cv fs trash empty [--wait]永久删除回收站中的所有条目;--wait 等待 Master 回收完毕并输出回收的大小。
cv fs stat <PATH> [--json]查看路径状态;--json 以 JSON 输出。
cv fs count <PATH>统计目录下文件 / 目录数量。
cv fs mv <SRC_PATH> <DST_PATH>移动或重命名。
cv fs du <PATH> [-h] [-v]查看目录空间占用。
cv fs df [-h]查看文件系统容量 / 已用 / 可用。
cv fs chmod <MODE> <PATH> [--recursive]修改权限。
cv fs chown <OWNER:GROUP> <PATH> [--recursive]修改属主 / 属组。
cv fs blocks <PATH> [--format table|json]查看文件块位置信息。
cv fs free <PATH> [-r|--recursive]释放已同步到 UFS 的 Curvine 缓存空间。

常用示例:

cv fs ls /
cv fs ls / --cache-only
cv fs mkdir -p /data/a/b
cv fs put ./local.txt /data/remote.txt
cv fs get /data/remote.txt ./local.txt
cv fs cat /data/remote.txt
cv fs stat /data
cv fs count /data
cv fs mv /data/a /data/b
cv fs du -h /data
cv fs df -h
cv fs chmod 755 /data/script.sh
cv fs chown user:group /data
cv fs blocks /data/file.txt --format json
cv fs free /data --recursive

cv fs ls 额外支持类 HDFS 的选项:

选项说明
-C, --path-only仅输出路径。
-d, --directory将目录当作普通文件列出。
-H, --human-readable以人类可读方式显示大小。
-q, --hide-non-printable将不可打印字符显示为 ?。
-R, --recursive递归列目录。
-r, --reverse反向排序。
-t, --mtime按修改时间排序。
-S, --size按大小排序。
-u, --atime使用访问时间显示和排序。
-l, --long-format长列表格式。

chmod / chown 通过 --recursive 旗标递归,旗标可放在其它参数之前或之后。权限字符串支持八进制(如 755、0o755)和符号形式(如 u=rwx,g=rx,o=rx)。chown 支持 user:group、user: 和 :group。


4. mount:将 UFS 挂载到 Curvine

当前实现把 mount 同时用于三件事:

  • cv mount:列出全部挂载点
  • cv mount --check:列出挂载点并逐个校验 UFS 可达性
  • cv mount <UFS_PATH> <CV_PATH> [OPTIONS]:创建或更新挂载
  • cv mount resync <CV_PATH> [OPTIONS]:对 fs_mode 挂载执行元数据重同步

常用选项如下:

选项说明
--config <key=value>UFS 配置项,可重复传入多个键值对。
--update更新已存在的挂载配置。
--check-path-consist <true|false>是否检查 UFS_PATH 与 CV_PATH 的路径一致性,默认 true。
--read-verify-ufs读缓存时按 mtime / len 校验 UFS。
--ttl-ms <DURATION>TTL,默认 7d。支持 1h、7d 之类的时长格式。
--replicas <N>覆盖副本数。
--block-size <SIZE>覆盖块大小,例如 128MB。
-s, --storage-type <TYPE>覆盖存储类型。
--write-type <cache_mode|fs_mode>当前源码只区分这两种模式,默认 fs_mode。
--provider <auto|oss-hdfs|opendal>指定 UFS provider。
--check仅在列挂载点时生效,附带有效性检查。
--dry-runresync 时只扫描和打印差异,不执行删除 / 创建。
--verboseresync 时打印更详细的逐文件日志。

关于 --provider:同一种 URI scheme 可能映射到不同实现。例如 oss://... 既可能走 OSS-HDFS / JindoSDK,也可能走 OpenDAL,因此可以通过 --provider 强制指定实现。

取值说明常见协议
auto按 URI scheme 自动选择实现。所有已支持 scheme
oss-hdfs使用 JindoSDK / OSS-HDFS 语义。oss://
opendal使用 OpenDAL 后端。s3://、oss://、hdfs://、webhdfs://、cos://、gcs://、azblob:// 等

当前实现还有几个容易遗漏的行为:

  • 对 s3://... 路径,如果没有显式传 s3.bucket_name,CLI 会自动从 URI 提取并补全。
  • 对 hdfs://... 路径,如果没有显式传 hdfs.namenode / hdfs.root,CLI 会自动从 URI 推导。
  • 如果配置里出现 hdfs.kerberos.*,但既没有 hdfs.kerberos.ccache,环境里也没有 KRB5CCNAME,CLI 会打印 Kerberos ticket cache 警告。
  • validate_path_and_configs 当前只对 S3 路径做额外格式校验;其它 scheme 主要依赖后续 provider 初始化和连通性检查。

示例:

# 列出挂载点
cv mount

# 列出挂载点并检查 UFS 可达性
cv mount --check

# 创建 S3 挂载
cv mount s3://bucket/datasets /bucket/datasets \
  --config s3.endpoint_url=http://hostname.com \
  --config s3.region_name=cn \
  --config s3.credentials.access=access_key \
  --config s3.credentials.secret=secret_key \
  --config s3.path_style=true \
  --provider opendal

# 通过 JindoSDK / OSS-HDFS 创建 OSS 挂载
cv mount oss://my-bucket/prefix /oss-data --provider oss-hdfs \
  --config oss.endpoint=oss-cn-hangzhou.aliyuncs.com \
  --config oss.accessKeyId=xxx \
  --config oss.accessKeySecret=yyy

# 手动执行一次元数据 resync
cv mount resync /bucket/datasets --dry-run --verbose

各 UFS 类型(S3、OSS、HDFS、WebHDFS)的常见参数列表见文末 附录:UFS 挂载参数。

默认开启 --check-path-consist=true。因此像 s3://bucket/datasets 这样的 UFS 路径,通常需要挂载到 /bucket/datasets。如果确实需要不一致映射,请显式传 --check-path-consist=false。

当前源码里首次创建 fs_mode 挂载时会自动触发一次 resync。手动 cv mount resync ... 只适用于 fs_mode 挂载点。


5. umount:卸载挂载点

用法: cv umount <CURVINE_PATH>

示例:

cv umount /bucket/datasets

6. load:提交 Load 任务

用法: cv load [OPTIONS] <SOURCE_PATH> [TARGET_PATH]

选项 / 参数说明
<SOURCE_PATH>UFS 源 URI,或已有 mount 下的 Curvine 路径。
[TARGET_PATH]可选 Curvine 目标路径。已挂载源路径会自动推导目标。
-w, --watch提交后立即持续观察任务状态。
--no-overwrite目标已经存在时失败,不覆盖目标。

示例:

cv load /datasets/train/part-0001.parquet --watch
cv load s3://bucket/datasets/train/part-0001.parquet /datasets/train/part-0001.parquet --no-overwrite --watch

启用 Transfer 后,load 会提交 Transfer Job;否则使用旧 Master Job 路径。两种模式 下命令都会输出 Job ID 和目标路径。

Transfer 路由

启用独立 Transfer 后,命令行不变:

客户端配置cv load / cv export 路由
[transfer] enabled = false为兼容已有集群,调用旧 Master Load API。
[transfer] enabled = trueCLI 直接调用 Transfer 服务 RPC。

Transfer 服务和客户端都需要配置 Transfer。按客户端切换时无需修改 Master 和 Worker 配置;transfer.enabled = false 的客户端会继续调用旧 Master API。


7. export:将 Curvine 路径导出到 UFS

用法: cv export [OPTIONS] <PATH>

<PATH> 必须是一个挂载路径下的 Curvine 路径。Curvine 会根据挂载自动推导 UFS 目标路径。

选项 / 参数说明
<PATH>要导出的 Curvine 源路径。
-w, --watch提交后立即持续观察任务状态。
--no-overwriteUFS 目标已存在时失败。

示例:

cv export /bucket/datasets/train/part-0001.parquet --watch

8. load-status:查询加载任务状态

用法: cv load-status [OPTIONS] <JOB_ID>

选项 / 参数说明
<JOB_ID>加载任务 ID。
-v, --verbose详细输出。
-w, --watch <INTERVAL>轮询间隔,默认 5s。支持 1s、1m、1h 等格式。
--conf <PATH>可选的单次配置覆盖;日常使用不需要。

示例:

cv load-status <job_id>
cv load-status <job_id> -w 1s

当前实现里 load-status 默认就会进入轮询模式,默认刷新间隔为 5s;源码暂未暴露“只查询一次然后退出”的独立开关。


9. cancel-load:取消加载任务

用法: cv cancel-load [OPTIONS] <JOB_ID>

选项 / 参数说明
<JOB_ID>要取消的任务 ID。
--conf <PATH>可选的单次配置覆盖;日常使用不需要。

示例:

cv cancel-load <job_id>

10. load-list:列出最近的 load / export 任务

用法: cv load-list [OPTIONS]

参数说明
--path <PREFIX>匹配源或目标路径以该前缀开头的任务。
--mount <CV_PATH>匹配某个 Curvine 挂载点下的 fs_mode 任务。
--state <STATE>按状态过滤:pending、loading、completed、failed、canceled。
--running-only只显示 pending/loading 的任务。
--failed-only只看失败任务;配合 -v 时只打印失败的任务行。
--limit <N>返回的任务数上限(默认 50)。
--offset <N>分页偏移,按最近优先跳过 N 条(默认 0)。
-v, --verbose输出每个任务的任务级明细。
--include-finished <BOOL>是否包含已完成/失败/已取消的任务(默认 true)。
cv load-list --running-only
cv load-list --state failed --limit 20
cv load-list --mount /bucket/datasets --verbose

11. transfer:运维 Transfer 任务

cv transfer 仅在 [transfer] enabled = true 时可用。它用于列举、查看、重试和分页查询 Transfer 任务;日常提交仍使用 cv load 或 cv export。

该命令要求客户端配置可访问的 Transfer endpoint。服务部署见 Transfer 服务。

命令说明
cv transfer list列出任务。可使用 --kind load|export、--state、--tenant、--submitter 过滤。
cv transfer status <JOB_ID>查看单个任务。使用 --verbose 查看任务明细,或用 --watch --interval 1s 轮询。
cv transfer tasks <JOB_ID>查看单个任务的 task 分页。
cv transfer cancel <JOB_ID>取消一个 Transfer 任务。
cv transfer retry <JOB_ID>将失败、取消或部分成功任务重试为一个新任务。
cv transfer tenants按 tenant 汇总任务。

示例:

cv transfer list --kind load --state running
cv transfer status <job_id> --watch --interval 2s
cv transfer retry <job_id>

load-status 与 cancel-load 仍保留为兼容命令。启用 Transfer 时它们调用 Transfer;关闭时调用旧 Master 实现。


12. version:查看版本

用法: cv version

示例:

cv version

当前实现会输出 curvine-cli <version>,并带上 commit / branch 信息。

所有二进制还支持全局 --version-json 参数,以 JSON 形式输出完整结构化版本 (组件名、发布版本、git 来源、协议版本、能力):

cv --version-json
curvine-master --version-json
curvine-worker --version-json

详细说明请参阅版本管理与兼容性。

13. bench:内置基准测试

用法: cv bench [OPTIONS]、cv bench prefill [OPTIONS]

bench 可对 cv:// 路径(client 模式)或 file:// 路径(FUSE 模式)运行元数据与吞吐量测试套件。cv bench prefill 用于为混合负载预置可复用的工作集。常用参数包括 --path、--profile basic|deep、--mode auto|client|fuse、-p/--threads、--workload、--block-size、--big-file-size 和 --big-file-count。完整参数请运行 cv bench --help。

cv bench --path cv://default/bench --profile basic
cv bench prefill --path cv://default/bench/ws --files 100000 --file-size 0

14. fsck:块副本健康检查

用法: cv fsck <PATH> [OPTIONS]

参数说明
<PATH>要检查的文件或目录。
--detail对目录输出每个文件与块的详细信息。
--list-page-size <N>每次列目录 RPC 返回的条目数(默认 256,范围 1-4096)。

fsck 会将每个块记录的副本与当前可用副本进行对比,报告副本不足的块和读取错误。扫描发现问题时会输出告警行。

cv fsck /data
cv fsck /data/file.txt --detail

15. admin config:查看与覆盖 Master 运行时配置

用法: cv admin config <set|get|reset> ...

运行时覆盖只作用于正在运行的 Master,不需要改配置文件,而且不持久:Master 重启后会恢复为配置文件里的值。

命令说明
cv admin config get列出所有已注册的运行时配置键,以及它们的文件值、覆盖值和生效值。
cv admin config get <KEY>查看单个键。
cv admin config set <KEY> <VALUE>设置内存覆盖,并打印覆盖前与生效后的值。
cv admin config reset <KEY>清除覆盖,回落到配置文件中的值。
cv admin config get

当前版本中 Master 没有注册任何运行时可调整的键(build_master_runtime_registry 返回空注册表)。因此 cv admin config get 会输出 (no runtime config entries),set / reset 会返回 unsupported runtime configuration ...; writable: []。命令入口是为后续可注册的键预留的;现阶段需要修改参数请改配置文件并重启。


16. snapshot:创建 Master 元数据快照

用法: cv snapshot create [--force]

请求活跃 Master 立即创建元数据快照,并输出快照目录和 checkpoint 耗时。日志截断和 checkpoint 保留在后台异步完成。

  • 距上一次快照不足 journal.snapshot_min_interval 时请求会被拒绝;--force 仍然执行 checkpoint,执行期间元数据写入会暂停。
  • checkpoint 在 Master 上执行,无法取消。命名空间很大时,耗时可能超过 client.rpc_timeout_ms(默认 120s),即使快照成功,重试也会报告 a leader snapshot is already in progress。请先在 --conf 指定的配置文件中调大 client.rpc_timeout_ms。
cv snapshot create

17. completion:Shell 补全脚本

用法: cv completion <SHELL>

输出 bash、zsh、fish、powershell 或 elvish 的补全脚本。例如在当前 bash 会话中启用补全:

source <(cv completion bash)

兼容 CLI:dfs

发行包里的 bin/dfs 是一个兼容包装器:

  • 当第一个子命令是 fs 或 report 时,它会调用 Java io.curvine.CurvineShell。
  • dfs fs 保留 Hadoop FsShell 风格,因此子命令写法是 -ls、-mkdir、-rm -r 这种单短横线形式。
  • 其它子命令最终仍会转发到 Rust curvine-cli,但日常运维建议直接使用 cv。

示例:

bin/dfs fs -ls /
bin/dfs fs -mkdir -p /data
bin/dfs fs -rm -r /data/tmp
bin/dfs report
bin/dfs report info
bin/dfs report json
bin/dfs report capacity
bin/dfs report used
bin/dfs report available

其中 dfs report info 对应 Java 兼容入口的完整文本概览;语义上接近 cv report all,但命令名并不相同。

如果你需要 HDFS Shell 兼容语义或依赖 Hadoop 配置文件(如 core-site.xml / hdfs-site.xml),使用 dfs 更合适;如果你需要 Curvine 当前源码里的完整命令集,优先使用 cv。


POSIX / FUSE

Curvine 提供 FUSE 文件系统接口。挂载后(例如通过 bin/curvine-fuse.sh start),可以在挂载点直接使用标准 Linux 命令:

ls /curvine-fuse
cp data.txt /curvine-fuse/data.txt
du -sh /curvine-fuse
stat /curvine-fuse/data.txt

常见场景包括:

  • 基础文件操作:ls、cp、mv、rm、mkdir
  • 内容查看:cat、grep、sed
  • 文件系统信息:df -h、du -sh、stat
  • 权限相关:chmod、chown

如果你的目标是兼容现有 POSIX 工具链,优先走 FUSE;如果需要 Curvine 原生的挂载、加载、节点管理等能力,使用 cv。


附录:UFS 挂载参数

以下为 cv mount 时通过 --config key=value 传入的常见参数说明。必填 表示通常需要提供;可选 表示可以依赖默认值,或由 CLI 从挂载 URI 自动推导。

S3(s3://、s3a://)

通过 --provider opendal 或自动选择时使用。

参数必填/可选描述
s3.endpoint_url必填S3 服务地址,须以 http:// 或 https:// 开头。
s3.credentials.access必填Access Key ID。
s3.credentials.secret必填Secret Access Key。
s3.region_name可选区域名。
s3.path_style可选是否使用路径风格访问,常见于 MinIO 兼容端点。

OSS(oss://)

用于阿里云 OSS / OSS-HDFS 语义访问。

参数必填/可选描述
oss.endpoint必填OSS 端点地址。
oss.accessKeyId必填阿里云 AccessKey ID。
oss.accessKeySecret必填阿里云 AccessKey Secret。
oss.region可选区域。

HDFS(hdfs://)

参数必填/可选描述
hdfs.namenode可选NameNode 地址;不填时从挂载 URI 的 authority 推导。
hdfs.root可选根路径;不填时从挂载 URI 的 path 推导。
hdfs.user可选HDFS 用户名。
hdfs.atomic_write_dir可选是否启用原子写目录。
hdfs.kerberos.ccache可选Kerberos ticket cache 路径;也可由 KRB5CCNAME 提供。
hdfs.kerberos.krb5_conf可选krb5.conf 文件路径。
hdfs.kerberos.keytab可选keytab 文件路径。

WebHDFS(webhdfs://)

参数必填/可选描述
webhdfs.endpoint可选WebHDFS HTTP 服务地址;不填时从 URI 的 authority 推导。
webhdfs.root可选根路径。
webhdfs.delegation可选delegation token。