基于 Docker 快速部署¶

NebulaGraph 提供了基于 Docker 的快速部署方式，可以在几分钟内完成部署。

使用 Docker Desktop使用 Docker Compose

按照以下步骤可以快速在 Docker Desktop 中部署NebulaGraph。

安装 Docker Desktop。

Caution

如果在 Windows 端安装 Docker Desktop 需安装 WSL 2。
在仪表盘中单击Extensions或Add Extensions打开Extensions Marketplace 搜索NebulaGraph ，也可以点击 NebulaGraph 在 Docker Desktop 打开。
导航到NebulaGraph的扩展市场。
点击Install下载NebulaGraph。
在有更新的时候，可以点击Update更新到最新版本。

视频介绍

使用 Docker Compose 可以基于准备好的配置文件快速部署NebulaGraph服务，仅建议在测试NebulaGraph功能时使用该方式。

前提条件¶

主机上安装如下应用程序。

应用程序推荐版本官方安装参考

Docker 最新版本 Install Docker Engine

Docker Compose 最新版本 Install Docker Compose

Git 最新版本 Download Git

如果使用非 root 用户部署NebulaGraph，请授权该用户 Docker 相关的权限。详细信息，请参见 Manage Docker as a non-root user。

启动主机上的 Docker 服务。

如果已经通过 Docker Compose 在主机上部署了另一个版本的NebulaGraph，为避免兼容性问题，需要删除目录nebula-docker-compose/data。

部署NebulaGraph¶

通过 Git 克隆nebula-docker-compose仓库的3.5.0分支到主机。

Danger

master分支包含最新的未测试代码。请不要在生产环境使用此版本。
```
$ git clone -b release-3.5 https://github.com/vesoft-inc/nebula-docker-compose.git
```
Note

Docker Compose 的x.y版本对齐内核的x.y版本，对于内核z版本，Docker Compose 不会发布对应的z版本，但是会拉取z版本的内核镜像。
切换至目录nebula-docker-compose。
```
$ cd nebula-docker-compose/
```

执行如下命令启动NebulaGraph服务。

Note

如果长期未内核更新镜像，请先更新 NebulaGraph镜像和 NebulaGraph Console 镜像。
执行命令后的返回结果因安装目录不同而不同。

[nebula-docker-compose]$ docker-compose up -d
Creating nebuladockercompose_metad0_1 ... done
Creating nebuladockercompose_metad2_1 ... done
Creating nebuladockercompose_metad1_1 ... done
Creating nebuladockercompose_graphd2_1   ... done
Creating nebuladockercompose_graphd_1    ... done
Creating nebuladockercompose_graphd1_1   ... done
Creating nebuladockercompose_storaged0_1 ... done
Creating nebuladockercompose_storaged2_1 ... done
Creating nebuladockercompose_storaged1_1 ... done

Compatibility

从 3.1 版本开始，Docker-compose 会自动启动 NebulaGraph Console 镜像的容器，并将 Storage 主机增加至集群中（即ADD HOSTS命令）。

Note

上述服务的更多信息，请参见架构总览。

连接NebulaGraph¶

连接NebulaGraph有两种方式：

在容器外通过 Nebula Console 连接。因为容器的配置文件中将 Graph 服务的外部映射端口也固定为 9669，因此可以直接通过默认端口连接。详情参见连接NebulaGraph。

登录安装了 NebulaGraph Console 的容器，然后再连接 Graph 服务。本小节介绍这种方式。

使用docker-compose ps命令查看 NebulaGraph Console 容器名称。

$ docker-compose ps
          Name                         Command             State                 Ports
----------------------------------------------------------------------------------------------
nebuladockercompose_console_1     sh -c sleep 3 &&          Up
                                  nebula-co ...
......

进入 NebulaGraph Console 容器中。

$ docker exec -it nebuladockercompose_console_1 /bin/sh
/ #

通过 NebulaGraph Console 连接NebulaGraph。
```
/ # ./usr/local/bin/nebula-console -u <user_name> -p <password> --address=graphd --port=9669
```
Note

