Apache TinkerPop 3.8.2 常用 CLI 命令与工具详解

一、环境信息

本文所有命令与回显均在以下环境实测采集。

项目	值
操作系统	Ubuntu 22.04.5 LTS / CentOS Linux 8（均已实测）
组件版本	Apache TinkerPop 3.8.2
服务端工具	/opt/gremlin-server/bin/gremlin-server.sh
交互客户端	/opt/gremlin-console/bin/gremlin.sh
JDK	OpenJDK 17
服务端口	8182

二、工具概览

TinkerPop 3.8.2 的命令行工具分两组：

工具	所在目录	作用
gremlin-server.sh	服务端包 bin 目录	管理服务端生命周期：启动、停止、重启、状态查询、前台运行、安装依赖
gremlin.sh	Console 包 bin 目录	Gremlin Console 交互环境：连接服务端、执行 Gremlin 语句、管理插件

两个注意点：一是 3.8.x 的 Console 启动脚本名为 gremlin.sh，不存在名为 gremlin-console 的脚本；二是 Server 与 Console 分开发行（下载页各有一个 zip），服务端只装 server 包也能运行，Console 供运维连接查询用。

三、前置条件

已按安装指南完成服务端部署（/opt/gremlin-server）与 Console 部署（/opt/gremlin-console）；
OpenJDK 17 已安装；
服务端已启动且 8182 端口在监听（/opt/gremlin-server/bin/gremlin-server.sh status 返回 running）。

四、工具详解

4.1 gremlin-server.sh 用法总览

不带参数执行可查看用法（实测回显）：

/opt/gremlin-server/bin/gremlin-server.sh usage

Configuration file not found.
Usage: /opt/gremlin-server/bin/gremlin-server.sh {start|stop|restart|status|console|install <group> <artifact> <version>|<conf file>}

    start        Start the server in the background using conf/gremlin-server.yaml as the
                 default configuration file
    stop         Stop the server
    restart      Stop and start the server
    status       Check if the server is running
    console      Start the server in the foreground using conf/gremlin-server.yaml as the
                 default configuration file
    install      Install dependencies

If using a custom YAML configuration file then specify it as the only argument for Gremlin
Server to run in the foreground or specify it via the GREMLIN_YAML environment variable.

帮助文本明确了规则：自定义配置文件要么在前台运行时作为唯一参数传入，要么通过 GREMLIN_YAML 环境变量指定（start 后台方式不支持位置参数，实测验证 start 分支会忽略路径参数）。

4.2 启动、状态与停止（start / status / stop）

使用默认堆限制启动（JAVA_OPTIONS 覆盖脚本默认的 -Xms512m -Xmx4096m）：

export JAVA_OPTIONS="-Xms256m -Xmx512m"
/opt/gremlin-server/bin/gremlin-server.sh start

实测回显：

Server started 4482.

查询状态：

/opt/gremlin-server/bin/gremlin-server.sh status

Server running with PID 4482

服务未运行时的状态回显为 Server not running。停止服务：

/opt/gremlin-server/bin/gremlin-server.sh stop

Server stopped [4482]

stop 流程为先发送 SIGTERM 等待进程退出，30 秒后仍未退出则再补发一次信号，因此持久化图能在停止时完整落盘，切勿使用 kill -9 直接杀进程。

加载自定义配置的后台启动方式：

export GREMLIN_YAML=/opt/gremlin-server/conf/gremlin-server-auth.yaml
/opt/gremlin-server/bin/gremlin-server.sh start

4.3 前台运行（console）

/opt/gremlin-server/bin/gremlin-server.sh console

前台模式实时输出启动日志到终端，关键回显：

[INFO] o.a.t.g.s.GremlinServer - Configuring Gremlin Server from /opt/gremlin-server/conf/gremlin-server.yaml
[INFO] o.a.t.g.s.u.ServerGremlinExecutor - A GraphTraversalSource is now bound to [g] with graphtraversalsource[tinkergraph[vertices:0 edges:0], standard]
[INFO] o.a.t.g.s.GremlinServer - Channel started at port 8182.

