Saltearse al contenido

Modo multi-tenant

Por defecto, namidb-server sirve el único namespace indicado en --store. Con --multi-tenant sirve cualquier cantidad de namespaces desde un solo proceso. Cada namespace es un grafo separado con su propio manifest, WAL, archivos de datos, writer, índices y estadísticas, así que los tenants están aislados físicamente, y los tokens pueden limitarse a los namespaces a los que pueden acceder.

Iniciarlo

Ventana de terminal
namidb-server \
--multi-tenant \
--store "file:///var/lib/namidb" \
--auth-tokens-file /etc/namidb/tokens.json \
--bolt-listen 0.0.0.0:7687
  • En modo multi-tenant, --store no necesita ?ns=; si está presente, se ignora con una advertencia.
  • Los namespaces viven directamente en la raíz del store: file:///var/lib/namidb guarda el namespace acme en /var/lib/namidb/acme/. Para s3://, gs:// y az:// viven en la raíz del bucket o contenedor; no se usa un prefijo de ruta en el URI.
  • Un namespace se crea la primera vez que una petición lo abre.

Enrutar una petición a un namespace

ProtocoloCómo se elige el namespace
HTTPEl prefijo de la ruta: POST /acme/v0/cypher
HTTPO el header X-NamiDB-Namespace: acme en la ruta /v0/... sin prefijo
HTTPNinguno de los dos: --default-namespace (por defecto default)
BoltLa base de datos de la sesión del driver: driver.session(database="acme")
BoltSin base de datos indicada: --default-namespace
Ventana de terminal
curl -s localhost:8080/acme/v0/cypher \
-H "Authorization: Bearer $ACME_TOKEN" -H 'Content-Type: application/json' \
-d '{"query": "CREATE (:Item {sku: \"A-1\"})"}'
curl -s localhost:8080/v0/cypher \
-H "Authorization: Bearer $ADMIN_TOKEN" -H 'X-NamiDB-Namespace: acme' \
-H 'Content-Type: application/json' \
-d '{"query": "MATCH (i:Item) RETURN i.sku AS sku"}'
# {"columns":["sku"],"rows":[{"sku":"A-1"}]}
from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt://localhost:7687", auth=("namidb", ACME_TOKEN))
with driver.session(database="acme") as s:
print(s.run("MATCH (i:Item) RETURN i.sku AS sku").value()) # ['A-1']

Una transacción explícita de Bolt queda fijada a la base de datos indicada cuando empezó.

Cada ruta por namespace tiene una forma con prefijo y una forma sin prefijo que resuelve el header o el namespace por defecto:

Con prefijoPropósito
GET /:namespace/v0/livez, GET /:namespace/v0/healthProbes (ver la advertencia más abajo)
POST /:namespace/v0/cypherCypher
POST /:namespace/v0/admin/flush, /admin/compactMantenimiento
POST /:namespace/v0/admin/backup, /admin/restoreBackup y restore
GET /:namespace/v0/admin/restore-pointsLa ventana de puntos de restauración del namespace (no abre un namespace en frío)
GET /:namespace/v0/admin/queries, POST …/admin/queries/:id/cancelConsultas en curso, limitadas al namespace

GET /v0/version y GET /v0/metrics son de todo el proceso y no llevan prefijo.

Limitar tokens a namespaces

En un archivo de tokens, una lista namespaces restringe un token. Omítela para un token que llegue a todos los namespaces; una lista vacía ([]) los deniega todos.

{
"tokens": [
{ "name": "admin", "token": "…", "role": "read-write" },
{ "name": "acme-app", "token": "…", "role": "read-write", "namespaces": ["acme"] },
{ "name": "dashboard", "token": "…", "role": "read-only" }
]
}

El alcance se aplica en cada ruta HTTP y, en Bolt, en cada sentencia:

Ventana de terminal
curl -s localhost:8080/globex/v0/cypher -H "Authorization: Bearer $ACME_TOKEN" \
-H 'Content-Type: application/json' -d '{"query": "RETURN 1 AS x"}'
# 401 {"error":"missing or invalid bearer token, or token not scoped to this namespace"}

Por Bolt, la misma petición falla con Neo.ClientError.Security.Forbidden. Los JWT se limitan de la misma forma con --jwt-namespaces-claim. Detalles y recarga en caliente: Autenticación.

