nebula-compose/README.md

NebulaGraph 3.8 + Elasticsearch 7 + Studio

Быстрый запуск

make verify
make es-health
make ps

Первый make verify сам создаёт .env из .env.example, поднимает контейнеры и проводит проверку.

Команда	Что делает
make verify	Поднимает стек и проверяет регистрацию storage, вход в Elasticsearch, listener, полнотекстовый индекс и поиск doc-001.
make es-health	Показывает состояние кластера Elasticsearch. Ожидается green и три узла.
make ps	Печатает статус контейнеров. es-certs в Exited (0) значит, что сертификат уже создан.

Локальный кластер:

Сервис	Число	Адрес в сети Docker	Порт
metad	3	172.30.80.11–.13	9559
storaged	3	172.30.80.21–.23	9779
graphd	1	172.30.80.31	9669
storaged-listener	1	172.30.80.41	9789
Elasticsearch 7.17	3	172.30.80.51–.53	9200
Nebula Studio 3.10	1	имя studio	7001

С хоста опубликованы только 127.0.0.1:9669 (graphd), 127.0.0.1:9200 (Elasticsearch) и 127.0.0.1:7001 (Studio).

Адреса заданы в .env и совпадают на macOS, Linux и Windows: контейнеры видят одну сеть nebula-stack-net, а не localhost хоста.

Что нужно

• Docker Engine или Docker Desktop и Docker Compose v2 (docker compose).
• Для make: macOS, Linux, либо Windows через WSL или Git Bash.
• Память Docker: комфортно от 8 ГБ. В .env у каждого узла Elasticsearch куча 512 МБ.
• Место на диске под образы (около 3–4 ГБ).

На Linux перед первым запуском ядро должно разрешать Elasticsearch много memory map:

sudo sysctl -w vm.max_map_count=262144
echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-elasticsearch.conf
sudo sysctl --system

На macOS и Windows это настройка виртуальной машины Docker Desktop, обычно уже 262144. Проверка из любого хоста:

make check

Число в ответе должно быть не меньше 262144.

Запуск

cp .env.example .env   # make up сделает это сам
make up
make init              # ADD HOSTS и SIGN IN TEXT SERVICE
make verify            # listener, индекс и поиск по тестовым вершинам

make verify включает make init. Контейнер es-certs после успеха в make ps будет Exited (0): сертификат транспортного TLS уже записан в том.

Подключение Studio описано в разделе «Подключение приложения».

Интерактивная консоль:

make console

Остановить, не удаляя данные: make down. Удалить тома: make clean.

Подключение приложения

С хоста

Приложение на той же машине, вне Docker, пишет в граф клиентом NebulaGraph на 127.0.0.1:9669. Пользователь root, пароль nebula. Порт принимает бинарный протокол graphd.

Elasticsearch для просмотра доступен по HTTP на 127.0.0.1:9200. С хоста открыт только первый узел. Пользователь elastic, пароль — ELASTIC_PASSWORD из .env (по умолчанию NebulaEsLab2026).

curl -u "elastic:NebulaEsLab2026" "http://127.0.0.1:9200/_cluster/health?pretty"
curl -u "elastic:NebulaEsLab2026" "http://127.0.0.1:9200/_cat/indices?v"
curl -u "elastic:NebulaEsLab2026" "http://127.0.0.1:9200/document_search/_search?q=Kubernetes&pretty"

document_search — индекс, который появляется после make verify. Если пароль в .env другой, подставьте его.

Порты привязаны к 127.0.0.1 этой машины. Адреса вида 172.30.80.31 предназначены для контейнеров в сети nebula-stack-net.

Из контейнера

Приложение в Docker подключайте к сети nebula-stack-net.

Куда	Адрес
graphd	graphd:9669 или 172.30.80.31:9669
Elasticsearch	172.30.80.51:9200, 172.30.80.52:9200, 172.30.80.53:9200

Логин и пароль те же. Внутри контейнера 127.0.0.1 указывает на само приложение.

Nebula Studio

Интерфейс открывается в браузере на той же машине: http://127.0.0.1:7001. На форме подключения к graphd укажите адрес контейнера в сети Docker: Studio сама ходит в graphd из сети nebula-stack-net.

Поле	Значение
Graphd IP	172.30.80.31
Port	9669
Username	root
Password	nebula

После make verify в консоли Studio доступно пространство demo. Сессия Studio живёт около 30 минут; по истечении откройте страницу снова и подключитесь теми же полями. Выйти можно через значок профиля и пункт Log out.

Windows без make

В PowerShell из каталога проекта:

Copy-Item .env.example .env
docker compose up -d
docker compose --profile ops run --rm --no-deps -e OPS_COMMAND=init ops
docker compose --profile ops run --rm --no-deps -e OPS_COMMAND=verify ops
docker compose --profile ops run --rm --no-deps console

Полезные команды

make ps
make logs
make es-health
docker compose logs -f storaged-listener