Ctrl+C 退出即停止服务。systemd 托管推荐使用该模式（ExecStart 指向 console 子命令）。

4.4 Gremlin Console 启动与退出

cd /opt/gremlin-console
bin/gremlin.sh

启动横幅与默认激活插件（实测回显）：

         \,,,/
         (o o)
-----oOOo-(3)-oOOo-----
plugin activated: tinkerpop.server
plugin activated: tinkerpop.gephi
plugin activated: tinkerpop.utilities
plugin activated: tinkerpop.credentials
plugin activated: tinkerpop.tinkergraph
plugin activated: tinkerpop.sparql
plugin activated: tinkerpop.spark
plugin activated: tinkerpop.hadoop
gremlin>

退出命令为 :q 或 :x（:exit 的别名）：

gremlin> :q

4.5 远程连接与脚本提交（:remote 系列）

建立远程连接（默认 remote.yaml 指向 localhost:8182 并以文本形式回显结果）：

gremlin> :remote connect tinkerpop.server conf/remote.yaml
==>Configured localhost/127.0.0.1:8182

用 :> 把 Gremlin 语句提交到服务端执行，以下为完整实测回显：

gremlin> :> g.V().count()
==>0
gremlin> :> g.addV("person").property("name","admin").next()
==>v[0]
gremlin> :> g.V().valueMap().toList()
==>{name=[admin]}
gremlin> :> g.V().count()
==>1

查看当前连接（星号标记当前使用的远程）：

gremlin> :remote list
==>*0 - Gremlin Server - [localhost/127.0.0.1:8182]

关闭连接：

gremlin> :remote close
==>Removed - Gremlin Server - [localhost/127.0.0.1:8182]

关闭后 :remote list 无输出条目。带认证的连接只需把 remote.yaml 换成携带 username 与 password 的配置文件（如自建的 conf/remote-admin.yaml，内容含 username: admin、password: q1w2e3r4），:> 提交时若凭据错误会得到：

gremlin> :> g.V().count()
Username and/or password are incorrect

4.6 插件管理（:plugin）

列出全部插件（实测回显，方括号为激活状态）：

gremlin> :plugin list
==>tinkerpop.server[active]
==>tinkerpop.gephi[active]
==>tinkerpop.utilities[active]
==>tinkerpop.sugar
==>tinkerpop.credentials[active]
==>tinkerpop.hadoop[active]
==>tinkerpop.spark[active]
==>tinkerpop.tinkergraph[active]
==>tinkerpop.sparql[active]

激活未启用的插件：

gremlin> :plugin use tinkerpop.sugar
==>tinkerpop.sugar activated

4.7 帮助与内置命令速查（:help）

gremlin> :help

实测输出（全部内置命令）：

Available commands:
  :help       (:h  ) Display this help message
  ?           (:?  ) Alias to: :help
  :exit       (:x  ) Exit the shell
  :quit       (:q  ) Alias to: :exit
  import      (:i  ) Import a class into the namespace
  :display    (:d  ) Display the current buffer
  :clear      (:c  ) Clear the buffer and reset the prompt counter
  :show       (:S  ) Show variables, classes or imports
  :inspect    (:n  ) Inspect a variable or the last result with the GUI object browser
  :purge      (:p  ) Purge variables, classes, imports or preferences
  :edit       (:e  ) Edit the current buffer
  :load       (:l  ) Load a file or URL into the buffer
  .           (:.  ) Alias to: :load
  :save       (:s  ) Save the current buffer to a file
  :record     (:r  ) Record the current session to a file
  :history    (:H  ) Display, manage and recall edit-line history
  :alias      (:a  ) Create an alias
  :grab       (:g  ) Add a dependency to the shell environment
  :register   (:rc ) Register a new command with the shell
  :doc        (:D  ) Open a browser window displaying the doc for the argument
  :set        (:=  ) Set (or list) preferences
  :uninstall  (:-  ) Uninstall a Maven library and its dependencies from the Gremlin Console
  :install    (:+  ) Install a Maven library and its dependencies into the Gremlin Console
  :plugin     (:pin) Manage plugins for the Console
  :remote     (:rem) Define a remote connection
  :submit     (:>  ) Send a Gremlin script to Gremlin Server
  :bytecode   (:bc ) Gremlin bytecode helper commands
  :cls        (:C  ) Clear the screen.

