Tools 快速上手
1 HugeGraph-Tools概述
HugeGraph-Tools 提供图与任务管理、备份和恢复命令，也保留旧版 Server/Studio 的部署命令。
测试指南：如需在本地运行 Tools 测试，请参考 工具链本地测试指南
2 获取 HugeGraph-Tools
HugeGraph-Tools 包含在 Toolchain 发布包中，可以下载发布包，也可以从源码编译。
- 下载二进制tar包
- 下载源码编译安装
2.1 下载二进制tar包
以下以已发布的 HugeGraph-Toolchain 1.7.0 为例。其他发布版本见下载页。
2.2 下载源码编译安装
任选一种方式构建发布版 1.7.0 Tools，开始前先安装 Maven 和 JDK 11。源码包方式还需要 wget。
两段命令均包含编译和进入生成目录，最后用 bin/hugegraph help 查看可用命令。
编译还会在源码根目录下生成 hugegraph-tools/target/apache-hugegraph-tools-incubating-1.7.0.tar.gz。
2.3 构建当前源码
若需要使用 master 分支未发布的新特性，可按以下步骤从源码构建 Tools（当前 master 以 1.8 为基线，需 JDK 17、Maven 3.6.3+ 与 Python 3.9+）：
获取 Toolchain 源码
构建配套 Server SDK
执行以下脚本下载 Server 源码并将配套 SDK 安装到独立 Maven 仓库：
详细说明见 Java 17 迁移指引。
打包 Tools
使用这份源码构建时保留 SDK 仓库。master 分支生成目录名不含 incubating。
3 使用
3.1 功能概览
进入解压或编译生成的 Tools 目录，用 bin/hugegraph help 查看命令列表，
用 bin/hugegraph help <子命令> 查看单个命令的用法。可用命令分为以下几类。
- 图管理类，graph-mode-set、graph-mode-get、graph-list、graph-get、graph-clear、graph-create、graph-clone 和 graph-drop
- 异步任务管理类，task-list、task-get、task-delete、task-cancel 和 task-clear
- Gremlin类，gremlin-execute 和 gremlin-schedule
- 备份/恢复类，backup、restore、migrate、schedule-backup 和 dump
- 认证数据备份/恢复类，auth-backup 和 auth-restore
- 旧版 Server/Studio 部署，deploy、clear、start-all 和 stop-all
3.2 [options]-全局变量
以下全局选项可以通过命令行或环境变量设置。
--graph指定要操作的图，默认为hugegraph。--url指定 Server 地址，默认为http://127.0.0.1:8080。--user在 Server 启用认证时提供用户名。--password提供该用户的密码。--timeout设置连接超时时间，默认为 30 秒。--trust-store-file指定 HTTPS truststore，留空时使用内置的conf/hugegraph.truststore。--trust-store-password提供其密码，留空时使用内置 truststore 的密码。--throw-mode默认为false，出错时打印错误并退出。设为true时抛出异常，主要用于测试。
--url的 scheme 决定连接协议。使用https://...连接 HTTPS 时，才可设置 truststore 选项。--user和--password必须同时提供或同时省略。
使用 export 设置的环境变量对当前终端及其启动的命令生效。
| 全局变量 | 环境变量 | 示例 |
|---|---|---|
| –url | HUGEGRAPH_URL | export HUGEGRAPH_URL=http://127.0.0.1:8080 |
| –graph | HUGEGRAPH_GRAPH | export HUGEGRAPH_GRAPH=hugegraph |
| –user | HUGEGRAPH_USERNAME | export HUGEGRAPH_USERNAME=admin |
| –password | HUGEGRAPH_PASSWORD | export HUGEGRAPH_PASSWORD=test |
| –timeout | HUGEGRAPH_TIMEOUT | export HUGEGRAPH_TIMEOUT=30 |
| –trust-store-file | HUGEGRAPH_TRUST_STORE_FILE | export HUGEGRAPH_TRUST_STORE_FILE=/tmp/trust-store |
| –trust-store-password | HUGEGRAPH_TRUST_STORE_PASSWORD | export HUGEGRAPH_TRUST_STORE_PASSWORD=xxxx |
下面两种写法查询同一个图的顶点总数，可按使用习惯任选一种。示例使用未启用鉴权的本地 Server；已启用鉴权时还需提供上述用户名和密码。
也可以在 bin/hugegraph 脚本中设置这些变量。
bin/hugegraph 还会读取 JAVA_HOME（未设置时打印警告，https 需要它）和 JAVA_OPTIONS（JVM 参数，为空时脚本使用 -Xms512m，并根据机器空闲内存计算 -Xmx）。
3.3 图管理类，graph-mode-set、graph-mode-get、graph-list、graph-get、graph-clear、graph-create、graph-clone和graph-drop
- graph-mode-set，设置图的 restore mode
- –graph-mode 或者 -m，必填项，指定将要设置的模式，合法值包括 [NONE, RESTORING, MERGING, LOADING]
- graph-mode-get，获取图的 restore mode
- graph-list，列出某个 HugeGraph-Server 中全部的图
- graph-get，获取某个图及其存储后端类型
- graph-clear，清除某个图的全部 schema 和 data
- –confirm-message 或者 -c，必填项，删除确认信息，需要手动输入，二次确认防止误删，“I’m sure to delete all data”，包括双引号
- graph-create，使用配置文件创建新图
- –name 或者 -n，选填项，新图的名称，默认为 g
- –file 或者 -f，图配置文件的路径，文件内容会作为新图的配置发送给 HugeGraph-Server
- graph-clone，克隆已存在的图
- –name 或者 -n，选填项，新克隆图的名称，默认为 g
- –clone-graph-name，选填项，要克隆的源图名称，默认为 hugegraph
- graph-drop，删除图（不同于 graph-clear，这会完全删除图）
- –confirm-message 或者 -c，必填项，确认消息 “I’m sure to drop the graph”，包括双引号
graph-create、graph-clone、graph-clear 和 graph-drop 会将 –timeout 提升到至少 300 秒。
当需要把备份的图原样恢复到一个新的图中的时候，需要先将图模式设置为 RESTORING 模式；当需要将备份的图合并到已存在的图中时，需要先将图模式设置为 MERGING 模式。
3.4 异步任务管理类，task-list、task-get、task-delete、task-cancel 和 task-clear
- task-list，列出某个图中的异步任务，可以根据任务的状态过滤
- –status，选填项，指定要查看的任务的状态，即按状态过滤任务，合法值包括 [UNKNOWN, NEW, QUEUED, RESTORING, RUNNING, SUCCESS, CANCELLED, FAILED]（不区分大小写）
- –limit，选填项，指定要获取的任务的数目，默认为 -1，意思为获取全部符合条件的任务，显式传入的值必须为正数
- task-get，获取某个异步任务的详细信息
- –task-id，必填项，指定异步任务的 ID
- task-delete，删除某个异步任务的信息
- –task-id，必填项，指定异步任务的 ID
- task-cancel，取消某个异步任务的执行
- –task-id，必填项，要取消的异步任务的 ID
- task-clear，清理完成的异步任务
- –force，选填项，设置时，表示清理全部异步任务，未执行完成的先取消，然后清除所有异步任务。默认只清理已完成的异步任务
3.5 Gremlin类，gremlin-execute和gremlin-schedule
- gremlin-execute，发送 Gremlin 语句到 HugeGraph-Server 来执行查询或修改操作，同步执行，结束后返回结果
- –file 或者 -f，指定要执行的脚本文件，UTF-8编码，与 –script 互斥
- –script 或者 -s，指定要执行的脚本字符串，与 –file 互斥
- –aliases 或者 -a，Gremlin 别名设置，格式为：key1=value1,key2=value2,…
- –bindings 或者 -b，Gremlin 绑定设置，格式为：key1=value1,key2=value2,…
- –language 或者 -l，Gremlin 脚本的语言，默认为 gremlin-groovy
–file 和 –script 二者互斥，必须设置其中之一
- gremlin-schedule，发送 Gremlin 语句到 HugeGraph-Server 来执行查询或修改操作，异步执行，任务提交后立刻返回异步任务id
- –file 或者 -f，指定要执行的脚本文件，UTF-8编码，与 –script 互斥
- –script 或者 -s，指定要执行的脚本字符串，与 –file 互斥
- –bindings 或者 -b，Gremlin 绑定设置，格式为：key1=value1,key2=value2,…
- –language 或者 -l，Gremlin 脚本的语言，默认为 gremlin-groovy
–file 和 –script 二者互斥，必须设置其中之一
3.6 备份/恢复类
- backup，将某张图中的 schema 或者 data 备份到 HugeGraph 系统之外，以 JSON 形式存在本地磁盘或者 HDFS
- –format，备份的格式，可选值包括 [json, text]，默认为 json
- –all-properties，是否备份顶点/边全部的属性，仅在 –format 为 text 是有效，默认 false
- –label，要备份的顶点 label 或者边 label，仅在 –format 为 text 时生效；设置该项时，–huge-types 必须只包含一种类型，且该类型必须是 vertex 或者 edge，否则命令会失败
- –properties，要备份的顶点/边的属性，逗号分隔，仅在 –format 为 text 是有效，只有备份顶点或者边的时候有效
- –compress，备份时是否压缩数据，默认为 true
- –directory 或者 -d，存储 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
- –huge-types 或者 -t，要备份的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，‘all’ 代表全部6种类型，即顶点、边和所有schema，‘schema’ 代表 4 种 schema 类型 [vertex_label, edge_label, property_key, index_label]
- –log 或者 -l，指定日志目录，默认为 ./logs
- –retry，指定失败重试次数，默认为 3
- –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
- –split-size 或者 -s，指定在备份时对顶点或者边分块的大小，默认为 1048576，且不能小于 1048576（1M）
- -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
当 –timeout 小于 120 秒时，backup（以及 migrate 中的备份步骤）会使用 120 秒
- restore，将 JSON 格式存储的 schema 或者 data 恢复到一个新图中（RESTORING 模式）或者合并到已存在的图中（MERGING 模式）
- –directory 或者 -d，存储 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
- –clean，是否在恢复图完成后删除 –directory 指定的目录，默认为 false
- –huge-types 或者 -t，要恢复的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，‘all’ 代表全部6种类型，即顶点、边和所有schema，‘schema’ 代表 4 种 schema 类型 [vertex_label, edge_label, property_key, index_label]
- –log 或者 -l，指定日志目录，默认为 ./logs
- –retry，指定失败重试次数，默认为 3
- –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
- -D，用 -Dkey=value 的模式指定动态参数，用来从 HDFS 恢复图时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
只有当 –format 为 json 执行 backup 时，才可以使用 restore 命令恢复 restore 要求图处于 RESTORING 或 MERGING 模式（先用 graph-mode-set 设置），否则命令会失败
- migrate，将当前连接的图迁移至另一个 HugeGraphServer 中
- –target-graph，目标图的名字，默认为 hugegraph
- –target-url，目标图所在的 HugeGraphServer，默认为 http://127.0.0.1:8081
- –target-user，访问目标图的用户名
- –target-password，访问目标图的密码
- –target-timeout，访问目标图的超时时间
- –target-trust-store-file，访问目标图使用的 truststore 文件
- –target-trust-store-password，访问目标图使用的 truststore 的密码
- –directory 或者 -d，迁移过程中，存储源图的 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
- –huge-types 或者 -t，要迁移的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，‘all’ 代表全部6种类型，即顶点、边和所有schema，‘schema’ 代表 4 种 schema 类型 [vertex_label, edge_label, property_key, index_label]
- –log 或者 -l，指定日志目录，默认为 ./logs
- –retry，指定失败重试次数，默认为 3
- –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
- –split-size 或者 -s，指定迁移过程中对源图进行备份时顶点或者边分块的大小，默认为 1048576，且不能小于 1048576（1M）
- -D，用 -Dkey=value 的模式指定动态参数，用来在迁移图过程中需要备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
- –graph-mode 或者 -m，将源图恢复到目标图时将目标图设置的模式，合法值包括 [RESTORING, MERGING]，默认为 RESTORING。迁移期间目标图会被切换到该模式，迁移结束后恢复为原来的模式
- –keep-local-data，是否保留在迁移图的过程中产生的源图的备份，默认为 false，即默认迁移图结束后不保留产生的源图备份
- schedule-backup，周期性对图执行备份操作，并保留一定数目的最新备份（目前仅支持本地文件系统）
- –directory 或者 -d，必填项，指定备份数据的目录
- –backup-num，选填项，指定保存的最新的备份的数目，默认为 3
- –interval，选填项，指定进行备份的周期，格式同 Linux crontab 格式，默认为 “0 0 * * *"（每天 00:00）
schedule-backup 会添加一条 crontab 任务，定期执行
backup -t all并写入{directory}/{graph}/hugegraph-backup-{yyMMddHHmm}/，只保留最新的 –backup-num 份备份。相对路径的 –directory 会相对于 hugegraph-tools 的根目录解析，且{directory}/{graph}必须尚不存在 - dump，把整张图的顶点和边全部导出，默认以
vertex vertex-edge1 vertex-edge2...的 JSON 格式存储。 用户也可以自定义存储格式。在hugegraph-tools/src/main/java/org/apache/hugegraph/formatter下实现一个继承自Formatter的类，例如CustomFormatter，使用时指定该类为 formatter：bin/hugegraph dump -f CustomFormatter- –formatter 或者 -f，指定使用的 formatter，默认为 JsonFormatter
- –directory 或者 -d，存储 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
- –log 或者 -l，指定日志目录，默认为 ./logs
- –retry，指定失败重试次数，默认为 3
- –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
- –split-size 或者 -s，指定在备份时对顶点或者边分块的大小，默认为 1048576，且不能小于 1048576（1M）
- -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
3.7 认证数据备份/恢复类
- auth-backup，备份认证数据到指定目录
- –types 或者 -t，要备份的认证数据类型，逗号分隔，可选值为 ‘all’ 或者一个或多个 [user, group, target, belong, access] 的组合，‘all’ 代表全部5种类型；包含 ‘belong’ 时必须同时包含 ‘user’ 和 ‘group’，包含 ‘access’ 时必须同时包含 ‘group’ 和 ’target’
- –directory，备份数据存储目录，本地目录时，默认为 ‘./auth-backup-restore’，HDFS 时，默认为 ‘{fs.default.name}/auth-backup-restore’（该选项没有 -d 短写）
- –retry，指定失败重试次数，默认为 3
- -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
- auth-restore，从指定目录恢复认证数据
- –types 或者 -t，要恢复的认证数据类型，逗号分隔，可选值为 ‘all’ 或者一个或多个 [user, group, target, belong, access] 的组合，‘all’ 代表全部5种类型；包含 ‘belong’ 时必须同时包含 ‘user’ 和 ‘group’，包含 ‘access’ 时必须同时包含 ‘group’ 和 ’target’
- –directory，备份数据存储目录，本地目录时，默认为 ‘./auth-backup-restore’，HDFS 时，默认为 ‘{fs.default.name}/auth-backup-restore’（该选项没有 -d 短写）
- –retry，指定失败重试次数，默认为 3
- –strategy，冲突处理策略，可选值为 [stop, ignore]，默认为 stop。stop 表示遇到冲突时停止恢复，ignore 表示忽略冲突继续恢复
- –init-password，恢复用户时设置的初始密码，当 –types 包含 user 时必填
- -D，用 -Dkey=value 的模式指定动态参数，用来从 HDFS 恢复数据时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
3.8 安装部署类
注意：此处的安装部署命令仅适用于早期历史版本（Server 0.6.10.10.4 与 Studio 0.6.10.10.0），不支持当前版本的 HugeGraph Server 或 Hubble。
新部署请参考 Server 快速上手 与 Hubble 快速上手，
以下说明仅供维护旧环境参考。
- deploy，一键下载、安装和启动 HugeGraph-Server 和 HugeGraph-Studio
- -v，必填项，指定要安装的 HugeGraph-Server 和 HugeGraph-Studio 版本，必须是 bin/version-map.yaml 中列出的版本之一（0.6、0.7、0.8、0.9、0.10），脚本据此映射到对应的 server 和 studio 发布版本
- -p，必填项，指定安装的 HugeGraph-Server 和 HugeGraph-Studio 目录
- -u，选填项，指定下载 HugeGraph-Server 和 HugeGraph-Studio 压缩包的链接
- clear，清理 HugeGraph-Server 和 HugeGraph-Studio 目录和tar包（若对应的 server 或 studio 进程仍在运行则拒绝执行，删除每一项前都会提示确认）
- -p，必填项，指定要清理的 HugeGraph-Server 和 HugeGraph-Studio 的目录
- start-all，一键启动 HugeGraph-Server 和 HugeGraph-Studio
- -v，必填项，指定已安装的 HugeGraph-Server 和 HugeGraph-Studio 版本，取值同 deploy
- -p，必填项，指定安装了 HugeGraph-Server 和 HugeGraph-Studio 的目录
- stop-all，一键关闭 HugeGraph-Server 和 HugeGraph-Studio
deploy、start-all、clear 和 stop-all 由
bin/hugegraph直接转交给bin/deploy.sh、bin/start-all.sh、bin/clear.sh和bin/stop-all.sh执行，因此 3.2 中的全局变量和环境变量对它们不生效。
deploy命令中有可选参数 -u，提供时会使用指定的下载地址替代默认下载地址下载 tar 包，并且将地址写入
~/hugegraph-download-url-prefix文件中；之后如果不指定地址时，会优先从~/hugegraph-download-url-prefix指定的地址下载 tar 包；如果 -u 和~/hugegraph-download-url-prefix都没有时，会从默认下载地址https://github.com/hugegraph进行下载
3.9 具体命令参数
各子命令的具体参数如下：