Проверка Elasticsearch с хоста описана в разделе «Подключение приложения».

Как подключён listener

Полнотекстовый индекс NebulaGraph пишет в Elasticsearch не сам storaged, а отдельный процесс Raft Listener. Это тот же бинарник nebula-storaged, но со своим портом и каталогом WAL. В compose у storaged-listener свой entrypoint: флаги listener не смешиваются с обычным nebula-storaged.conf.

Слушает он 172.30.80.41:9789 (LISTENER_IP в .env). В кластер хранения через ADD HOSTS его не добавляют. Для каждого графового пространства listener регистрируется один раз, все адреса — одним оператором ADD LISTENER. Пока SHOW LISTENER не покажет ONLINE по всем партициям, полнотекстовый индекс не создают.

Учётные данные Elasticsearch глобальные для кластера, не для пространства: один SIGN IN TEXT SERVICE на все space. Повторный вход делается после SIGN OUT TEXT SERVICE.

make init и make verify выполняют команды ниже сами и повторяют попытку, пока метаданные и listener не станут готовы. Вручную между CREATE SPACE, CREATE TAG и индексом нужно подождать одно-два сердцебиения meta (около 20 секунд): иначе пространство или тег ещё не видны.

Пароль в примерах — значение ELASTIC_PASSWORD из .env. Адреса — значения по умолчанию из .env.example.

1. Узлы хранения

ADD HOSTS
  "172.30.80.21":9779,
  "172.30.80.22":9779,
  "172.30.80.23":9779;
SHOW HOSTS;

В SHOW HOSTS три строки ONLINE. До этой команды контейнеры storaged уже запущены, но метаданные ещё не отдают им партиции. make ps может показывать их unhealthy, пока ADD HOSTS не пройдёт.

2. Elasticsearch

Транспорт между es01–es03 зашифрован общим сертификатом, HTTP оставлен без TLS и закрыт basic-авторизацией. NebulaGraph ходит по HTTP, поэтому в SIGN IN схема HTTP, пользователь elastic и пароль из .env.

SIGN IN TEXT SERVICE
  (172.30.80.51:9200, HTTP, "elastic", "NebulaEsLab2026"),
  (172.30.80.52:9200, HTTP, "elastic", "NebulaEsLab2026"),
  (172.30.80.53:9200, HTTP, "elastic", "NebulaEsLab2026");
SHOW TEXT SEARCH CLIENTS;

Ожидаются три строки ELASTICSEARCH. Клиент один на весь кластер. Сброс: SIGN OUT TEXT SERVICE;.

3. Пространство и listener

CREATE SPACE IF NOT EXISTS demo (
  partition_num = 12,
  replica_factor = 3,
  vid_type = FIXED_STRING(64)
);

USE demo;
ADD LISTENER ELASTICSEARCH "172.30.80.41":9789;
SHOW LISTENER;

USE и ADD LISTENER должны быть в одной сессии консоли. SHOW LISTENER — тоже после USE demo. Для 12 партиций будет 12 строк. Ждите ONLINE в каждой. Снять listener с пространства: REMOVE LISTENER ELASTICSEARCH;.

4. Схема, индекс и данные

USE demo;
CREATE TAG IF NOT EXISTS document (
  title STRING,
  content STRING
);
CREATE FULLTEXT TAG INDEX document_search
  ON document(title, content)
  ANALYZER = "standard";
SHOW FULLTEXT INDEXES;

В NebulaGraph 3.8 у CREATE FULLTEXT TAG INDEX нет IF NOT EXISTS. Повторный запуск отвечает Existed!, make verify это учитывает.

INSERT VERTEX document(title, content) VALUES
  "doc-001":("Kubernetes", "Container orchestration platform"),
  "doc-002":("NebulaGraph", "Distributed graph database");

Индексация идёт асинхронно через listener. Для уже лежащих в пространстве данных:

USE demo;
REBUILD FULLTEXT INDEX;

Проверка со стороны NebulaGraph — запрос в Elasticsearch через индекс:

USE demo;
LOOKUP ON document
  WHERE ES_QUERY(document_search, "Kubernetes")
  YIELD id(vertex);

В ответе должен быть doc-001. Анализатор standard приводит слово к нижнему регистру, поэтому в Elasticsearch документ ищется и по Kubernetes.

Появление индекса снаружи:

curl -u "elastic:NebulaEsLab2026" "http://127.0.0.1:9200/_cat/indices?v"

Если адреса другие

Поменяйте подсеть и IP в .env, затем make clean && make up && make verify. Команды nGQL и поле Graphd IP в Studio берите уже из своего .env: listener и ADD HOSTS должны указывать те же адреса, что --local_ip у контейнеров.

На сервере со свободным диском в .env поставьте ES_DISK_THRESHOLD=true. Кучу Elasticsearch увеличивают через ES_JAVA_OPTS. ES_MEMORY_LOCK=true включайте на Linux, где для контейнера разрешён memlock.