Guide de déploiement de clusters

Ce document fournit des étapes de configuration détaillées et les meilleures pratiques pour le déploiement du cluster 88API, vous aidant à créer un système distribué à haute disponibilité et à charge équilibrée.

Prérequis

• Plusieurs serveurs (au moins deux, architecture maître-esclave)
• Docker et Docker Compose installés
• Base de données MySQL partagée (les nœuds maître et esclave doivent accéder à la même base de données)
• Service Redis partagé (pour la synchronisation des données et la mise en cache entre les nœuds)
• Facultatif: équilibreur de charge (tel que Nginx, HAProxy ou le service d'équilibrage de charge d'un fournisseur de cloud)

Présentation de l'architecture du cluster

Le cluster 88API adopte une conception d'architecture maître-esclave:

1. Nœud maître: responsable de la gestion de toutes les opérations d'écriture et de certaines opérations de lecture
2. Nœuds esclaves: principalement responsables de la gestion des opérations de lecture, améliorant ainsi le débit global du système

Configuration de clé pour le déploiement de cluster

La clé du déploiement de cluster est que tous les nœuds doivent:

1. Partager la même base de données: tous les nœuds accèdent à la même base de données MySQL
2. Partagez le même Redis: pour la mise en cache et la communication entre les nœuds
3. Utilisez les mêmes secrets : SESSION_SECRET et CRYPTO_SECRET doivent être identiques sur tous les nœuds
4. Configurez correctement les types de nœuds: nœud maître comme master, nœuds esclaves comme slave

Étapes de déploiement

Étape 1: Préparer la base de données partagée et Redis

Tout d’abord, vous devez préparer la base de données MySQL partagée et les services Redis. Cela peut être :

• Services MySQL et Redis haute disponibilité déployés séparément
• Services de base de données et de cache gérés fournis par les fournisseurs de cloud
• MySQL et Redis fonctionnant sur des serveurs indépendants

Pour la base de données MySQL, vous pouvez choisir les solutions d'architecture suivantes:

Assurez-vous que ces services sont accessibles à tous les nœuds et qu’ils offrent des performances et une fiabilité suffisantes.

Étape 2: Configurer le nœud maître

Créez un fichier docker-compose.yml sur le serveur du nœud maître:

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

Démarrez le nœud maître:

docker compose up -d

Étape 3: Configurer les nœuds esclaves

Créez un fichier docker-compose.yml sur chaque serveur de nœud esclave:

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

Démarrez le nœud esclave:

docker compose up -d

Répétez cette étape pour chaque serveur de nœud esclave.

Étape 4: Configurer l'équilibrage de charge

Pour obtenir une répartition équilibrée du trafic, vous devez configurer un équilibreur de charge. Voici un exemple de configuration utilisant Nginx comme équilibreur de charge:

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;
    }
}

Cette configuration définit le poids du nœud maître sur 3 et le poids du nœud esclave sur 5, ce qui signifie que les nœuds esclaves traiteront plus de requêtes. Vous pouvez ajuster ces poids en fonction de vos besoins réels.

Options de configuration avancées

Paramètres de synchronisation des données

La synchronisation des données entre les nœuds du cluster dépend des variables d'environnement suivantes:

Configuration haute disponibilité Redis

Pour améliorer la disponibilité de Redis, vous pouvez configurer le cluster Redis ou le mode sentinelle:

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

Configuration de la sécurité des sessions

Assurez-vous que tous les nœuds du cluster utilisent les mêmes secrets de session et de chiffrement:

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

Surveillance et maintenance

Bilans de santé

Configurez des vérifications d'état régulières pour surveiller l'état du nœud:

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

Gestion des journaux

Pour les clusters à grande échelle, il est recommandé d'utiliser une gestion centralisée des journaux:

environment:
  - LOG_SQL_DSN=root:password@tcp(log-db-host:3306)/new_api_logs # Independent log database

Guide de mise à l'échelle

À mesure que votre entreprise se développe, vous devrez peut-être étendre l'échelle du cluster. Les étapes de mise à l'échelle sont les suivantes:

1. Préparer les nouveaux serveurs: installez Docker et Docker Compose
2. Configurer les nœuds esclaves: Configurez les nouveaux nœuds esclaves conformément à « Étape 3: Configurer les nœuds esclaves »
3. Mettre à jour la configuration de l'équilibreur de charge: ajoutez de nouveaux nœuds à la configuration de l'équilibreur de charge
4. Testez les nouveaux nœuds: assurez-vous que les nouveaux nœuds fonctionnent correctement et participent à l'équilibrage de charge

meilleures pratiques

1. Sauvegardes régulières de la base de données: même dans les environnements de cluster, sauvegardez régulièrement la base de données
2. Surveillez l'utilisation des ressources: surveillez de près l'utilisation du processeur, de la mémoire et du disque.
3. Adopter une stratégie de mise à jour continue: lors de la mise à jour, mettez d'abord à jour les nœuds esclaves, confirmez la stabilité avant de mettre à jour le nœud maître.
4. Configurer le système d'alerte: surveillez l'état du nœud et informez rapidement les administrateurs lorsque des problèmes surviennent
5. Déploiement de distribution géographique: si possible, déployez des nœuds dans différents emplacements géographiques pour améliorer la disponibilité

Dépannage

Les nœuds ne peuvent pas synchroniser les données

• Vérifiez si la connexion Redis est normale
• Confirmez que SESSION_SECRET et CRYPTO_SECRET sont identiques sur tous les nœuds
• Vérifiez que la configuration de la connexion à la base de données est correcte

Déséquilibre de charge

• Vérifier la configuration de l'équilibreur de charge et les paramètres de poids
• Surveiller l'utilisation des ressources de chaque nœud pour garantir qu'aucun nœud n'est surchargé
• Il faudra peut-être ajuster le poids des nœuds ou ajouter plus de nœuds

Problèmes de perte de session

• Assurez-vous que tous les nœuds utilisent le même SESSION_SECRET
• Vérifier que la configuration de Redis est correcte et accessible
• Vérifiez si les clients gèrent correctement les cookies

Documentation connexe

• Guide de configuration des variables d'environnement - Contient toutes les variables d'environnement pertinentes pour le déploiement multi-nœuds
• Guide de mise à jour du système - Stratégie de mise à jour du système dans un environnement multi-nœuds -Docker Compose Configuration Guide - Pour écrire des fichiers de configuration de nœud de cluster