🌐 Cluster Deployment Guide¶
This document provides detailed configuration steps and best practices for New API cluster deployment, helping you build a high-availability, load-balanced distributed system.
📋 Prerequisites¶
- Multiple servers (at least two, master-slave architecture)
- Docker and Docker Compose installed
- Shared MySQL database (master and slave nodes need to access the same database)
- Shared Redis service (for data synchronization and caching between nodes)
- Optional: Load balancer (such as Nginx, HAProxy, or cloud provider's load balancing service)
🏛️ Cluster Architecture Overview¶
New API cluster adopts a master-slave architecture design:
- Master Node: Responsible for handling all write operations and some read operations
- Slave Nodes: Primarily responsible for handling read operations, improving overall system throughput
🔑 Key Configuration for Cluster Deployment¶
The key to cluster deployment is that all nodes must:
- Share the same database: All nodes access the same MySQL database
- Share the same Redis: For caching and inter-node communication
- Use the same secrets:
SESSION_SECRET
andCRYPTO_SECRET
must be identical on all nodes - Configure node types correctly: Master node as
master
, slave nodes asslave
🛠️ Deployment Steps¶
Step 1: Prepare Shared Database and Redis¶
First, you need to prepare shared MySQL database and Redis services. This can be:
- High-availability MySQL and Redis services deployed separately
- Managed database and cache services provided by cloud providers
- MySQL and Redis running on independent servers
For MySQL database, you can choose the following architecture solutions:
Architecture Type | Component Composition | Working Method | Application Configuration Method |
---|---|---|---|
Master-Slave Replication | 1 master database N slave databases |
Master handles writes Slaves handle reads Automatic master-slave data sync |
Configure master database address as SQL_DSN |
Database Cluster | Multiple peer nodes Proxy layer (ProxySQL/MySQL Router) |
All nodes can read/write Load balancing through proxy layer Automatic failover |
Configure proxy layer address as SQL_DSN |
Important Note
Regardless of which architecture you choose, the application's SQL_DSN
configuration only needs one unified entry address.
Ensure these services can be accessed by all nodes and have sufficient performance and reliability.
Step 2: Configure Master Node¶
Create a docker-compose.yml
file on the master node server:
services:
new-api-master:
image: calciumion/new-api:latest
container_name: new-api-master
restart: always
ports:
- "3000:3000"
environment:
- SQL_DSN=root:password@tcp(your-db-host:3306)/new-api
- REDIS_CONN_STRING=redis://default:password@your-redis-host:6379
- SESSION_SECRET=your_unique_session_secret
- CRYPTO_SECRET=your_unique_crypto_secret
- TZ=Asia/Shanghai
# Optional configurations below
- SYNC_FREQUENCY=60 # Sync frequency in seconds
- FRONTEND_BASE_URL=https://your-domain.com # Frontend base URL for email notifications and other functions
volumes:
- ./data:/data
- ./logs:/app/logs
Security Tip
Please use strong passwords and randomly generated secret strings to replace the example values in the above configuration.
Start the master node:
Step 3: Configure Slave Nodes¶
Create a docker-compose.yml
file on each slave node server:
services:
new-api-slave:
image: calciumion/new-api:latest
container_name: new-api-slave
restart: always
ports:
- "3000:3000" # Can use the same port as master node since they're on different servers
environment:
- SQL_DSN=root:password@tcp(your-db-host:3306)/new-api # Same as master node
- REDIS_CONN_STRING=redis://default:password@your-redis-host:6379 # Same as master node
- SESSION_SECRET=your_unique_session_secret # Must be same as master node
- CRYPTO_SECRET=your_unique_crypto_secret # Must be same as master node
- NODE_TYPE=slave # Key configuration, specify as slave node
- SYNC_FREQUENCY=60 # Sync frequency between slave and master nodes, in seconds
- TZ=Asia/Shanghai
# Optional configurations below
- FRONTEND_BASE_URL=https://your-domain.com # Must be same as master node
volumes:
- ./data:/data
- ./logs:/app/logs
Start the slave node:
Repeat this step for each slave node server.
Step 4: Configure Load Balancing¶
To achieve balanced traffic distribution, you need to set up a load balancer. Here's an example configuration using Nginx as the load balancer:
upstream new_api_cluster {
server master-node-ip:3000 weight=3;
server slave-node1-ip:3000 weight=5;
server slave-node2-ip:3000 weight=5;
# Can add more slave nodes
}
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://new_api_cluster;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
This configuration sets the master node weight to 3 and slave node weights to 5, meaning slave nodes will handle more requests. You can adjust these weights based on your actual needs.
⚙️ Advanced Configuration Options¶
Data Synchronization Settings¶
Data synchronization between cluster nodes depends on the following environment variables:
Environment Variable | Description | Recommended Value |
---|---|---|
SYNC_FREQUENCY |
Node sync frequency (seconds) | 60 |
BATCH_UPDATE_ENABLED |
Enable batch updates | true |
BATCH_UPDATE_INTERVAL |
Batch update interval (seconds) | 5 |
Redis High Availability Configuration¶
To improve Redis availability, you can configure Redis cluster or sentinel mode:
environment:
- REDIS_CONN_STRING=redis://your-redis-host:6379
- REDIS_PASSWORD=your_redis_password
- REDIS_MASTER_NAME=mymaster # Master node name in sentinel mode
- REDIS_CONN_POOL_SIZE=10 # Redis connection pool size
Session Security Configuration¶
Ensure all nodes in the cluster use the same session and encryption secrets:
environment:
- SESSION_SECRET=your_unique_session_secret # Must be same on all nodes
- CRYPTO_SECRET=your_unique_crypto_secret # Must be same on all nodes
📈 Monitoring and Maintenance¶
Health Checks¶
Configure regular health checks to monitor node status:
healthcheck:
test: ["CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' | awk -F: '{print $$2}'"]
interval: 30s
timeout: 10s
retries: 3
Log Management¶
For large-scale clusters, it's recommended to use centralized log management:
environment:
- LOG_SQL_DSN=root:password@tcp(log-db-host:3306)/new_api_logs # Independent log database
🚀 Scaling Guide¶
As your business grows, you may need to expand the cluster scale. Scaling steps are as follows:
- Prepare new servers: Install Docker and Docker Compose
- Configure slave nodes: Configure new slave nodes according to "Step 3: Configure Slave Nodes"
- Update load balancer configuration: Add new nodes to the load balancer configuration
- Test new nodes: Ensure new nodes work properly and participate in load balancing
💡 Best Practices¶
- Regular database backups: Even in cluster environments, regularly backup the database
- Monitor resource usage: Closely monitor CPU, memory, and disk usage
- Adopt rolling update strategy: When updating, update slave nodes first, confirm stability before updating master node
- Configure alert system: Monitor node status and notify administrators promptly when issues occur
- Geographic distribution deployment: If possible, deploy nodes in different geographic locations to improve availability
❓ Troubleshooting¶
Nodes Cannot Sync Data¶
- Check if Redis connection is normal
- Confirm that SESSION_SECRET and CRYPTO_SECRET are identical on all nodes
- Verify database connection configuration is correct
Load Imbalance¶
- Check load balancer configuration and weight settings
- Monitor resource usage of each node to ensure no node is overloaded
- May need to adjust node weights or add more nodes
Session Loss Issues¶
- Ensure all nodes use the same SESSION_SECRET
- Verify Redis configuration is correct and accessible
- Check if clients handle cookies correctly
📚 Related Documentation¶
- Environment Variables Configuration Guide - Contains all relevant environment variables for multi-node deployment
- System Update Guide - System update strategy in multi-node environment
- Docker Compose Configuration Guide - For writing cluster node configuration files