高频组合建议记住：:h 求助、:q 退出、:rem 远程、:> 提交、:pin 插件、:c 清缓冲、:H 历史。

4.8 类导入与本地求值

导入类后可直接本地求值（不经过服务端）：

gremlin> import java.lang.Math
==>java.lang.Math
gremlin> Math.abs(-8)
==>8

注意：老版本文档常见的 :class 命令在 3.8.2 中已不存在，实测输入 :class java.lang.Math 后语句进入 Groovy 缓冲区（提示符变为多点续行形态，形如 6 个点接数字与大于号）且永不求值，此时可用 :c 清空缓冲恢复。

五、注意事项

gremlin-server.sh start 的位置参数会被忽略，后台方式加载自定义配置必须用 GREMLIN_YAML 环境变量，前台 console 方式才可传配置文件路径。
Console 与服务端版本建议严格一致（同为 3.8.2），跨大版本连接可能因序列化格式差异失败。
Console 的 JVM 工作目录会被启动脚本切换到 Console 安装目录，conf/remote.yaml 等相对路径以此为基准；引用服务端目录下的文件时写绝对路径。
以管道方式给 gremlin.sh 喂命令时，紧贴 :q 的最后一条语句输出会被吞掉，批量执行验证脚本时在末尾追加一条无关语句（如 1+1）再 :q。
groovysh 环境不支持"全限定类名直接赋值"（报 No such property: org），先 import 再用短类名。
服务端对普通 HTTP 请求返回 400（Invalid WebSocket handshake method: POST），判断服务是否存活应使用 ss、nc 或 :remote connect 实测。
带认证连接时凭据文件中的 password 为明文口令（客户端侧传输经 SASL 协商），注意该文件的属主与读写权限收敛。

六、常见问题

Q1：:remote connect 成功但 :> 提交报 Username and/or password are incorrect？

服务端启用了认证而客户端凭据不对。核对 remote 连接文件中的 username 与 password；password 在服务端凭据图中必须以 bcrypt 哈希存储；同时确认服务端 JVM 带 --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED（凭据图读取依赖该参数）。

Q2：gremlin.sh 启动后输入任何语句都没有 ==> 结果输出？

先确认是否处于续行缓冲状态（提示符为多点续行形态而非 gremlin> ），用 :c 清空缓冲；再确认语句是否以 :> 提交（不带 :> 的语句在本地求值，本地没有 g 变量时会报错）；最后确认连接未被 :remote close 关闭。

Q3：restart 子命令会保留自定义配置吗？

restart 等价于先 stop 后 start，环境变量 GREMLIN_YAML 与 JAVA_OPTIONS 在 shell 会话中仍然有效时会继承；通过 systemd 管理时直接用 systemctl restart gremlin-server.service 更可靠。

Q4：如何查看 Console 当前已导入的类与变量？

用 :S 命令：:S imports 查看导入，:S vars 查看变量（:show 的别名 :S，用法见 4.7 节帮助表）。

七、参考链接

TinkerPop 官方参考文档（Console 章节）：https://tinkerpop.apache.org/docs/3.8.2/reference/#gremlin-console
Gremlin Server 管理文档：https://tinkerpop.apache.org/docs/3.8.2/reference/#gremlin-server
Gremlin 查询语言入门：https://tinkerpop.apache.org/docs/3.8.2/tutorials/getting-started/
官方下载页：https://downloads.apache.org/tinkerpop/3.8.2/