Nombres de namespace

Los nombres cumplen [a-z0-9][a-z0-9_-]{0,62}: letras minúsculas, dígitos, - y _, de 1 a 63 caracteres, sin empezar con _ ni -. Comprueba uno con namidb namespace-check <name>. Una petición con un nombre inválido se rechaza antes de abrir nada.

Capacidad y desalojo

AjustePor defectoSignificado
--max-namespaces100Namespaces abiertos a la vez. Al llegar al tope, los inactivos se desalojan del más antiguo al más reciente. 0 = ilimitado.
--namespace-idle-timeout1hCuánto tiempo debe estar sin uso un namespace antes de poder ser desalojado.
NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE0 (desactivado)Tope de lecturas por namespace dentro del control de lecturas de todo el proceso, para que un tenant no pueda tomar todos los slots.

El desalojo descarta la sesión en memoria, no los datos; la siguiente petición vuelve a abrir el namespace. Un namespace con una lectura en curso nunca está inactivo. Las cachés son de todo el proceso con un único presupuesto agregado, así que muchos tenants no multiplican el uso de memoria; consulta Memoria y cachés. Los namespaces se abren de forma independiente, así que una apertura en frío lenta (un WAL largo que reproducir) solo retrasa las peticiones de ese namespace.

Restaurar en un namespace nuevo

Un servidor multi-tenant puede restaurar un backup en un namespace que todavía no existe, a través de su propio store. Tanto el backup como el restore necesitan --backup-target-uri, que limita hacia dónde pueden copiar:

Ventana de terminal
namidb-server --multi-tenant --store "s3://graphs?region=us-east-1" \
--backup-target-uri "s3://graph-backups/namidb?region=us-east-1" …
# Online backup of acme:
curl -s -X POST localhost:8080/acme/v0/admin/backup \
-H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"to": "s3://graph-backups/namidb/acme-nightly?ns=acme&region=us-east-1"}'
# {"bytes_copied":649,"objects_copied":4,"source_version":1}
# Restore it as a new namespace acme-restored:
curl -s -X POST localhost:8080/acme-restored/v0/admin/restore \
-H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"from": "s3://graph-backups/namidb/acme-nightly?ns=acme&region=us-east-1", "verify": true}'
# {"bytes_copied":658,"objects_copied":4,"source_version":0}

Un restore rechaza (409) un destino que está abierto, abriéndose, ya en proceso de restauración o que ya tiene datos. Las reglas completas están en Backup y restore.

Un dueño por namespace

Un namespace tiene exactamente un writer, protegido por un epoch en su manifest. Cualquier proceso que lo abre para escritura reclama el siguiente epoch y bloquea (fencing) al anterior: un segundo servidor, una instancia vieja que se superpone con una nueva durante un despliegue gradual, o un cliente de Python embebido sobre el mismo bucket. Dos writers nunca suman throughput; se bloquean entre sí.

  • Enruta cada namespace a un solo servidor. Si ejecutas varios servidores sobre el mismo store, la capa que está delante debe enviar todo el tráfico de un namespace, incluidos los health probes, a su dueño.
  • Los probes abren namespaces. GET /:namespace/v0/health abre el namespace por el que pregunta, y el /v0/health sin prefijo abre el namespace del header o el namespace por defecto. Usa GET /v0/livez para la liveness del nodo; no abre nada.
  • --fence-policy. El valor por defecto steal hace que un writer bloqueado vuelva a abrir y recupere el namespace, lo que conviene a un único servidor. Cuando algo externo decide quién es el dueño, ejecuta todos los servidores con yield: un writer bloqueado deja entonces de escribir y se reporta como degradado (readiness 503) hasta que el proceso, o el namespace, se vuelva a abrir.

Alternativa: muchos tenants en un solo namespace

La alternativa es un único namespace con una propiedad tenant_id en cada nodo. Es más barato de operar, pero el aislamiento es solo lógico: cada consulta debe filtrar por tenant, y todos los tenants comparten un índice vectorial por (label, property), así que una búsqueda vectorial debe llevar el tenant en su filter (consulta Búsqueda). Trátalo como una comodidad, no como un límite de seguridad; usa el modo multi-tenant cuando los tenants no deban verse entre sí.