Sergey Antropoff
248 lines
12 KiB
Markdown
248 lines
12 KiB
Markdown
# NebulaGraph 3.8 + Elasticsearch 7 + Studio
|
||
|
||
## Быстрый запуск
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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`. Проверка из любого хоста:
|
||
|
||
```bash
|
||
make check
|
||
```
|
||
|
||
Число в ответе должно быть не меньше `262144`.
|
||
|
||
## Запуск
|
||
|
||
```bash
|
||
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 описано в разделе «Подключение приложения».
|
||
|
||
Интерактивная консоль:
|
||
|
||
```bash
|
||
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`).
|
||
|
||
```bash
|
||
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 из каталога проекта:
|
||
|
||
```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
|
||
```
|
||
|
||
### Полезные команды
|
||
|
||
```bash
|
||
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. Узлы хранения
|
||
|
||
```ngql
|
||
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`.
|
||
|
||
```ngql
|
||
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
|
||
|
||
```ngql
|
||
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. Схема, индекс и данные
|
||
|
||
```ngql
|
||
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` это учитывает.
|
||
|
||
```ngql
|
||
INSERT VERTEX document(title, content) VALUES
|
||
"doc-001":("Kubernetes", "Container orchestration platform"),
|
||
"doc-002":("NebulaGraph", "Distributed graph database");
|
||
```
|
||
|
||
Индексация идёт асинхронно через listener. Для уже лежащих в пространстве данных:
|
||
|
||
```ngql
|
||
USE demo;
|
||
REBUILD FULLTEXT INDEX;
|
||
```
|
||
|
||
Проверка со стороны NebulaGraph — запрос в Elasticsearch через индекс:
|
||
|
||
```ngql
|
||
USE demo;
|
||
LOOKUP ON document
|
||
WHERE ES_QUERY(document_search, "Kubernetes")
|
||
YIELD id(vertex);
|
||
```
|
||
|
||
В ответе должен быть `doc-001`. Анализатор `standard` приводит слово к нижнему регистру, поэтому в Elasticsearch документ ищется и по `Kubernetes`.
|
||
|
||
Появление индекса снаружи:
|
||
|
||
```bash
|
||
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.
|