集群部署

本文档提供了 New API 集群部署的详细配置步骤和最佳实践，帮助您构建高可用、负载均衡的分布式系统。

前置要求

多台服务器（至少两台，一主多从架构）
已安装 Docker 和 Docker Compose
共享的 PostgreSQL 数据库（推荐，所有应用节点需访问同一数据库）
可选的 Redis 服务（可由所有节点共享，也可由各节点独立使用）
可选：负载均衡器（如 Nginx、HAProxy 或云服务商提供的负载均衡服务）

集群架构概述

New API 集群采用主从架构设计：

主节点：负责处理所有写操作和部分读操作
从节点：主要负责处理读操作，提高系统整体吞吐量

集群架构

上图仅展示共享 Redis 的拓扑示例；每节点独立 Redis 和无 Redis 模式同样受支持，具体语义见下文。

集群部署关键配置

集群部署的关键在于所有节点必须：

共享相同的数据库：所有节点访问同一 PostgreSQL 数据库
选择 Redis 拓扑：所有节点共享 Redis、各节点使用独立 Redis，或不使用 Redis
使用相同的会话密钥：SESSION_SECRET 必须在所有节点上相同；共享 Redis 的节点还必须使用相同的 CRYPTO_SECRET
正确配置节点类型：主节点为 master，从节点为 slave

部署步骤

步骤一：准备共享数据库并选择 Redis 拓扑

首先，您必须准备所有应用节点共同访问的 PostgreSQL 数据库。优先推荐：

云服务商提供的托管 PostgreSQL 服务
单独部署的高可用 PostgreSQL 服务
独立服务器上运行的 PostgreSQL

对于 PostgreSQL，常见的生产架构如下：

架构类型	组件构成	工作方式	应用配置方式
主备复制	1 个主库 N 个备用库	主库处理读写备用库持续复制并可用于故障切换	配置主库地址作为 `SQL_DSN`
高可用集群	PostgreSQL 节点托管入口或 Patroni + HAProxy	入口将连接路由到当前主库支持自动故障转移	配置统一可写入口作为 `SQL_DSN`

重要提示

无论选择哪种架构，SQL_DSN 都应指向同一个稳定、可写的 PostgreSQL 入口。MySQL 仍受支持，但不再作为集群部署的首选示例。

确保这些服务能够被所有节点访问，并具有足够的性能和可靠性。

Redis 不是共享数据库的替代品，可按部署需求选择：

Redis 拓扑	Session 状态传播	限流语义
所有节点共享 Redis	撤销和版本发布正常情况下即时生效	Redis 限流额度在节点间共享
每个节点使用独立 Redis	最迟在有效 `SYNC_FREQUENCY` 后回源共享数据库并收敛；版本轮换期间，新 Access JWT 可能短暂收到 401	每个节点独立计数，集群总额度最坏约为单节点阈值乘节点数
不使用 Redis	Session 校验直接查询共享数据库	使用各节点的内存限流

数据库中的 user_sessions 表在所有拓扑下都是 Session 状态的唯一权威来源，Session 活跃上限和签发窗口计数始终在所有节点间共享。Redis 中 Session Hash 的 TTL 取 Session 剩余寿命与有效 SYNC_FREQUENCY 的较小值，读取不会续期。延迟完成的 active 缓存回写只使用数据库读取时观察窗口的剩余部分，不会在撤销 tombstone 过期后重新获得完整 TTL。

SYNC_FREQUENCY 默认为 60 秒；值越大，独立 Redis 的陈旧窗口越长，值越小，每个活跃 Session 在每个节点上的数据库主键查询越频繁。

步骤二：配置主节点

在主节点服务器上创建 docker-compose.yml 文件：

services:
  new-api-master:
    image: calciumion/new-api:latest
    container_name: new-api-master
    restart: always
    ports:
      - '3000:3000'
    environment:
      - SQL_DSN=postgresql://newapi:password@your-db-host:5432/new-api
      - REDIS_CONN_STRING=redis://default:password@your-redis-host:6379 # 可改为本节点 Redis，或删除以禁用 Redis
      - SESSION_SECRET=your_unique_session_secret
      - CRYPTO_SECRET=your_unique_crypto_secret
      - TZ=Asia/Shanghai
      # 以下是可选配置
      - SYNC_FREQUENCY=60 # 同步频率，单位秒
      # - FRONTEND_BASE_URL=https://<your-newapi-domain> # 前端基础 URL，用于邮件通知等功能
    volumes:
      - ./data:/data
      - ./logs:/app/logs

安全提示

请使用强密码和随机生成的密钥字符串替换上述配置中的示例值。

启动主节点：

docker compose up -d

步骤三：配置从节点

在每个从节点服务器上创建 docker-compose.yml 文件：

