Ubuntu 22.04 安装 Apache TinkerPop 3.8.2 指南

Ubuntu 22.04 从零安装 Apache TinkerPop 3.8.2 实测指南：安装 OpenJDK 17、下载校验、Gremlin Server 部署、JVM 堆限制、systemd 自启、Console 远程查询与卸载。

Apache TinkerPopApache TinkerPop2026/10/12

Ubuntu 22.04 安装 Apache TinkerPop 3.8.2 指南

一、环境信息

本文所有命令与回显均在以下环境实测通过，读者可按相同版本对照操作。

项目值
操作系统Ubuntu 22.04.5 LTS（x86_64）
组件Apache TinkerPop Gremlin Server 3.8.2
配套客户端Gremlin Console 3.8.2
JDKOpenJDK 17（openjdk-17-jdk-headless）
安装路径/opt/gremlin-server（服务端）、/opt/gremlin-console（控制台）
服务端口8182（WebSocket，默认监听 127.0.0.1）
运行方式gremlin-server.sh 脚本或 systemd 托管
日志路径/opt/gremlin-server/logs/gremlin.log

操作系统版本确认命令与实测回显：

cat /etc/os-release | head -3

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"

二、前置条件

2.1 基础工具

解压与下载需要 unzip 与 curl，JDK 安装前建议先刷新软件源索引：

apt-get update

apt-get install -y unzip curl

2.2 安装 OpenJDK 17

TinkerPop 3.8.x 官方支持 Java 11 与 Java 17，本文采用长期支持版本 OpenJDK 17：

apt-get install -y openjdk-17-jdk-headless

安装完成后验证版本：

java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

Ubuntu 的 headless JDK 包自带 jps 工具（用于后续堆内存验证），无需额外安装。

2.3 网络与磁盘要求

  • 服务器需能直连 downloads.apache.org 下载发行包；
  • Gremlin Server 发行包约 37 MB，解压后约 300 MB；Gremlin Console 发行包约 566 MB（内置 Hadoop、Spark 扩展依赖），规划磁盘时按解压后大小估算；
  • 8182 端口未被占用：ss -lntp | grep 8182 应无输出。

三、版本选型说明

  • Apache 官方下载页当前提供 3.7.5、3.7.6、3.7.7、3.8.0、3.8.1、3.8.2 系列包，其中 3.8.2 为最新稳定版本，本文以其为准。
  • 自 3.7 起 Gremlin Server 与 Gremlin Console 分开发行，两个包需分别下载；服务端运行不依赖 Console，仅运维查询时需要。
  • 版本号与文件名一一对应，更换版本时只需替换下载链接中的版本号。
  • sha512 校验文件为"裸哈希"格式（仅一行哈希值、不含文件名），直接执行 sha512sum -c 会报 no properly formatted SHA512 checksum lines found，需按下文方式拼接文件名后校验。

四、部署步骤

以下步骤从零开始完成安装、配置、启动、验证全过程，命令均在 /opt 目录层级执行。

4.1 下载发行包并校验

进入临时目录，下载服务端与校验文件：

cd /tmp
curl -fsSL -O https://downloads.apache.org/tinkerpop/3.8.2/apache-tinkerpop-gremlin-server-3.8.2-bin.zip
curl -fsSL -O https://downloads.apache.org/tinkerpop/3.8.2/apache-tinkerpop-gremlin-server-3.8.2-bin.zip.sha512

拼接文件名后做 sha512 校验，实测回显：

echo "$(cat apache-tinkerpop-gremlin-server-3.8.2-bin.zip.sha512)  apache-tinkerpop-gremlin-server-3.8.2-bin.zip" | sha512sum -c -

apache-tinkerpop-gremlin-server-3.8.2-bin.zip: OK

4.2 解压到安装目录

unzip -q apache-tinkerpop-gremlin-server-3.8.2-bin.zip -d /opt/
mv /opt/apache-tinkerpop-gremlin-server-3.8.2 /opt/gremlin-server

确认目录结构：

ls /opt/gremlin-server

LICENSE  NOTICE  bin  conf  data  ext  lib  licenses  scripts

4.3 下载并部署 Gremlin Console（可选但推荐）

Console 用于远程连接服务端执行 Gremlin 查询，是日常运维的主要工具：