默认情况下，身份认证功能是关闭的，只能使用已存在的用户名（默认为root）和任意密码登录。如果想使用身份认证，请参见身份认证。

查看集群状态。

nebula> SHOW HOSTS;
+-------------+------+----------+--------------+----------------------+------------------------+---------+
| Host        | Port | Status   | Leader count | Leader distribution  | Partition distribution | Version |
+-------------+------+----------+--------------+----------------------+------------------------+---------+
| "storaged0" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
| "storaged1" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
| "storaged2" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
+-------------+------+----------+--------------+----------------------+------------------------+---------+

执行两次exit可以退出容器。

查看NebulaGraph服务的状态和端口¶

执行命令docker-compose ps可以列出NebulaGraph服务的状态和端口。

Note

NebulaGraph默认使用9669端口为客户端提供服务，如果需要修改端口，请修改目录nebula-docker-compose内的文件docker-compose.yaml，然后重启NebulaGraph服务。

$ docker-compose ps
nebuladockercompose_console_1     sh -c sleep 3 &&                 Up
                                  nebula-co ...
nebuladockercompose_graphd1_1     /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49174->19669/tcp,:::49174->19669/tcp, 0.0.0.0:49171->19670/tcp,:::49171->19670/tcp, 0.0.0.0:49177->9669/tcp,:::49177->9669/tcp
nebuladockercompose_graphd2_1     /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49175->19669/tcp,:::49175->19669/tcp, 0.0.0.0:49172->19670/tcp,:::49172->19670/tcp, 0.0.0.0:49178->9669/tcp,:::49178->9669/tcp
nebuladockercompose_graphd_1      /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49180->19669/tcp,:::49180->19669/tcp, 0.0.0.0:49179->19670/tcp,:::49179->19670/tcp, 0.0.0.0:9669->9669/tcp,:::9669->9669/tcp
nebuladockercompose_metad0_1      /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49157->19559/tcp,:::49157->19559/tcp, 0.0.0.0:49154->19560/tcp,:::49154->19560/tcp, 0.0.0.0:49160->9559/tcp,:::49160->9559/tcp, 9560/tcp
nebuladockercompose_metad1_1      /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49156->19559/tcp,:::49156->19559/tcp, 0.0.0.0:49153->19560/tcp,:::49153->19560/tcp, 0.0.0.0:49159->9559/tcp,:::49159->9559/tcp, 9560/tcp
nebuladockercompose_metad2_1      /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49158->19559/tcp,:::49158->19559/tcp, 0.0.0.0:49155->19560/tcp,:::49155->19560/tcp, 0.0.0.0:49161->9559/tcp,:::49161->9559/tcp, 9560/tcp
nebuladockercompose_storaged0_1   /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49166->19779/tcp,:::49166->19779/tcp, 0.0.0.0:49163->19780/tcp,:::49163->19780/tcp, 9777/tcp, 9778/tcp, 0.0.0.0:49169->9779/tcp,:::49169->9779/tcp, 9780/tcp
nebuladockercompose_storaged1_1   /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49165->19779/tcp,:::49165->19779/tcp, 0.0.0.0:49162->19780/tcp,:::49162->19780/tcp, 9777/tcp, 9778/tcp, 0.0.0.0:49168->9779/tcp,:::49168->9779/tcp, 9780/tcp
nebuladockercompose_storaged2_1   /usr/local/nebula/bin/nebu ...   Up      0.0.0.0:49167->19779/tcp,:::49167->19779/tcp, 0.0.0.0:49164->19780/tcp,:::49164->19780/tcp, 9777/tcp, 9778/tcp, 0.0.0.0:49170->9779/tcp,:::49170->9779/tcp, 9780/tcp

如果服务有异常，用户可以先确认异常的容器名称（例如nebuladockercompose_graphd2_1）,

然后执行docker ps查看对应的CONTAINER ID（示例为2a6c56c405f5)。

