Apache HugeGraph Docker Compose 部署指南

使用 Docker Compose 单命令编排部署 Apache HugeGraph 1.7.0 分布式图数据库，覆盖镜像选型、compose 文件、后端存储持久化、环境变量、端口与常用运维命令，帮助在干净环境独立从零启动 HugeGraphServer（REST 8080 / Gremlin 8182）。

Apache HugeGraphApache HugeGraph数据库容器化部署ApacheDocker Compose图数据库2026/10/11

Apache HugeGraph Docker Compose 部署指南

目标：使用 Docker Compose 在单台主机上编排部署 Apache HugeGraph 1.7.0（分布式图数据库，兼容 Apache TinkerPop3 与 Gremlin），通过一个 docker-compose.yml 完成 image 声明、后端数据卷持久化、端口映射与环境变量注入，最终 docker compose up -d 一键启动，REST 8080 / Gremlin 8182 即可访问。本文以官方镜像编排流程为准。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • 编排工具：Docker Engine 24+ 与 Docker Compose v2（docker compose 子命令）
  • 组件版本：Apache HugeGraph 1.7.0（REST Server + Gremlin Server）
  • 镜像：hugegraph/hugegraph-server（HugeGraph 官方 Server 镜像）
  • 默认端口：8080（REST/Apis）、8182（Gremlin WebSocket）
  • 默认后端：RocksDB（backend=rocksdb）
  • 服务内部数据目录：/hugegraph-server/data（见数据卷设计）
  • 示例管理账号：admin（认证启用后生效）

二、镜像选型说明

镜像说明建议
hugegraph/hugegraph-serverHugeGraph 官方 Server 镜像，内含 REST/Gremlin 服务层，默认 RocksDB 后端推荐，本文采用
apache/incubator-hugegraphApache 社区通用 all-in-one 镜像（老版本命名）老版本可用，新部署建议上面者
自建镜像基于官方发行包 + JDK 17 自行构建需要强定制时选用

💡 说明：HugeGraph 1.7.0 采用 PD + Store + Server 分层架构，官方 Server 镜像默认以内嵌 RocksDB 提供 store，单进程即可完整启动，适合用 Compose 快速起一个可用实例；如需多节点/集群（独立 PD、Store），需额外编排 hugegraph-store、PD 相关服务，超出单机部署范围。

三、前置条件

  • 已安装 Docker Engine 24+ 与 Docker Compose v2，docker compose version 可用
  • 主机可访问 Docker Hub（拉取 hugegraph/hugegraph-server 镜像）
  • 主机预留充足磁盘给数据卷（默认 RocksDB 数据落盘）
  • docker compose ps 能正常返回（守护进程运行中）

四、部署步骤

4.1 创建部署目录与 compose 文件

mkdir -p /opt/hugegraph/compose && cd /opt/hugegraph/compose

创建 docker-compose.yml，内容如下：

