Skip to content

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:

  1. Master Node: Responsible for handling all write operations and some read operations
  2. Slave Nodes: Primarily responsible for handling read operations, improving overall system throughput

Cluster Architecture

Key Configuration for Cluster Deployment

The key to cluster deployment is that all nodes must:

  1. Share the same database: All nodes access the same MySQL database
  2. Share the same Redis: For caching and inter-node communication
  3. Use the same secrets: SESSION_SECRET and CRYPTO_SECRET must be identical on all nodes
  4. Configure node types correctly: Master node as master, slave nodes as slave

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:

docker compose up -d

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:

docker compose up -d

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:

  1. Prepare new servers: Install Docker and Docker Compose
  2. Configure slave nodes: Configure new slave nodes according to "Step 3: Configure Slave Nodes"
  3. Update load balancer configuration: Add new nodes to the load balancer configuration
  4. Test new nodes: Ensure new nodes work properly and participate in load balancing

Best Practices

  1. Regular database backups: Even in cluster environments, regularly backup the database
  2. Monitor resource usage: Closely monitor CPU, memory, and disk usage
  3. Adopt rolling update strategy: When updating, update slave nodes first, confirm stability before updating master node
  4. Configure alert system: Monitor node status and notify administrators promptly when issues occur
  5. 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