使用 Docker Compose 部署开发版

通过 Docker Compose 在一台开发机上启动悦数图数据库开发版和悦数图管理。服务启动后，可在浏览器中连接并查询示例数据。

部署前准备

• 一台 Windows、macOS 或 Linux 开发机，采用 AMD64（x86_64）或 ARM64 架构。
• 已安装 Docker 和 Docker Compose，且 Docker 正在运行。
• 开发机能连接镜像仓库，并为 Docker、悦数图数据库开发版和示例数据预留足够的内存与磁盘空间。

本文命令均在运行 Docker 的开发机终端执行；Windows 可使用 PowerShell。先检查 Docker 环境：

docker compose version
docker info

能看到 Compose 版本和 Docker 服务信息后，继续下面的步骤。若命令不存在、无法连接 Docker 或权限不足，先解决相应问题。

1. 创建部署目录并下载配置文件

在开发机终端执行以下命令，创建并进入部署目录dev-quickstart，下载compose.yaml。数据库的数据和日志也将保存在此目录。

Linux / macOSWindows PowerShell

mkdir dev-quickstart
cd dev-quickstart
curl -fL -o compose.yaml \
  "https://dev-docs.yueshu.com.cn/v5.3.2/get-started/files/compose.yaml"

New-Item -ItemType Directory -Path dev-quickstart
Set-Location dev-quickstart
Invoke-WebRequest -UseBasicParsing `
  -Uri "https://dev-docs.yueshu.com.cn/v5.3.2/get-started/files/compose.yaml" `
  -OutFile compose.yaml

文件将保存为当前目录下的compose.yaml。后续命令均在此目录执行。

也可以新建空文件夹dev-quickstart，通过浏览器下载 compose.yaml 并保存到该文件夹，然后在该文件夹中打开终端。

2. 设置登录密码

本文使用悦数图数据库开发版账号root。compose.yaml中的ROOT_PASSWORD指定它的初始密码：

ROOT_PASSWORD: 'YueshuGraph01'

可保留该值。如需修改，用文本编辑器找到这一行，替换引号内的密码并保存，保留原有缩进和其他配置。

密码要求：长度至少 8 个字符，且同时包含大写字母、小写字母和数字。首次启动时会自动设置该密码，后续登录悦数图管理时也使用它。

复用已有data目录时，须填写原密码，并保留服务组名default_svcgrp。更改已有实例的密码见修改已有实例的 root 密码。

密码包含 $ 时的写法

在compose.yaml中，将每个$写成$$；登录时仍使用单个$。例如，实际密码为Graph$2026时，配置写为ROOT_PASSWORD: 'Graph$$2026'。这是 Docker Compose 的转义规则。

3. 启动服务

1. 在部署目录中检查配置：

   docker compose config --quiet
   

   没有输出且没有报错，表示检查通过。若报错，确认终端位于部署目录，文件名为compose.yaml，并检查 YAML 缩进和引号。

2. 确认接受最终用户许可协议（EULA）后，启动服务。配套compose.yaml已设置ACCEPT_EULA: "Y"，表示接受协议。

   Linux / macOSWindows PowerShell

   ACCEPT_EULA=Y docker compose up -d
   

   docker compose up -d
   

   执行本文其他启动命令时，省略ACCEPT_EULA=Y，保留其余参数。

   本地缺少的镜像会自动下载。命令成功后，悦数图数据库开发版和悦数图管理在后台运行。

4. 检查服务状态

在同一终端中执行：

docker compose ps --all

检查六个服务的STATUS列：

服务	预期状态
metad、storaged、graphd、ngql	Up（运行中）
ngctl、studio	Up且包含(healthy)

Graph 服务和 Storage 服务会在ngctl健康检查通过后启动。服务尚未全部启动或健康检查仍在进行时，稍后再次检查；出现Exited、持续重启或unhealthy时，见部署问题排查。

常用操作

以下命令均在开发机终端的部署目录中执行。

停止和重新启动服务

停止服务：

docker compose stop

再次使用时，启动已有容器：

docker compose start

stop保留容器和数据。重新检查服务状态后，按退出并恢复查询继续练习。

悦数图数据库开发版数据保存在部署目录下的data/meta和data/storage，日志保存在logs。保留整个部署目录以便继续使用原数据；数据备份需另行安排。

单独启停悦数图管理

悦数图数据库开发版服务已启动时，可以单独管理悦数图管理：