cd /tmp
curl -fsSL -O https://downloads.apache.org/tinkerpop/3.8.2/apache-tinkerpop-gremlin-console-3.8.2-bin.zip
echo "$(cat apache-tinkerpop-gremlin-console-3.8.2-bin.zip.sha512)  apache-tinkerpop-gremlin-console-3.8.2-bin.zip" | sha512sum -c -
unzip -q apache-tinkerpop-gremlin-console-3.8.2-bin.zip -d /opt/
mv /opt/apache-tinkerpop-gremlin-console-3.8.2 /opt/gremlin-console

注意：3.8.2 的 Console 启动脚本是 bin/gremlin.sh，没有名为 gremlin-console 的脚本文件。

4.4 限制 JVM 堆内存（256-512MB）

gremlin-server.sh 默认 JVM 参数为 -Xms512m -Xmx4096m，脚本约定：环境变量 JAVA_OPTIONS 非空时整体覆盖默认值。为控制内存占用，统一以 JAVA_OPTIONS 方式启动：

export JAVA_OPTIONS="-Xms256m -Xmx512m"

若需要持久化生效，可将该行写入 /etc/profile.d/gremlin-server.sh：

echo 'export JAVA_OPTIONS="-Xms256m -Xmx512m"' > /etc/profile.d/gremlin-server.sh

4.5 启动服务

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

实测回显：

Server started 4482.

确认运行状态：

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

Server running with PID 4482

如需前台运行观察实时日志（Ctrl+C 退出即停止服务）：

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

4.6 验证端口与进程

查看端口监听（默认配置 host: localhost，仅绑定回环地址）：

ss -lntp | grep 8182

LISTEN 0      4096   [::ffff:127.0.0.1]:8182            *:*    users:(("java",pid=4482,fd=86))

用 jps 确认堆参数已生效：

jps -v | grep GremlinServer

4482 GremlinServer -Dlogback.configurationFile=file:/opt/gremlin-server/conf/logback.xml -Xms256m -Xmx512m

查看服务启动日志：

tail -n 8 /opt/gremlin-server/logs/gremlin.log

实测回显（节选）：