[nebula-docker-compose]$ docker ps
CONTAINER ID   IMAGE                               COMMAND                  CREATED          STATUS                    PORTS                                                                                                  NAMES
2a6c56c405f5   vesoft/nebula-graphd:nightly     "/usr/local/nebula/b…"   36 minutes ago   Up 36 minutes (healthy)   0.0.0.0:49230->9669/tcp, 0.0.0.0:49229->19669/tcp, 0.0.0.0:49228->19670/tcp                            nebuladockercompose_graphd2_1
7042e0a8e83d   vesoft/nebula-storaged:nightly   "./bin/nebula-storag…"   36 minutes ago   Up 36 minutes (healthy)   9777-9778/tcp, 9780/tcp, 0.0.0.0:49227->9779/tcp, 0.0.0.0:49226->19779/tcp, 0.0.0.0:49225->19780/tcp   nebuladockercompose_storaged2_1
18e3ea63ad65   vesoft/nebula-storaged:nightly   "./bin/nebula-storag…"   36 minutes ago   Up 36 minutes (healthy)   9777-9778/tcp, 9780/tcp, 0.0.0.0:49219->9779/tcp, 0.0.0.0:49218->19779/tcp, 0.0.0.0:49217->19780/tcp   nebuladockercompose_storaged0_1
4dcabfe8677a   vesoft/nebula-graphd:nightly     "/usr/local/nebula/b…"   36 minutes ago   Up 36 minutes (healthy)   0.0.0.0:49224->9669/tcp, 0.0.0.0:49223->19669/tcp, 0.0.0.0:49222->19670/tcp                            nebuladockercompose_graphd1_1
a74054c6ae25   vesoft/nebula-graphd:nightly     "/usr/local/nebula/b…"   36 minutes ago   Up 36 minutes (healthy)   0.0.0.0:9669->9669/tcp, 0.0.0.0:49221->19669/tcp, 0.0.0.0:49220->19670/tcp                             nebuladockercompose_graphd_1
880025a3858c   vesoft/nebula-storaged:nightly   "./bin/nebula-storag…"   36 minutes ago   Up 36 minutes (healthy)   9777-9778/tcp, 9780/tcp, 0.0.0.0:49216->9779/tcp, 0.0.0.0:49215->19779/tcp, 0.0.0.0:49214->19780/tcp   nebuladockercompose_storaged1_1
45736a32a23a   vesoft/nebula-metad:nightly      "./bin/nebula-metad …"   36 minutes ago   Up 36 minutes (healthy)   9560/tcp, 0.0.0.0:49213->9559/tcp, 0.0.0.0:49212->19559/tcp, 0.0.0.0:49211->19560/tcp                  nebuladockercompose_metad0_1
3b2c90eb073e   vesoft/nebula-metad:nightly      "./bin/nebula-metad …"   36 minutes ago   Up 36 minutes (healthy)   9560/tcp, 0.0.0.0:49207->9559/tcp, 0.0.0.0:49206->19559/tcp, 0.0.0.0:49205->19560/tcp                  nebuladockercompose_metad2_1
7bb31b7a5b3f   vesoft/nebula-metad:nightly      "./bin/nebula-metad …"   36 minutes ago   Up 36 minutes (healthy)   9560/tcp, 0.0.0.0:49210->9559/tcp, 0.0.0.0:49209->19559/tcp, 0.0.0.0:49208->19560/tcp                  nebuladockercompose_metad1_1

最后登录容器排查问题

[nebula-docker-compose]$ docker exec -it 2a6c56c405f5 bash
[root@2a6c56c405f5 nebula]#

查看NebulaGraph服务的数据和日志¶

NebulaGraph的所有数据和日志都持久化存储在nebula-docker-compose/data和nebula-docker-compose/logs目录中。

目录的结构如下：

nebula-docker-compose/
  |-- docker-compose.yaml
  ├── data
  │   ├── meta0
  │   ├── meta1
  │   ├── meta2
  │   ├── storage0
  │   ├── storage1
  │   └── storage2
  └── logs
      ├── graph
      ├── graph1
      ├── graph2
      ├── meta0
      ├── meta1
      ├── meta2
      ├── storage0
      ├── storage1
      └── storage2

