KeyDB es un fork de Redis que procesa las peticiones con varios hilos en lugar de uno solo, y mantiene la compatibilidad con el protocolo, los comandos y las librerías cliente de Redis. En este tutorial desplegarás KeyDB en Ubuntu 24.04 con Docker Compose, lo configurarás con contraseña, persistencia y varios hilos, medirás su rendimiento y verás cómo migrar los datos de una instancia de Redis.

Requisitos previos

  • Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 2 vCPU y 2 GB de RAM. KeyDB solo aporta ventaja sobre Redis cuando hay varios núcleos disponibles.
  • Un usuario no root con privilegios sudo.
  • Docker Engine y el plugin Docker Compose instalados. Si aún no los tienes, sigue la guía de instalación de Docker en Ubuntu 24.04.

Se usa la imagen oficial eqalpha/keydb porque el repositorio APT de KeyDB no publica paquetes para Ubuntu 24.04.

Paso 1: Preparar el sistema

KeyDB, como Redis, recomienda permitir el overcommit de memoria para que los guardados en segundo plano (BGSAVE) no fallen cuando el servidor está cerca de su límite de RAM. Crea un archivo de sysctl:

echo 'vm.overcommit_memory = 1' | sudo tee /etc/sysctl.d/90-keydb.conf
sudo sysctl --system | grep overcommit

vm.overcommit_memory = 1

Crea el directorio del proyecto, donde irán la configuración y el archivo de Compose:

sudo mkdir -p /opt/keydb

Paso 2: Escribir la configuración de KeyDB

KeyDB usa la misma sintaxis que redis.conf, con algunas opciones propias. Genera una contraseña larga y aleatoria y guárdala en un lugar seguro:

openssl rand -base64 32

Crea el archivo de configuración:

sudo nano /opt/keydb/keydb.conf

Pega el siguiente contenido y sustituye your_strong_password por la contraseña que acabas de generar:

# Red: dentro del contenedor se escucha en todas las interfaces;
# la exposición real la controla Docker en el paso 3
bind 0.0.0.0
port 6379
protected-mode yes
requirepass your_strong_password

# Hilos que atienden peticiones (opción propia de KeyDB)
server-threads 2

# Persistencia: snapshots RDB y registro AOF
dir /data
save 900 1
save 300 10
save 60 10000
appendonly yes
appendfsync everysec

# Límite de memoria y política de expulsión
maxmemory 1gb
maxmemory-policy allkeys-lru

loglevel notice

Sobre las opciones clave:

  • server-threads es el número de hilos que procesan comandos. Empieza con el número de núcleos menos uno (compruébalo con nproc) y no superes el total de núcleos.
  • maxmemory debe dejar margen para el sistema y para la copia que hace KeyDB al guardar. Un valor razonable es la mitad de la RAM si el servidor solo se dedica a KeyDB.
  • allkeys-lru expulsa las claves menos usadas al llegar al límite, lo adecuado para una caché. Si guardas datos que no pueden perderse, usa noeviction.

Como el archivo contiene la contraseña, impide que otros usuarios del servidor entren en el directorio. El archivo debe seguir siendo legible (permisos 644) para que el proceso de KeyDB dentro del contenedor pueda leerlo:

sudo chmod 750 /opt/keydb

Paso 3: Crear el servicio con Docker Compose

Crea el archivo de Compose:

sudo nano /opt/keydb/compose.yaml

services:
  keydb:
    image: eqalpha/keydb:latest
    container_name: keydb
    command: keydb-server /etc/keydb/keydb.conf
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - ./keydb.conf:/etc/keydb/keydb.conf:ro
      - keydb_data:/data
    restart: unless-stopped

volumes:
  keydb_data:

El puerto se publica solo en 127.0.0.1, de modo que únicamente las aplicaciones del propio servidor pueden conectarse. Docker modifica iptables por su cuenta y un puerto publicado en 0.0.0.0 quedaría expuesto aunque UFW lo bloquee.

Arranca el contenedor:

sudo docker compose -f /opt/keydb/compose.yaml up -d
sudo docker compose -f /opt/keydb/compose.yaml ps

NAME      IMAGE                  COMMAND                  SERVICE   STATUS          PORTS
keydb     eqalpha/keydb:latest   "docker-entrypoint.s…"   keydb     Up 5 seconds    127.0.0.1:6379->6379/tcp

Comprueba en los logs que ha cargado la configuración sin errores:

sudo docker compose -f /opt/keydb/compose.yaml logs keydb | tail -n 5

keydb  | ... Server initialized
keydb  | ... Ready to accept connections

Paso 4: Verificar la conexión y la compatibilidad con Redis

La imagen incluye el cliente keydb-cli, equivalente a redis-cli. Lanza un PING autenticado:

sudo docker exec keydb keydb-cli -a 'your_strong_password' --no-auth-warning ping

PONG

Abre una sesión interactiva para probar algunos tipos de datos:

