CentOS 8 安装 Apache TinkerPop 3.8.2 指南

一、环境信息

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

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

cat /etc/os-release | head -2

NAME="CentOS Linux"
VERSION="8"

二、前置条件

2.1 基础工具

刷新软件源缓存并安装解压、下载工具：

dnf makecache

dnf install -y unzip curl

2.2 安装 OpenJDK 17

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

dnf install -y java-17-openjdk-headless

安装完成后验证版本：

java -version

实测回显：

openjdk version "17.0.1" 2021-10-19 LTS
OpenJDK Runtime Environment 21.9 (build 17.0.1+12-LTS)
OpenJDK 64-Bit Server VM 21.9 (build 17.0.1+12-LTS, mixed mode, sharing)

CentOS 8 的 headless JDK 包不包含 jps 工具，后续验证堆内存需要开发包：

dnf install -y java-17-openjdk-devel

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，需按下文方式拼接文件名后校验。

四、部署步骤

以下步骤从零开始完成安装、配置、启动、验证全过程。

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
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 598.

确认运行状态：

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

Server running with PID 598

如需前台运行观察实时日志（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=598,fd=86))

用 jps 确认堆参数已生效（CentOS 需已安装 java-17-openjdk-devel）：

jps -v | grep GremlinServer

598 GremlinServer -Dlogback.configurationFile=file:/opt/gremlin-server/conf/logback.xml -Xms256m -Xmx512m --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED

查看服务启动日志：

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 - Channel started at port 8182.

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

4.7 Console 连接并执行查询

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

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

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

gremlin> :remote connect tinkerpop.server conf/remote.yaml
==>Configured localhost/127.0.0.1:8182
gremlin> :> g.addV("person").property("name","marko").property("age",29).next()
==>v[0]
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

systemctl start gremlin-server.service

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

实测回显：

● 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)

4.9 防火墙放行

若服务器启用了 firewalld，需放行 8182 端口供远程客户端访问：

firewall-cmd --permanent --add-port=8182/tcp
firewall-cmd --reload

五、配置说明

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

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

/opt/gremlin-server/bin/gremlin-server.sh stop
/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。
7. CentOS 8 的 headless JDK 不含 jps，验证堆内存前先安装 java-17-openjdk-devel。

七、常见问题

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 命令不存在或如何验证堆内存确实被限制？

CentOS 8 需先安装开发包：dnf install -y java-17-openjdk-devel，然后：

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：远程服务器连接不上 8182 端口？

依次确认三点：服务端 yaml 的 host 是否已从 localhost 改为本机网卡 IP 或 0.0.0.0（默认只绑定回环地址）；firewalld 是否已放行 8182/tcp；云服务器还需检查安全组规则是否放行该端口。

八、卸载方式

先停止服务并移除 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：

dnf remove -y java-17-openjdk-headless java-17-openjdk-devel

九、参考链接

• Apache TinkerPop 官方下载：https://downloads.apache.org/tinkerpop/3.8.2/
• TinkerPop 官方参考文档：https://tinkerpop.apache.org/docs/3.8.2/reference/
• Gremlin Server 官方文档章节：https://tinkerpop.apache.org/docs/3.8.2/reference/#gremlin-server
• TinkerPop 项目主页：https://tinkerpop.apache.org/