[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 - Gremlin Server configured with worker thread pool of 1, gremlin pool of 12 and boss thread pool of 1.
[INFO] o.a.t.g.s.GremlinServer - Channel started at port 8182.

出现 Channel started at port 8182. 即启动成功。

4.7 Console 连接并执行查询

在另一终端进入 Console 目录启动交互环境：

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

启动横幅与插件加载回显：

         \,,,/
         (o o)
-----oOOo-(3)-oOOo-----
plugin activated: tinkerpop.server
plugin activated: tinkerpop.tinkergraph

连接服务端并执行查询，以下为完整实测回显：

gremlin> :remote connect tinkerpop.server conf/remote.yaml
==>Configured localhost/127.0.0.1:8182
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

验证完成后退出 Console：

gremlin> :q

4.8 配置 systemd 开机自启

创建服务单元文件 /etc/systemd/system/gremlin-server.service：

vi /etc/systemd/system/gremlin-server.service

内容如下（采用前台 console 模式交由 systemd 托管，便于标准化的启动停止管理）：

[Unit]
Description=Apache TinkerPop Gremlin Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/gremlin-server
Environment=JAVA_OPTIONS=-Xms256m -Xmx512m --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED
Environment=GREMLIN_YAML=/opt/gremlin-server/conf/gremlin-server.yaml
ExecStart=/opt/gremlin-server/bin/gremlin-server.sh console
Restart=on-failure
RestartSec=10
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

三个关键点：JAVA_OPTIONS 中必须包含 --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED（Java 17 模块系统限制所致，缺失会导致认证配置与图持久化功能失效，详见第七节）；SuccessExitStatus=143 使 systemctl stop 后状态为 inactive 而非 failed；自定义配置文件通过 GREMLIN_YAML 环境变量传入（start 子命令的路径参数不会生效）。

重载并启用：

systemctl daemon-reload

systemctl enable gremlin-server.service

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/gremlin-server.service → /etc/systemd/system/gremlin-server.service.

systemctl start gremlin-server.service

systemctl status gremlin-server.service --no-pager | head -6

实测回显：

● gremlin-server.service - Apache TinkerPop Gremlin Server
     Loaded: loaded (/etc/systemd/system/gremlin-server.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-12 06:55:30 UTC; 14s ago
   Main PID: 12022 (java)
      Tasks: 35 (limit: 5753)
     Memory: 294.9M

五、配置说明

默认配置文件为 /opt/gremlin-server/conf/gremlin-server.yaml，配套空图属性文件 conf/tinkergraph-empty.properties，开箱即可运行内存空图。常用调整项：

配置项位置说明
监听地址gremlin-server.yaml 的 host默认 localhost 仅本机可连，远程访问改为 0.0.0.0 或本机网卡 IP
监听端口gremlin-server.yaml 的 port默认 8182
图定义gremlin-server.yaml 的 graphs默认指向 conf/tinkergraph-empty.properties 内存空图
JVM 堆环境变量 JAVA_OPTIONS默认 -Xms512m -Xmx4096m，建议限制为 -Xms256m -Xmx512m
日志级别conf/logback.xml默认 INFO
认证gremlin-server.yaml 的 authentication默认关闭，开启方式见注意事项与配置详解文档

修改配置后重启服务生效：

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

Server stopped [4482]

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

六、注意事项

  1. Java 17 环境必须为 JVM 追加 --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED 参数。实测缺失该参数时：启用认证的服务端启动即退出（报 Could not create/configure Authenticator null）；持久化 TinkerGraph 在停止服务时写盘失败产生 0 字节 graph.kryo 文件导致数据丢失，再次启动时报 Could not load graph at data/graph.kryo with gryo 并退化为"端口在但查询引擎不可用"的半瘫状态。
  2. gremlin-server.sh start 后面跟的配置文件路径参数不会生效（脚本 start 分支不接收参数），后台方式加载自定义配置必须使用 GREMLIN_YAML 环境变量；前台 console 模式才支持位置参数。
  3. 默认 host: localhost 只绑定 127.0.0.1，跨机访问必须改 host。该默认 channelizer 为 WebSocket，对普通 HTTP 请求返回 400 Bad Request（Invalid WebSocket handshake method: POST），不能以 HTTP 探测判断服务存活，应使用 ss、nc 等端口级检测。
  4. 发行包自带 data/credentials.kryo 文件，其中预置 stephen、daniel、marko 三个样例账号（密码为 bcrypt 哈希），启用认证前必须重建该凭据文件，仅保留自建账号。
  5. SimpleAuthenticator 的密码必须存储为 bcrypt 哈希，存明文会在认证时报 Invalid salt version 拒绝登录。
  6. TinkerGraph 不支持事务（tx().commit() 抛 UnsupportedOperationException），配置 graphLocation 后数据在服务正常停止（close）时整体落盘，务必通过 stop 命令或 systemd 正常停机，禁止 kill -9。

七、常见问题

Q1：服务进程存在、端口在监听，但所有查询都报 gremlin-groovy is not an available GremlinScriptEngine？

这是典型的启动半瘫：日志中同时存在 Could not load graph at data/graph.kryo with gryo 与 InaccessibleObjectException（java.util.concurrent.atomic 包未被 open）。根因是 JVM 缺少 --add-opens 参数导致持久化图读取失败，图变量未注册进而脚本引擎初始化失败。处理：按 4.8 节在 JAVA_OPTIONS 中补齐 --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED，删除损坏的 0 字节 kryo 文件后重启。

Q2：jps 命令如何验证堆内存确实被限制？

jps -v | grep GremlinServer

回显中的 -Xms256m -Xmx512m 即当前生效的堆参数；若仍显示默认的 -Xmx4096m，说明启动时环境变量 JAVA_OPTIONS 未带上（systemd 方式需写在 unit 文件的 Environment= 行中）。

Q3：:remote connect 配置了用户名密码却报 Username and/or password are incorrect？

三步排查：确认服务端 yaml 已加 authentication 块且 credentialsDb 路径正确（注意相对路径以服务端工作目录 /opt/gremlin-server 为基准）；确认凭据图文件中只保留自建账号且 password 字段是 bcrypt 哈希而非明文；确认服务端 JVM 带有 --add-opens 参数（凭据图是持久化 TinkerGraph，读取时同样依赖该参数）。

Q4：如何让服务器重启后 Gremlin Server 自动拉起？

按 4.8 节配置 systemd 单元并执行 systemctl enable gremlin-server.service 即可，重启服务器后由 systemd 自动拉起，崩溃时按 on-failure 策略 10 秒后自动重启。

八、卸载方式

先停止服务并移除 systemd 单元：

systemctl stop gremlin-server.service
systemctl disable gremlin-server.service
rm -f /etc/systemd/system/gremlin-server.service
systemctl daemon-reload

删除程序目录与数据：

rm -rf /opt/gremlin-server
rm -rf /opt/gremlin-console

删除环境变量配置文件（如按 4.4 节创建过）：

rm -f /etc/profile.d/gremlin-server.sh

如需卸载 JDK：

apt-get remove -y openjdk-17-jdk-headless

九、参考链接