操作	命令
启用启动时跳过的图管理	docker compose up -d studio
暂时停止，保留容器	docker compose stop studio
恢复已停止的容器	docker compose start studio

不需要配套悦数图管理时，启动服务改用以下命令；如果studio容器已创建，该命令会将其移除：

ACCEPT_EULA=Y docker compose up -d --scale studio=0

此时不会创建或保留studio容器，只需检查其余五个服务。如仍不需要悦数图管理，以后启动整套服务时继续在up命令中带上--scale studio=0。

start studio只能启动已有容器；执行过down后，需用up重新创建。移除容器会保留studio-data卷。

登录步骤见连接并完成首次查询。需要使用二进制安装包等方式独立部署时，见安装悦数图管理。

修改已有实例的 root 密码

仅在需要更改已启动实例的密码时执行。先确认ngctl健康；仅编辑ROOT_PASSWORD不会更改已有实例的密码。

1. 将<current-password>和<new-password>分别替换为当前密码和新密码，执行：

   docker compose exec ngctl ngctl auth passwd -H graph-cluster -P 9559 -u root -c '<current-password>' -p '<new-password>'
   

   此处输入实际密码，不要使用 Compose 文件中的$$转义。密码包含单引号时，需按开发机所用终端的规则转义。新密码需满足密码要求。看到Change password succeeded.后，再继续下一步。

2. 将compose.yaml中services.ngctl.environment.ROOT_PASSWORD更新为新密码。密码包含$时，按转义规则写成$$。

3. 检查配置：

   docker compose config --quiet
   

   检查通过后，应用更新：

   ACCEPT_EULA=Y docker compose up -d
   

   不需要容器版 Studio 时，改用ACCEPT_EULA=Y docker compose up -d --scale studio=0。docker compose restart不会应用修改后的ROOT_PASSWORD环境变量。

4. 按检查服务状态确认服务正常，再使用新密码重新登录ngql、网页控制台或 Studio。已有图数据保留，无需重新加载示例数据集。

移除服务

docker compose down

该命令移除整套服务的容器和网络，包括已启动的studio，但保留镜像、悦数图数据库开发版的data和logs目录，以及悦数图管理的studio-data卷。

删除数据

docker compose down -v会删除studio-data等命名卷。删除整个部署目录还会永久删除悦数图数据库开发版数据。执行前，确认这些数据不再需要或已另行备份。

服务、端口和数据目录的配置见 Docker Compose 配置说明，使用范围与容量上限见功能与限制。

部署问题排查

服务无法启动时，在部署目录查看日志；初始化未完成时，重点查看ngctl日志：

docker compose logs --tail 100
docker compose logs --tail 100 ngctl

现象	处理方法
镜像拉取失败	核对配套文件中的镜像名称和标签，检查镜像仓库的网络连接
容器名已被占用	执行docker ps -a查找同名容器，确认其用途后再处理，避免删除其他实例
提示端口已被占用	按端口配置说明修改冲突的开发机端口，再重新启动
找不到配置或 YAML 解析失败	确认终端位于部署目录，文件名为compose.yaml，且缩进和引号正确
metad日志出现EULA_NOT_ACCEPTED	确认接受许可协议后，将services.metad.environment.ACCEPT_EULA设为字符串"Y"，再按启动服务重新创建容器
ngctl一直等待登录	检查密码要求；复用已有data时须填写原密码
ngctl未通过健康检查，后续服务未启动	查看ngctl和metad日志，先解决登录或服务组初始化错误
Graph 服务或 Storage 服务无法启动或持续重启	检查 Docker 可用内存。配套配置要求为操作系统和其他进程预留 1 GiB。保留错误信息和data目录，避免丢失已有数据

修正后，重新启动服务。

端口映射显示在 metad 行

Graph 服务和 Storage 服务与 Meta 服务共用容器网络，因此9559、9779、9669和19669的端口映射都显示在metad行。开发机端口可按端口配置说明修改。

无法打开 Studio

在部署目录中检查 Studio 的状态和日志：

docker compose ps --all studio

docker compose logs --tail 50 studio

确认studio正在运行，且浏览器使用的端口与compose.yaml中的开发机端口一致，默认为7001。跨机器访问时，还需确认该端口可从浏览器所在机器访问。

下一步

确认服务状态正常后，在悦数图管理中登录、加载示例数据并执行查询：

连接并完成首次查询 →