Source: https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/ Documentation version: v5.3.2 # 使用 Docker Compose 部署开发版 通过 Docker Compose 在一台开发机上启动悦数图数据库开发版和悦数图管理。服务启动后，可在浏览器中连接并查询示例数据。 ## 部署前准备 - 一台 Windows、macOS 或 Linux 开发机，采用 AMD64（x86_64）或 ARM64 架构。 - 已[安装 Docker 和 Docker Compose](https://docs.docker.com/compose/install/)，且 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](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/files/compose.yaml) 并保存到该文件夹，然后在该文件夹中打开终端。 ## 2. 设置登录密码 本文使用悦数图数据库开发版账号`root`。`compose.yaml`中的`ROOT_PASSWORD`指定它的初始密码： ```` ROOT_PASSWORD: 'YueshuGraph01' ```` 可保留该值。如需修改，用文本编辑器找到这一行，替换引号内的密码并保存，保留原有缩进和其他配置。 密码要求：长度至少 8 个字符，且同时包含大写字母、小写字母和数字。首次启动时会自动设置该密码，后续登录悦数图管理时也使用它。 复用已有`data`目录时，须填写原密码，并保留服务组名`default_svcgrp`。更改已有实例的密码见[修改已有实例的 root 密码](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#change-root-password)。 密码包含 $ 时的写法 在`compose.yaml`中，将每个`$`写成`$$`；登录时仍使用单个`$`。例如，实际密码为`Graph$2026`时，配置写为`ROOT_PASSWORD: 'Graph$$2026'`。这是 [Docker Compose 的转义规则](https://docs.docker.com/reference/compose-file/interpolation/)。 ## 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](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/#docker-compose) | `Up`（运行中） | [ngctl](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngctl/#docker-compose)、`studio` | `Up`且包含`(healthy)` Graph 服务和 Storage 服务会在`ngctl`健康检查通过后启动。服务尚未全部启动或健康检查仍在进行时，稍后再次检查；出现`Exited`、持续重启或`unhealthy`时，见[部署问题排查](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#troubleshooting)。 ## 常用操作 以下命令均在开发机终端的部署目录中执行。 停止和重新启动服务 停止服务： ```` docker compose stop ```` 再次使用时，启动已有容器： ```` docker compose start ```` `stop`保留容器和数据。重新[检查服务状态](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#check-services)后，按[退出并恢复查询](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/first-query/#resume)继续练习。 悦数图数据库开发版数据保存在部署目录下的`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`容器，只需[检查其余五个服务](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#check-services)。如仍不需要悦数图管理，以后启动整套服务时继续在`up`命令中带上`--scale studio=0`。 `start studio`只能启动已有容器；执行过`down`后，需用`up`重新创建。移除容器会保留`studio-data`卷。 登录步骤见[连接并完成首次查询](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/first-query/#connect)。需要使用二进制安装包等方式独立部署时，见[安装悦数图管理](https://dev-docs.yueshu.com.cn/v5.3.2/visualization/studio/install/)。 修改已有实例的 root 密码 仅在需要更改已启动实例的密码时执行。先确认`ngctl`健康；仅编辑`ROOT_PASSWORD`不会更改已有实例的密码。 1. 将``和``分别替换为当前密码和新密码，执行： ```` docker compose exec ngctl ngctl auth passwd -H graph-cluster -P 9559 -u root -c '' -p '' ```` 此处输入实际密码，不要使用 Compose 文件中的`$$`转义。密码包含单引号时，需按开发机所用终端的规则转义。新密码需满足[密码要求](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#root-password)。看到`Change password succeeded.`后，再继续下一步。 2. 将`compose.yaml`中`services.ngctl.environment.ROOT_PASSWORD`更新为新密码。密码包含`$`时，按[转义规则](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#password-escaping)写成`$$`。 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. 按[检查服务状态](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#check-services)确认服务正常，再使用新密码重新登录`ngql`、网页控制台或 Studio。已有图数据保留，无需重新加载示例数据集。 移除服务 ```` docker compose down ```` 该命令移除整套服务的容器和网络，包括已启动的`studio`，但保留镜像、悦数图数据库开发版的`data`和`logs`目录，以及悦数图管理的`studio-data`卷。 删除数据 `docker compose down -v`会删除`studio-data`等命名卷。删除整个部署目录还会永久删除悦数图数据库开发版数据。执行前，确认这些数据不再需要或已另行备份。 服务、端口和数据目录的配置见 [Docker Compose 配置说明](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/configurations/docker-compose/)，使用范围与容量上限见[功能与限制](https://dev-docs.yueshu.com.cn/v5.3.2/intro/limitations/)。 ## 部署问题排查 服务无法启动时，在部署目录查看日志；初始化未完成时，重点查看`ngctl`日志： ```` docker compose logs --tail 100 docker compose logs --tail 100 ngctl ```` | 现象 | 处理方法 | 镜像拉取失败 | 核对配套文件中的镜像名称和标签，检查镜像仓库的网络连接 | 容器名已被占用 | 执行`docker ps -a`查找同名容器，确认其用途后再处理，避免删除其他实例 | 提示端口已被占用 | 按[端口配置说明](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/configurations/docker-compose/#ports)修改冲突的开发机端口，再重新启动 | 找不到配置或 YAML 解析失败 | 确认终端位于部署目录，文件名为`compose.yaml`，且缩进和引号正确 | `metad`日志出现`EULA_NOT_ACCEPTED` | 确认接受许可协议后，将`services.metad.environment.ACCEPT_EULA`设为字符串`"Y"`，再按[启动服务](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#start-database)重新创建容器 | `ngctl`一直等待登录 | 检查[密码要求](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#root-password)；复用已有`data`时须填写原密码 | `ngctl`未通过健康检查，后续服务未启动 | 查看`ngctl`和`metad`日志，先解决登录或服务组初始化错误 | Graph 服务或 Storage 服务无法启动或持续重启 | 检查 Docker 可用内存。配套配置要求为操作系统和其他进程预留 1 GiB。保留错误信息和`data`目录，避免丢失已有数据 修正后，重新[启动服务](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#start-database)。 端口映射显示在 metad 行 Graph 服务和 Storage 服务与 Meta 服务共用容器网络，因此`9559`、`9779`、`9669`和`19669`的端口映射都显示在`metad`行。开发机端口可按[端口配置说明](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/configurations/docker-compose/#ports)修改。 ### 无法打开 Studio 在部署目录中检查 Studio 的状态和日志： ```` docker compose ps --all studio ```` ```` docker compose logs --tail 50 studio ```` 确认`studio`正在运行，且浏览器使用的端口与`compose.yaml`中的开发机端口一致，默认为`7001`。跨机器访问时，还需确认该端口可从浏览器所在机器访问。 ## 下一步 确认[服务状态](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/deploy/#check-services)正常后，在悦数图管理中登录、加载示例数据并执行查询： [连接并完成首次查询 →](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/first-query/)