services:
  hugegraph-server:
    image: hugegraph/hugegraph-server
    container_name: hugegraph-server
    restart: unless-stopped
    ports:
      - "8080:8080"
      - "8182:8182"
    environment:
      - JAVA_OPTIONS=-Xms256m -Xmx512m
    volumes:
      - hg_data:/hugegraph-server/data
      - ./conf/graphs:/hugegraph-server/conf/graphs:ro
    healthcheck:
      test: ["CMD", "curl", "-fs", "http://127.0.0.1:8080/graphs"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  hg_data:

💡 说明：JAVA_OPTIONS=-Xms256m -Xmx512m 将 JVM 堆限制在 256–512MB（对应技能 JVM 内存规范）；数据写入命名卷 hg_data 实现持久化（见「五」）。

4.2 启动服务

cd /opt/hugegraph/compose
docker compose up -d

4.3 查看运行状态

cd /opt/hugegraph/compose
docker compose ps

4.4 验证 8080 健康 / 图列表

curl -s http://localhost:8080/graphs

实测回显（镜像内 HugeGraphServer 返回）：

{"graphs":["hugegraph"]}

4.5 进入容器内部运维

docker exec -it hugegraph-server bash

五、数据持久化说明

  • 命名卷 hg_data（volumes: hg_data:）挂载到容器内 /hugegraph-server/data，RocksDB 数据落盘到该卷，docker compose down 不会删除卷，数据保留。
  • 若需彻底清空数据再重建（危险操作），应显式加 -v：docker compose down -v（会同时删除 hg_data 卷）。
  • 配置以只读方式挂载 ./conf/graphs，可在宿主机直接改 conf/graphs/hugegraph.properties（如切换 backend）后重启生效。

六、常用环境变量表

环境变量作用备注
JAVA_OPTIONS注入 JVM 参数（堆大小等）本部署置为 -Xms256m -Xmx512m
OPEN_MONITOR是否开启监控默认关闭
OPEN_SECURITY_CHECK是否开启安全启动检查默认 true

💡 说明：镜像内起动脚本 start-hugegraph.sh/hugegraph-server.sh 会读取 JAVA_OPTIONS，非空时直接使用该组堆参数（与 tar.gz 安装版行为一致）。

七、常用配置参数说明（command）

若需覆盖镜像默认启动命令，可在 service 里通过 command: 指定（覆盖默认 start-hugegraph.sh）：

services:
  hugegraph-server:
    image: hugegraph/hugegraph-server
    command: ["/bin/bash", "/hugegraph-server/bin/start-hugegraph.sh"]

通常无需覆盖 command，默认入口已包含 store 自动初始化与启动。

八、配置文件持久化（conf 挂载）

  • 后端切换：宿主机 ./conf/graphs/hugegraph.properties 中 backend=（默认 rocksdb）决定存储后端；1.7.0 支持 hstore / rocksdb / hbase / memory。
  • 认证开关：宿主机 ./conf/rest-server.properties 中 auth.authenticator、auth.admin_pa。
  • Gremlin Server：./conf/gremlin-server.yaml（8182 端口、channelizer、序列化器）。
  • 修改宿主机挂载的 conf 后执行 docker compose restart hugegraph-server 生效。

九、等价 docker run 运行方式

未使用 Compose 时，等价手动启动命令如下：

docker volume create hg_data
docker run -d --name hugegraph-server \
  -p 8080:8080 -p 8182:8182 \
  -e JAVA_OPTIONS="-Xms256m -Xmx512m" \
  -v hg_data:/hugegraph-server/data \
  -v /opt/hugegraph/compose/conf/graphs:/hugegraph-server/conf/graphs:ro \
  --restart unless-stopped \
  hugegraph/hugegraph-server

十、常用运维命令

docker compose up -d                     # 启动
docker compose ps                        # 查看状态
docker compose logs -f hugegraph-server  # 实时日志
docker compose restart hugegraph-server  # 重启（改配置后）
docker compose down                      # 停止并删除容器（保留数据卷）
docker compose down -v                   # 停止并删除容器与数据卷（清空数据）

十一、常见问题（FAQ）

Q1：8080 端口访问不到 先确认 docker compose ps 为 Up，再 docker compose logs hugegraph-server 看是否出现 store 未初始化或端口被占用的错误；若宿主机 8080 被占用，修改 compose 的左侧端口映射（如 18080:8080）后 docker compose up -d。

Q2：改了配置不生效 conf 以只读卷挂载，改完宿主机文件后必须 docker compose restart hugegraph-server；若仍不生效，确认挂载目录与镜像内路径一致。

Q3：Gremlin 调用报 gremlin-groovy is not an available GremlinScriptEngine 镜像内 Groovy 版本对 JDK 版本敏感（详见《Ubuntu 22.04 安装 Apache HugeGraph 1.7.0 指南》常见问题）；如遇此情况，确认镜像所配 JDK 与 Gremin 引擎兼容，或改用 REST API 完成图操作。

Q4：数据想换后端（如 HBase） 在挂载的 conf/graphs/hugegraph.properties 中把 backend= 改为 hbase（1.7.0 支持范围 hstore/rocksdb/hbase/memory），配好 hbase.hosts 等参数后重启；注意 1.7.0 已不支持 MySQL/PG/Cassandra 后端。

十二、参考链接