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
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,
--storeno necesita?ns=; si está presente, se ignora con una advertencia. - Los namespaces viven directamente en la raíz del store:
file:///var/lib/namidbguarda el namespaceacmeen/var/lib/namidb/acme/. Paras3://,gs://yaz://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
| Protocolo | Cómo se elige el namespace |
|---|---|
| HTTP | El prefijo de la ruta: POST /acme/v0/cypher |
| HTTP | O el header X-NamiDB-Namespace: acme en la ruta /v0/... sin prefijo |
| HTTP | Ninguno de los dos: --default-namespace (por defecto default) |
| Bolt | La base de datos de la sesión del driver: driver.session(database="acme") |
| Bolt | Sin base de datos indicada: --default-namespace |
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 prefijo | Propósito |
|---|---|
GET /:namespace/v0/livez, GET /:namespace/v0/health | Probes (ver la advertencia más abajo) |
POST /:namespace/v0/cypher | Cypher |
POST /:namespace/v0/admin/flush, /admin/compact | Mantenimiento |
POST /:namespace/v0/admin/backup, /admin/restore | Backup y restore |
GET /:namespace/v0/admin/restore-points | La ventana de puntos de restauración del namespace (no abre un namespace en frío) |
GET /:namespace/v0/admin/queries, POST …/admin/queries/:id/cancel | Consultas 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:
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
| Ajuste | Por defecto | Significado |
|---|---|---|
--max-namespaces | 100 | Namespaces abiertos a la vez. Al llegar al tope, los inactivos se desalojan del más antiguo al más reciente. 0 = ilimitado. |
--namespace-idle-timeout | 1h | Cuánto tiempo debe estar sin uso un namespace antes de poder ser desalojado. |
NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE | 0 (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:
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®ion=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®ion=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/healthabre el namespace por el que pregunta, y el/v0/healthsin prefijo abre el namespace del header o el namespace por defecto. UsaGET /v0/livezpara la liveness del nodo; no abre nada. --fence-policy. El valor por defectostealhace 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 conyield: 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í.