Neo4j en un VPS: base de datos de grafos, Cypher y GraphRAG

Neo4j registra nodos — un cliente, un producto, un servidor — con etiquetas (:Person, :Product) y propiedades, conectados por relaciones dirigidas y con nombre (:KNOWS, :BOUGHT, :DEPENDS_ON). Una relación se almacena como un enlace directo entre dos nodos: seguirla no requiere buscar en un índice, por grande que sea la base.

Se consulta en Cypher, un lenguaje que dibuja el patrón buscado: (a:Person)-[:KNOWS]->(b:Person). Los caminos de longitud variable (-[:KNOWS*1..3]->), los caminos más cortos y las agregaciones caben en una línea, donde SQL apila uniones o consultas recursivas.

Un VPS Ubuntu 24.04 con 2 GB de RAM y 20 GB de disco, Docker y el plugin Compose instalados, nginx y Certbot en el host, y un subdominio que apunte al VPS, por ejemplo neo4j.example.com. Neo4j es más rápido cuando el grafo cabe en su caché de páginas: prevé más memoria para un grafo de decenas de millones de nodos.

Neo4j Browser necesita dos cosas: la interfaz HTTP y una conexión Bolt, que el navegador abre en WebSocket. nginx dirige ambas con el mismo nombre: las peticiones normales al 7474, las de WebSocket al 7687.

map $http_upgrade $neo4j_backend {
    default   127.0.0.1:7474;
    websocket 127.0.0.1:7687;
}
server {
    listen 80;
    server_name neo4j.example.com;
    location / {
        proxy_pass http://$neo4j_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

certbot --nginx -d neo4j.example.com

Abre después https://neo4j.example.com. En Neo4j Browser, escribe neo4j+s://neo4j.example.com:443 como Connect URL, el usuario neo4j y tu contraseña.

En Neo4j Browser, crea una restricción de unicidad, algunos nodos y sus relaciones, y luego sigue un camino de dos niveles como máximo. MERGE solo crea un nodo o una relación si todavía no existe: la consulta se puede repetir sin duplicados.

CREATE CONSTRAINT person_name IF NOT EXISTS FOR (p:Person) REQUIRE p.name IS UNIQUE;
MERGE (sara:Person {name: 'Sara'})
MERGE (yassine:Person {name: 'Yassine'})
MERGE (casa:City {name: 'Casablanca'})
MERGE (sara)-[:KNOWS]->(yassine)
MERGE (yassine)-[:LIVES_IN]->(casa);
MATCH (p:Person {name: 'Sara'})-[:KNOWS*1..2]->(f)-[:LIVES_IN]->(c:City)
RETURN f.name, c.name;

El Browser dibuja el resultado; el comando :guide abre sus tutoriales integrados, y :sysinfo muestra el tamaño de la base y el uso de la caché.

Desde cualquier lenguaje, la API HTTP recibe una consulta Cypher por POST y responde en JSON, con autenticación HTTP básica. Una aplicación instalada en el mismo VPS usa más bien un driver oficial en Bolt, en bolt://127.0.0.1:7687. Desde tu equipo de desarrollo, un túnel SSH hace accesible el mismo puerto sin abrirlo a Internet.

curl -s -u neo4j:$NEO4J_PASSWORD \
  -H 'Content-Type: application/json' \
  -d '{"statement": "MATCH (p:Person) RETURN p.name LIMIT 5"}' \
  https://neo4j.example.com/db/neo4j/query/v2

from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://127.0.0.1:7687", auth=("neo4j", "<mot-de-passe>"))
records, _, _ = driver.execute_query("MATCH (p:Person) RETURN p.name AS name")
print([r["name"] for r in records])

ssh -L 7687:127.0.0.1:7687 [email protected]

Usa el esquema bolt:// y no neo4j:// para una conexión local: el segundo pide la tabla de enrutamiento, que anuncia la dirección pública en el puerto 443.

Un RAG clásico recupera pasajes cercanos a la pregunta. Un GraphRAG añade las relaciones: las entidades extraídas de los documentos (personas, contratos, productos) se convierten en nodos, conectados entre sí y con los pasajes que las citan. Neo4j guarda ambos en la misma base, gracias a sus índices vectoriales.

CREATE VECTOR INDEX chunk_embedding IF NOT EXISTS
FOR (c:Chunk) ON c.embedding
OPTIONS {indexConfig: {`vector.dimensions`: 768, `vector.similarity_function`: 'cosine'}};

La búsqueda vectorial encuentra los pasajes pertinentes y luego una consulta Cypher sigue sus relaciones para reunir el contexto: el asistente responde con hechos conectados y la fuente de cada uno. Los embeddings pueden venir de un modelo local servido por Ollama en el mismo VPS.

En Community Edition, la copia se hace con la base detenida, con neo4j-admin database dump: unos segundos de interrupción para un grafo de tamaño medio. Prográmala por la noche.

cd /opt/neo4j
docker compose stop neo4j
docker compose run --rm -v /opt/neo4j/backups:/backups neo4j \
  neo4j-admin database dump neo4j --to-path=/backups --overwrite-destination=true
docker compose start neo4j

Copia después backups/neo4j.dump fuera del VPS. Para actualizar, cambia la versión de la imagen en docker-compose.yml y luego docker compose pull && docker compose up -d, justo después de una copia; lee las notas de la versión antes de cambiar de versión mayor.

Desde el Marketplace de tu área de cliente, Neo4j se instala en un VPS de ServOrbit sin escribir una línea: Neo4j Community Edition se despliega detrás de un pequeño proxy que sirve Neo4j Browser, la API HTTP y la conexión Bolt en un solo puerto, la contraseña del usuario neo4j se genera y aparece en tu área de cliente, y todo se publica en HTTPS en tu dominio o en el subdominio gratuito del VPS. El puerto Bolt sigue disponible en local, en bolt://127.0.0.1:7687, para tus aplicaciones.