停止NebulaGraph服务¶

用户可以执行如下命令停止NebulaGraph服务：

$ docker-compose down

如果返回如下信息，表示已经成功停止服务。

Stopping nebuladockercompose_console_1   ... done
Stopping nebuladockercompose_graphd1_1   ... done
Stopping nebuladockercompose_graphd_1    ... done
Stopping nebuladockercompose_graphd2_1   ... done
Stopping nebuladockercompose_storaged1_1 ... done
Stopping nebuladockercompose_storaged0_1 ... done
Stopping nebuladockercompose_storaged2_1 ... done
Stopping nebuladockercompose_metad2_1    ... done
Stopping nebuladockercompose_metad0_1    ... done
Stopping nebuladockercompose_metad1_1    ... done
Removing nebuladockercompose_console_1   ... done
Removing nebuladockercompose_graphd1_1   ... done
Removing nebuladockercompose_graphd_1    ... done
Removing nebuladockercompose_graphd2_1   ... done
Removing nebuladockercompose_storaged1_1 ... done
Removing nebuladockercompose_storaged0_1 ... done
Removing nebuladockercompose_storaged2_1 ... done
Removing nebuladockercompose_metad2_1    ... done
Removing nebuladockercompose_metad0_1    ... done
Removing nebuladockercompose_metad1_1    ... done
Removing network nebuladockercompose_nebula-net

Danger

命令docker-compose down -v的参数-v将会删除所有本地的数据。如果使用的是 nightly 版本，并且有一些兼容性问题，请尝试这个命令。

修改配置¶

Docker Compose 部署的NebulaGraph，配置文件位置为nebula-docker-compose/docker-compose.yaml，修改该文件内的配置并重启服务即可使新配置生效。

具体的配置说明请参见配置管理。

常见问题¶

如何固定 Docker 映射到外部的端口？¶

在目录nebula-docker-compose内修改文件docker-compose.yaml，将对应服务的ports设置为固定映射，例如：

graphd:
    image: vesoft/nebula-graphd:release-3.5
    ...
    ports:
      - 9669:9669
      - 19669
      - 19670

9669:9669表示内部的 9669 映射到外部的端口也是 9669，下方的19669表示内部的 19669 映射到外部的端口是随机的。

如何升级/更新NebulaGraph服务的 Docker 镜像？¶

在文件nebula-docker-compose/docker-compose.yaml中，找到所有服务的image并修改其值为相应的镜像版本。
在目录nebula-docker-compose内执行命令docker-compose pull，更新 Graph 服务、Storage 服务、Meta 服务和 NebulaGraph Console 的镜像。
执行命令docker-compose up -d启动NebulaGraph服务。
通过 NebulaGraph Console 连接NebulaGraph后，分别执行命令SHOW HOSTS GRAPH、SHOW HOSTS STORAGE、SHOW HOSTS META查看各服务版本。

执行命令`docker-compose pull`报错`ERROR: toomanyrequests`¶

可能遇到如下错误：

ERROR: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

以上错误表示已达到 Docker Hub 的速率限制。解决方案请参见 Understanding Docker Hub Rate Limiting。

如何更新 NebulaGraph Console？¶

docker-compose pull会同时更新NebulaGraph服务和 NebulaGraph Console。

最后更新: 2026年9月24日

应用程序	推荐版本	官方安装参考
Docker	最新版本	Install Docker Engine
Docker Compose	最新版本	Install Docker Compose
Git	最新版本	Download Git

基于 Docker 快速部署¶

前提条件¶

部署NebulaGraph¶

连接NebulaGraph¶

查看NebulaGraph服务的状态和端口¶

查看NebulaGraph服务的数据和日志¶

停止NebulaGraph服务¶

修改配置¶

常见问题¶

如何固定 Docker 映射到外部的端口？¶

如何升级/更新NebulaGraph服务的 Docker 镜像？¶

执行命令docker-compose pull报错ERROR: toomanyrequests¶

如何更新 NebulaGraph Console？¶

执行命令`docker-compose pull`报错`ERROR: toomanyrequests`¶