🏦 refactor: Centralize Caching & Redis Key Prefixing (#8457)

* 🔧 Overhauled caching feature:
- Refactored caching logic.
- Fixed redis prefix, namespace, tls, ttl, and cluster.
- Added REDIS_KEY_PREFIX_VAR

* # refactor: Rename redisCache to standardCache

* # Add Redis pinging mechanism to maintain connection.

* # docs: Add warning about Keyv Redis client prefix support
This commit is contained in:
Theo N. Truong 2025-07-15 16:24:31 -06:00 committed by GitHub
parent 418b5e9070
commit 01b012a8fa
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
39 changed files with 1407 additions and 526 deletions

399
redis-config/README.md Normal file
View file

@ -0,0 +1,399 @@
# Redis Configuration and Setup
This directory contains comprehensive Redis configuration files and scripts for LibreChat development and testing, supporting both cluster and single-node setups with optional TLS encryption.
## Supported Configurations
### 1. Redis Cluster (3 Nodes)
- **3 Redis nodes** running on ports 7001, 7002, and 7003
- **No replicas** (each node is a master)
- **Automatic hash slot distribution** across all nodes
### 2. Single Redis with TLS Encryption
- **Single Redis instance** on port 6380 with TLS encryption
- **CA certificate validation** for secure connections
- **Self-signed certificates** with proper Subject Alternative Names
### 3. Standard Single Redis
- **Basic Redis instance** on port 6379 (default)
- **No encryption** - suitable for local development
All configurations are designed for **local development and testing**.
## Prerequisites
1. **Redis** must be installed on your system:
```bash
# macOS
brew install redis
# Ubuntu/Debian
sudo apt-get install redis-server
# CentOS/RHEL
sudo yum install redis
```
2. **Redis CLI** should be available (usually included with Redis)
## Quick Start
### Option 1: Redis Cluster (3 Nodes)
```bash
# Navigate to the redis-config directory
cd redis-config
# Start and initialize the cluster
./start-cluster.sh
```
### Option 2: Single Redis with TLS
```bash
# Start Redis with TLS encryption on port 6380
./start-redis-tls.sh
```
### Option 3: Standard Redis
```bash
# Use system Redis on default port 6379
redis-server
```
## Testing Your Setup
### Test Cluster
```bash
# Connect to the cluster
redis-cli -c -p 7001
# Test basic operations
SET test_key "Hello World"
GET test_key
```
### Test TLS Redis
```bash
# Test with CA certificate validation
redis-cli --tls --cacert certs/ca-cert.pem -p 6380 ping
```
### Test Standard Redis
```bash
# Connect to default Redis
redis-cli ping
```
## Stopping Services
### Stop Cluster
```bash
./stop-cluster.sh
```
### Stop TLS Redis
```bash
# Find and stop TLS Redis process
ps aux | grep "redis-server.*6380"
kill <PID>
```
## Configuration Files
- `redis-7001.conf` - Configuration for node 1 (port 7001)
- `redis-7002.conf` - Configuration for node 2 (port 7002)
- `redis-7003.conf` - Configuration for node 3 (port 7003)
## Scripts
- `start-cluster.sh` - Starts and initializes the Redis cluster
- `stop-cluster.sh` - Stops all Redis nodes and cleans up
- `start-redis-tls.sh` - Starts Redis with TLS encryption and CA certificate validation
- `redis-tls.conf` - TLS Redis configuration file
## Directory Structure
```
redis-config/
├── README.md
├── redis-7001.conf # Cluster node 1 configuration
├── redis-7002.conf # Cluster node 2 configuration
├── redis-7003.conf # Cluster node 3 configuration
├── redis-tls.conf # TLS Redis configuration
├── start-cluster.sh # Start cluster script
├── stop-cluster.sh # Stop cluster script
├── start-redis-tls.sh # Start TLS Redis script
├── certs/ # TLS certificates (created automatically)
│ ├── ca-cert.pem # Certificate Authority certificate
│ ├── ca-key.pem # CA private key
│ ├── server-cert.pem # Server certificate with SAN
│ ├── server-key.pem # Server private key
│ ├── redis.dh # Diffie-Hellman parameters
│ └── server.conf # OpenSSL certificate configuration
├── data/ # Data files (created automatically)
│ ├── 7001/ # Cluster node 1 data
│ ├── 7002/ # Cluster node 2 data
│ └── 7003/ # Cluster node 3 data
└── logs/ # Log directory (created automatically)
# Note: By default, Redis logs to stdout/stderr
# Log files would be created here if enabled in config
```
## Using with LibreChat
Update your `.env` file based on your chosen Redis configuration:
### For Redis Cluster
```bash
USE_REDIS=true
REDIS_URI=redis://127.0.0.1:7001,redis://127.0.0.1:7002,redis://127.0.0.1:7003
```
### For TLS Redis
```bash
USE_REDIS=true
REDIS_URI=rediss://127.0.0.1:6380
REDIS_CA=/path/to/LibreChat/redis-config/certs/ca-cert.pem
```
### For Standard Redis
```bash
USE_REDIS=true
REDIS_URI=redis://127.0.0.1:6379
```
### Optional Configuration
```bash
# Use environment variable for dynamic key prefixing
REDIS_KEY_PREFIX_VAR=K_REVISION
# Or set static prefix
REDIS_KEY_PREFIX=librechat
# Connection limits
REDIS_MAX_LISTENERS=40
```
## TLS/SSL Redis Setup
For secure Redis connections using TLS encryption with CA certificate validation:
### 1. Start Redis with TLS
```bash
# Start Redis with TLS on port 6380
./start-redis-tls.sh
```
### 2. Configure LibreChat for TLS
Update your `.env` file:
```bash
# .env file - TLS Redis with CA certificate validation
USE_REDIS=true
REDIS_URI=rediss://127.0.0.1:6380
REDIS_CA=/path/to/LibreChat/redis-config/certs/ca-cert.pem
```
### 3. Test TLS Connection
```bash
# Test Redis TLS connection with CA certificate
redis-cli --tls --cacert certs/ca-cert.pem -p 6380 ping
# Should return: PONG
# Test basic operations
redis-cli --tls --cacert certs/ca-cert.pem -p 6380 set test_tls "TLS Working"
redis-cli --tls --cacert certs/ca-cert.pem -p 6380 get test_tls
```
### 4. Test Backend Integration
```bash
# Start LibreChat backend
npm run backend
# Look for these success indicators in logs:
# ✅ "No changes needed for 'USER' role permissions"
# ✅ "No changes needed for 'ADMIN' role permissions"
# ✅ "Server listening at http://localhost:3080"
# ✅ No "IoRedis connection error" messages
```
### TLS Certificate Details
The TLS setup includes:
- **CA Certificate**: Self-signed Certificate Authority for validation
- **Server Certificate**: Contains Subject Alternative Names (SAN) for:
- `DNS: localhost`
- `IP: 127.0.0.1`
- **TLS Configuration**:
- TLS v1.2 and v1.3 support
- No client certificate authentication required
- Strong cipher suites (AES-256-GCM, ChaCha20-Poly1305)
### Troubleshooting TLS
#### Certificate Validation Errors
```bash
# If you see "Hostname/IP does not match certificate's altnames"
# Check certificate SAN entries:
openssl x509 -in certs/server-cert.pem -text -noout | grep -A3 "Subject Alternative Name"
# Should show: DNS:localhost, IP Address:127.0.0.1
```
#### Connection Refused
```bash
# Check if Redis TLS is running
lsof -i :6380
# Check Redis TLS server logs
ps aux | grep redis-server
```
#### Backend Connection Issues
```bash
# Verify CA certificate path in .env
ls -la /path/to/LibreChat/redis-config/certs/ca-cert.pem
# Test LibreChat Redis configuration
cd /path/to/LibreChat
npm run backend
# Look for Redis connection errors in output
```
## Common Operations
### Check Cluster Status
```bash
# Cluster information
redis-cli -p 7001 cluster info
# Node information
redis-cli -p 7001 cluster nodes
# Check specific node
redis-cli -p 7002 info replication
```
### Monitor Cluster
```bash
# Monitor all operations
redis-cli -p 7001 monitor
# Check memory usage
redis-cli -p 7001 info memory
redis-cli -p 7002 info memory
redis-cli -p 7003 info memory
```
### Troubleshooting
#### Cluster Won't Start
1. Check if Redis is installed: `redis-server --version`
2. Check for port conflicts: `netstat -tlnp | grep :700`
3. Check Redis processes: `ps aux | grep redis-server`
4. Check if nodes are responding: `redis-cli -p 7001 ping`
#### Cluster Initialization Fails
1. Ensure all nodes are running: `./start-cluster.sh`
2. Check cluster configuration: `redis-cli -p 7001 cluster nodes`
3. Reset if needed: `redis-cli -p 7001 CLUSTER RESET`
#### Performance Issues
1. Monitor memory usage: `redis-cli -p 7001 info memory`
2. Check slow queries: `redis-cli -p 7001 slowlog get 10`
3. Adjust `maxmemory` settings in configuration files
## Configuration Details
### Node Configuration
Each node is configured with:
- **Memory limit**: 256MB with LRU eviction
- **Persistence**: AOF + RDB snapshots
- **Clustering**: Enabled with 15-second timeout
- **Logging**: Notice level (logs to stdout/stderr by default)
### Hash Slot Distribution
With 3 nodes and no replicas:
- Node 1 (7001): Hash slots 0-5460
- Node 2 (7002): Hash slots 5461-10922
- Node 3 (7003): Hash slots 10923-16383
## Security Note
### Development Setup
The basic Redis cluster setup is designed for **local development only**.
### TLS Setup
The TLS Redis configuration provides:
- ✅ **TLS encryption** with CA certificate validation
- ✅ **Server certificate** with proper Subject Alternative Names
- ✅ **Strong cipher suites** (AES-256-GCM, ChaCha20-Poly1305)
- ✅ **Certificate validation** via self-signed CA
### Production Considerations
For production use, consider:
- Authentication (`requirepass` or `AUTH` commands)
- Client certificate authentication (`tls-auth-clients yes`)
- Firewall configuration
- Replica nodes for high availability
- Proper certificate management (not self-signed)
- Key rotation policies
## Backup and Recovery
### Backup
```bash
# Backup all nodes
mkdir -p backup
redis-cli -p 7001 BGSAVE
redis-cli -p 7002 BGSAVE
redis-cli -p 7003 BGSAVE
# Copy backup files
cp data/7001/dump.rdb backup/dump-7001.rdb
cp data/7002/dump.rdb backup/dump-7002.rdb
cp data/7003/dump.rdb backup/dump-7003.rdb
```
### Recovery
```bash
# Stop cluster
./stop-cluster.sh
# Restore backup files
cp backup/dump-7001.rdb data/7001/dump.rdb
cp backup/dump-7002.rdb data/7002/dump.rdb
cp backup/dump-7003.rdb data/7003/dump.rdb
# Start cluster
./start-cluster.sh
```
## Support
For Redis-specific issues:
- [Redis Documentation](https://redis.io/docs/)
- [Redis Cluster Tutorial](https://redis.io/docs/manual/scaling/)
For LibreChat integration:
- [LibreChat Documentation](https://github.com/danny-avila/LibreChat)

View file

@ -0,0 +1 @@
54E48A77C8FF4781A554C80BF6EFC0401A6ACE8A

BIN
redis-config/certs/dump.rdb Normal file

Binary file not shown.

View file

@ -0,0 +1,8 @@
-----BEGIN DH PARAMETERS-----
MIIBDAKCAQEAmPCtZIwB9l9LqyFewdGKxxk3HEcQdHswM3IHbhE+GqZOaD8KwxB+
rfPH54pDSW42WLWM+y7/eC2ufPdw6ZDBjCYFC8rGkWUPwguDl90INuzCCCAgwBVw
tpKfcZ92T8ek1qR6UgZa4zPq4FjQm09ZcVmMzaUeIkiRGv0/t2GjswZDVuLhKRp5
eSH7pByYCNYj3X9HyMqcCDfGhTkg8azcWJiEOCTCpsYgXcW1tz2PQsaJZpERnffk
px8mLuDPMVxTRWpXcIBmzs/Nwv8bGigyI4ADocM3jmQ8c6b9ZYUmyvled/1LEBzC
10g2R67op+dGOxk40lwrLmN6bzYFt/YKbwIBAgICAOE=
-----END DH PARAMETERS-----

View file

@ -0,0 +1,16 @@
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no
[req_distinguished_name]
CN = localhost
[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = localhost
IP.1 = 127.0.0.1

View file

@ -0,0 +1,27 @@
# Redis Cluster Node 1 Configuration
port 7001
cluster-enabled yes
cluster-config-file nodes-7001.conf
cluster-node-timeout 15000
appendonly yes
appendfilename "appendonly-7001.aof"
# Data directory
dir ./data/7001
# Logging
# logfile ./logs/redis-7001.log
loglevel notice
# Network
bind 127.0.0.1
protected-mode no
# Memory management
maxmemory 256mb
maxmemory-policy allkeys-lru
# Persistence
save 900 1
save 300 10
save 60 10000

View file

@ -0,0 +1,27 @@
# Redis Cluster Node 2 Configuration
port 7002
cluster-enabled yes
cluster-config-file nodes-7002.conf
cluster-node-timeout 15000
appendonly yes
appendfilename "appendonly-7002.aof"
# Data directory
dir ./data/7002
# Logging
# logfile ./logs/redis-7002.log
loglevel notice
# Network
bind 127.0.0.1
protected-mode no
# Memory management
maxmemory 256mb
maxmemory-policy allkeys-lru
# Persistence
save 900 1
save 300 10
save 60 10000

View file

@ -0,0 +1,27 @@
# Redis Cluster Node 3 Configuration
port 7003
cluster-enabled yes
cluster-config-file nodes-7003.conf
cluster-node-timeout 15000
appendonly yes
appendfilename "appendonly-7003.aof"
# Data directory
dir ./data/7003
# Logging
# logfile ./logs/redis-7003.log
loglevel notice
# Network
bind 127.0.0.1
protected-mode no
# Memory management
maxmemory 256mb
maxmemory-policy allkeys-lru
# Persistence
save 900 1
save 300 10
save 60 10000

View file

@ -0,0 +1,31 @@
port 0
tls-port 6380
tls-cert-file /Users/theotr/WebstormProjects/LibreChat/redis-cluster/certs/server-cert.pem
tls-key-file /Users/theotr/WebstormProjects/LibreChat/redis-cluster/certs/server-key.pem
tls-ca-cert-file /Users/theotr/WebstormProjects/LibreChat/redis-cluster/certs/ca-cert.pem
tls-auth-clients no
tls-dh-params-file /Users/theotr/WebstormProjects/LibreChat/redis-cluster/certs/redis.dh
tls-protocols "TLSv1.2 TLSv1.3"
tls-ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
tls-prefer-server-ciphers yes
tls-session-caching no
tls-session-cache-size 5000
tls-session-cache-timeout 60
bind 127.0.0.1
protected-mode yes
timeout 0
tcp-keepalive 300
daemonize no
pidfile /var/run/redis_6379.pid
loglevel notice
logfile ""
databases 16
always-show-logo no
save 900 1
save 300 10
save 60 10000
stop-writes-on-bgsave-error yes
rdbcompression yes
rdbchecksum yes
dbfilename dump.rdb
dir ./

84
redis-config/start-cluster.sh Executable file
View file

@ -0,0 +1,84 @@
#!/bin/bash
# Redis Cluster Startup Script
# This script starts and initializes a 3-node Redis cluster with no replicas
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$SCRIPT_DIR"
echo "🚀 Starting Redis Cluster..."
# Create necessary directories
mkdir -p data/7001 data/7002 data/7003
mkdir -p logs
# Check if Redis is installed
if ! command -v redis-server &> /dev/null; then
echo "❌ Redis is not installed. Please install Redis first:"
echo " macOS: brew install redis"
echo " Ubuntu: sudo apt-get install redis-server"
echo " CentOS: sudo yum install redis"
exit 1
fi
# Check if Redis CLI is available
if ! command -v redis-cli &> /dev/null; then
echo "❌ Redis CLI is not available. Please install Redis CLI."
exit 1
fi
# Start Redis instances
redis-server redis-7001.conf --daemonize yes
redis-server redis-7002.conf --daemonize yes
redis-server redis-7003.conf --daemonize yes
# Wait for nodes to start
sleep 3
# Check if all nodes are running
NODES_RUNNING=0
for port in 7001 7002 7003; do
if redis-cli -p $port ping &> /dev/null; then
NODES_RUNNING=$((NODES_RUNNING + 1))
else
echo "❌ Node on port $port failed to start"
fi
done
if [ $NODES_RUNNING -ne 3 ]; then
echo "❌ Not all Redis nodes started successfully."
exit 1
fi
echo "✅ All Redis nodes started"
# Check if cluster is already initialized
if redis-cli -p 7001 cluster info 2>/dev/null | grep -q "cluster_state:ok"; then
echo "✅ Cluster already initialized"
echo ""
echo "📋 Usage:"
echo " Connect: redis-cli -c -p 7001"
echo " Stop: ./stop-cluster.sh"
exit 0
fi
# Initialize the cluster
echo "🔧 Initializing cluster..."
echo "yes" | redis-cli --cluster create 127.0.0.1:7001 127.0.0.1:7002 127.0.0.1:7003 --cluster-replicas 0 > /dev/null
# Wait for cluster to stabilize
sleep 3
# Verify cluster status
if redis-cli -p 7001 cluster info | grep -q "cluster_state:ok"; then
echo "✅ Redis cluster ready!"
echo ""
echo "📋 Usage:"
echo " Connect: redis-cli -c -p 7001"
echo " Stop: ./stop-cluster.sh"
else
echo "❌ Cluster initialization failed!"
exit 1
fi

13
redis-config/start-redis-tls.sh Executable file
View file

@ -0,0 +1,13 @@
#!/bin/bash
# Start Redis with TLS configuration
echo "Starting Redis with TLS on port 6379..."
# Check if Redis is already running
if pgrep -f "redis-server.*tls" > /dev/null; then
echo "Redis with TLS is already running"
exit 1
fi
# Start Redis with TLS config
redis-server /Users/theotr/WebstormProjects/LibreChat/redis-cluster/redis-tls.conf

69
redis-config/stop-cluster.sh Executable file
View file

@ -0,0 +1,69 @@
#!/bin/bash
# Redis Cluster Shutdown Script
# This script stops all Redis cluster nodes
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$SCRIPT_DIR"
echo "🛑 Stopping Redis Cluster..."
# Function to stop a Redis node
stop_node() {
local port=$1
if redis-cli -p $port ping &> /dev/null; then
# Try graceful shutdown first
redis-cli -p $port SHUTDOWN NOSAVE 2>/dev/null || true
sleep 2
# Check if still running and force kill if needed
if redis-cli -p $port ping &> /dev/null; then
PID=$(ps aux | grep "[r]edis-server.*:$port" | awk '{print $2}')
if [ -n "$PID" ]; then
kill -TERM $PID 2>/dev/null || true
sleep 2
if kill -0 $PID 2>/dev/null; then
kill -KILL $PID 2>/dev/null || true
fi
fi
fi
# Final check
if redis-cli -p $port ping &> /dev/null; then
echo "❌ Failed to stop Redis node on port $port"
return 1
else
return 0
fi
else
return 0
fi
}
# Stop all nodes
NODES_STOPPED=0
for port in 7001 7002 7003; do
if stop_node $port; then
NODES_STOPPED=$((NODES_STOPPED + 1))
fi
done
# Clean up cluster configuration files
rm -f nodes-7001.conf nodes-7002.conf nodes-7003.conf
if [ $NODES_STOPPED -eq 3 ]; then
echo "✅ Redis cluster stopped"
else
echo "⚠️ Some nodes may not have stopped properly"
echo "Check running processes: ps aux | grep redis-server"
fi
# Check for remaining processes
REMAINING_PROCESSES=$(ps aux | grep "[r]edis-server" | grep -E ":(7001|7002|7003)" | wc -l)
if [ $REMAINING_PROCESSES -gt 0 ]; then
echo "⚠️ Found $REMAINING_PROCESSES remaining Redis processes"
echo "Kill with: pkill -f 'redis-server.*:700[1-3]'"
fi