services:
  new-api-slave:
    image: calciumion/new-api:latest
    container_name: new-api-slave
    restart: always
    ports:
      - '3000:3000' # 可以与主节点使用相同端口，因为它们在不同服务器上
    environment:
      - SQL_DSN=postgresql://newapi:password@your-db-host:5432/new-api # 与主节点相同
      - REDIS_CONN_STRING=redis://default:password@your-node-redis-host:6379 # 可与主节点相同、使用本节点 Redis，或删除以禁用 Redis
      - SESSION_SECRET=your_unique_session_secret # 必须与主节点相同
      - CRYPTO_SECRET=your_unique_crypto_secret # 共享 Redis 时必须与主节点相同
      - NODE_TYPE=slave # 关键配置，指定为从节点
      - SYNC_FREQUENCY=60 # 缓存同步频率，单位秒
      - TZ=Asia/Shanghai
      # 以下是可选配置
      # - FRONTEND_BASE_URL=https://<your-newapi-domain> # 需与主节点相同
    volumes:
      - ./data:/data
      - ./logs:/app/logs

启动从节点：

docker compose up -d

对每台从节点服务器重复此步骤。

上例展示每节点独立 Redis。共享 Redis 时让所有节点使用相同的 REDIS_CONN_STRING；不使用 Redis 时删除该环境变量。无论选择哪种拓扑，SQL_DSN 都必须指向同一个数据库，SESSION_SECRET 都必须在所有节点保持一致。

步骤四：配置负载均衡

为了实现流量的均衡分配，您需要设置负载均衡器。以下是使用 Nginx 作为负载均衡器的配置示例：

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;
    # 可添加更多从节点
}

server {
    listen 80;
    server_name <your-newapi-domain>;

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

此配置将主节点权重设置为 3，从节点权重设置为 5，这意味着从节点将处理更多的请求。您可以根据实际需求调整这些权重。

高级配置选项

缓存同步设置

数据库是 Session 的唯一权威来源。以下变量控制缓存更新频率及独立 Redis 部署下的最大 Session 陈旧窗口：

环境变量	说明	推荐值
`SYNC_FREQUENCY`	缓存同步频率和 Session 最大陈旧窗口（秒）	`60`
`BATCH_UPDATE_ENABLED`	启用批量更新	`true`
`BATCH_UPDATE_INTERVAL`	批量更新间隔（秒）	`5`

Redis 连接与高可用

New API 通过 REDIS_CONN_STRING 连接单一的 Redis 兼容端点，密码应直接包含在连接 URI 中；连接池大小使用 REDIS_POOL_SIZE。应用不原生解析 Redis Cluster 或 Sentinel 节点列表。如需 Redis 高可用，请使用能提供单一兼容端点的托管服务或代理：

environment:
  - REDIS_CONN_STRING=redis://your-redis-host:6379
  - REDIS_POOL_SIZE=10

会话安全配置

所有节点必须使用相同的 SESSION_SECRET。只有连接同一个 Redis 的节点才必须使用相同的有效 CRYPTO_SECRET：

environment:
  - SESSION_SECRET=your_unique_session_secret # 所有节点必须相同
  - CRYPTO_SECRET=your_unique_crypto_secret # 共享 Redis 的节点必须相同

监控与维护

健康检查

配置定期健康检查以监控节点状态：

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

日志管理

对于大规模集群，建议使用集中式日志管理系统：

environment:
  - LOG_SQL_DSN=postgresql://newapi:password@log-db-host:5432/new_api_logs # 独立的日志数据库

扩容指南

随着业务增长，您可能需要扩展集群规模。扩容步骤如下：

准备新服务器：安装 Docker 和 Docker Compose
配置从节点：按照"步骤三：配置从节点"的说明配置新的从节点
更新负载均衡器配置：将新节点添加到负载均衡器配置中
测试新节点：确保新节点能正常工作并参与负载均衡

最佳实践

定期备份数据库：即使在集群环境中，也应定期备份数据库
监控资源使用情况：密切关注 CPU、内存和磁盘使用情况
采用滚动更新策略：更新时，先更新从节点，确认稳定后再更新主节点
配置告警系统：监控节点状态，在问题发生时及时通知管理员
地理分布部署：如果可能，将节点部署在不同地理位置，提高可用性

故障排除

节点无法同步数据

检查共享数据库连接是否正常
确认所有节点的 SESSION_SECRET 相同；共享 Redis 时再确认 CRYPTO_SECRET 相同
验证数据库连接配置是否正确

负载不均衡

检查负载均衡器配置和权重设置
监控各节点的资源使用情况，确保没有节点过载
可能需要调整节点权重或增加更多节点

会话丢失问题

确保所有节点使用相同的 SESSION_SECRET
按所选拓扑验证 Redis 配置；独立 Redis 下允许最多 SYNC_FREQUENCY 的有界陈旧窗口
检查客户端是否正确处理 cookie