sudo docker exec -it keydb keydb-cli

Dentro del cliente, autentícate y ejecuta comandos de Redis habituales:

AUTH your_strong_password
SET sesion:42 "datos" EX 3600
TTL sesion:42
HSET producto:1 nombre "VPS" precio 12
HGETALL producto:1
CONFIG GET server-threads

La última orden debe devolver el número de hilos que configuraste. Sal con exit.

Cualquier librería cliente de Redis (redis-py, ioredis, Jedis, go-redis, StackExchange.Redis) funciona sin cambios: basta con apuntarla a 127.0.0.1:6379 con la contraseña configurada.

Paso 5: Medir el rendimiento

Instala redis-tools en el host para disponer de redis-benchmark:

sudo apt install redis-tools

Lanza una prueba con 50 conexiones concurrentes y pipelining:

redis-benchmark -h 127.0.0.1 -p 6379 -a 'your_strong_password' -t set,get -n 200000 -c 50 -P 16 -q

SET: 612345.00 requests per second, p50=1.103 msec
GET: 798403.19 requests per second, p50=0.871 msec

Las cifras dependen del número de núcleos. Para ver el efecto de los hilos, cambia server-threads en keydb.conf, reinicia con sudo docker compose -f /opt/keydb/compose.yaml restart y repite la prueba. Si aumentar hilos no mejora el resultado, el cuello de botella está en otra parte (red, CPU compartida o el propio benchmark) y conviene volver al valor anterior.

Paso 6 (opcional): Replicación activa entre dos nodos

La función más distintiva de KeyDB es la replicación activa: dos nodos que son a la vez maestro y réplica el uno del otro, de modo que ambos aceptan escrituras. Los conflictos se resuelven con la escritura más reciente.

Para este paso necesitas dos servidores conectados por una red privada, con IP 10.0.0.11 y 10.0.0.12 en el ejemplo. En cada nodo, publica el puerto en su IP privada en lugar de 127.0.0.1 editando compose.yaml:

    ports:
      - "10.0.0.11:6379:6379"

Añade al final de keydb.conf del nodo 10.0.0.11:

active-replica yes
replicaof 10.0.0.12 6379
masterauth your_strong_password

Y en el nodo 10.0.0.12, lo mismo apuntando al primero:

active-replica yes
replicaof 10.0.0.11 6379
masterauth your_strong_password

Ambos nodos deben usar la misma contraseña. Aplica los cambios con sudo docker compose -f /opt/keydb/compose.yaml up -d --force-recreate en cada nodo y comprueba el estado:

sudo docker exec keydb keydb-cli -a 'your_strong_password' --no-auth-warning info replication | grep -E 'role|master_link_status'

role:active-replica
master_link_status:up

Escribe una clave en un nodo y léela en el otro para confirmar que la réplica funciona en ambos sentidos.

Paso 7: Migrar datos desde Redis

La forma más sencilla de migrar sin parar la aplicación es convertir KeyDB temporalmente en réplica del Redis actual. Ejecuta en KeyDB, sustituyendo la IP y la contraseña del Redis de origen:

sudo docker exec keydb keydb-cli -a 'your_strong_password' --no-auth-warning config set masterauth 'redis_password'
sudo docker exec keydb keydb-cli -a 'your_strong_password' --no-auth-warning replicaof redis_server_ip 6379

Espera a que la sincronización termine, cuando master_link_status pase a up:

sudo docker exec keydb keydb-cli -a 'your_strong_password' --no-auth-warning info replication | grep master_link_status

Compara el número de claves en ambos servidores con DBSIZE. Cuando coincidan, cambia la aplicación para que apunte a KeyDB y desconecta la réplica:

sudo docker exec keydb keydb-cli -a 'your_strong_password' --no-auth-warning replicaof no one

Solución de problemas

El contenedor se reinicia en bucle. Casi siempre es un error en keydb.conf. Revisa sudo docker compose -f /opt/keydb/compose.yaml logs keydb: KeyDB indica la línea y la directiva que no reconoce.

NOAUTH Authentication required. El cliente no envía la contraseña. Revisa la cadena de conexión de la aplicación, por ejemplo redis://:[email protected]:6379/0.

OOM command not allowed when used memory > 'maxmemory'. Has llegado al límite con noeviction, o las claves no se pueden expulsar. Aumenta maxmemory o cambia la política a allkeys-lru si los datos son de caché.

Aviso de overcommit_memory en los logs. El ajuste del paso 1 no se aplicó. Comprueba el valor con sysctl vm.overcommit_memory y reinicia el contenedor.

Conclusión

Tienes KeyDB funcionando en Ubuntu 24.04 con persistencia, contraseña y varios hilos, accesible solo desde el propio servidor. Como siguientes pasos puedes programar copias del volumen keydb_data (contiene dump.rdb y el AOF), exportar métricas con un exportador compatible con Redis o montar la replicación activa sobre una red privada para tener dos nodos con escritura.