One API 高可用部署及负载配置完整使用步骤

要实现 One API 的高可用部署，关键在于消除服务的单点故障。核心思路是：部署多个 One API 实例 + 共享数据库与缓存 + 前置负载均衡器。

下面是具体的实现步骤：

📝 准备工作：规划共享基础设施

· 数据库：生产环境务必使用 MySQL 或 PostgreSQL 作为共享数据库，而非默认的 SQLite。

· 缓存 (Redis)：强烈建议部署，用于支持多实例部署下的会话共享和分布式速率限制。

· 负载均衡器：负责将流量分发到后端的多个 One API 实例。最常用的是 Nginx，也可以根据环境选择云厂商的负载均衡服务（如阿里云 SLB、AWS ELB）。

📦 步骤一：部署共享基础设施

部署数据库：通过包管理器或 Docker 部署一个高可用数据库，并完成初始化。
部署 Redis：同样使用 Docker 等方式部署 Redis 服务。
bash 复制代码
```
docker run -d --name redis -p 6379:6379 --restart always redis:latest
```
（可选）部署 Nginx：Nginx 可以作为负载均衡器，也可以后续配置。

🚀 步骤二：部署 One API 多实例

需要在多台服务器或同一服务器的不同端口，以相同配置启动多个实例。推荐使用 Docker Compose，核心 docker-compose.yml 模板如下：

yaml 复制代码

version: '3.4'
services:
  one-api:
    image: justsong/one-api:latest
    container_name: one-api
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      # 关键：所有实例必须连接同一个数据库
      - SQL_DSN=root:123456@tcp(your_mysql_host:3306)/oneapi
      # 关键：Redis 连接地址，用于会话共享和速率限制
      - REDIS_CONN_STRING=redis://:@your_redis_host:6379
      # 关键：所有实例必须设置完全相同的强随机字符串
      - SESSION_SECRET=your_very_strong_and_random_secret_here
    healthcheck:
      test: ["CMD", "wget", "-q", "-O-", "http://localhost:3000/api/status"]
      interval: 30s
      timeout: 10s
      retries: 3

为确保高可用，应将此 Compose 文件在多台服务器上部署，或通过 docker-compose up -d 命令在同一台机器上创建多个不同端口的实例。

⚖️ 步骤三：配置负载均衡 (以 Nginx 为例)

以下是一个基本的 Nginx 负载均衡配置示例，用于将流量分发到三个 One API 实例：

nginx 复制代码

upstream one_api_backend {
    # 负载均衡算法，默认为轮询
    # 可选的健康检查配置
    server 192.168.1.10:3000 weight=1 max_fails=3 fail_timeout=30s;
    server 192.168.1.11:3000 weight=1 max_fails=3 fail_timeout=30s;
    server 192.168.1.12:3000 weight=1 max_fails=3 fail_timeout=30s;
}

server {
    listen 80;
    server_name api.yourdomain.com; # 替换为你的域名

    # 关键配置：处理流式响应
    location / {
        proxy_pass http://one_api_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
        # 流式响应必须关闭缓冲
        proxy_buffering off;
        # 针对大模型 API 的超时设置
        proxy_read_timeout 300s;
    }
}

配置后执行 nginx -t 测试语法，然后 systemctl reload nginx 使配置生效。

✅ 步骤四：验证高可用性

· 一致性验证：登录任意一个实例的后台，创建新的 Token。然后从其他实例的后台查看，确认数据已同步。

· 会话验证 (Session)：用 A 实例登录，刷新页面或跳转到其他页面，确认登录状态不会丢失。

· 故障转移 (Failover) 验证：在 Nginx 持续压测时，手动停止一个后端 One API 容器，观察服务是否仍有响应，Nginx 应自动将流量切换到其他健康节点。

🚨 常见问题与注意事项

· SESSION_SECRET：这是高可用的关键。如果各实例设置不一致，会导致登录状态失效。建议使用命令生成强随机字符串：openssl rand -base64 32。

· 流式响应：如果调用 API 时发现输出是一段段出现而非逐字显示，请检查 Nginx 配置中的 proxy_buffering off; 指令是否已正确设置。

· 数据库选择：个人测试可用 SQLite；生产环境务必使用 MySQL/PostgreSQL，并确保所有实例都通过 SQL_DSN 连接到同一个数据库。

· Redis 的重要性：如果不配置 REDIS_CONN_STRING，One API 会降级运行但无法实现分布式会话共享和速率限制。对于生产环境，建议部署 Redis 哨兵或集群模式以避免 Redis 成为新的单点故障。

One API 部署完成后，你还可以通过配置渠道、令牌等功能来管理你的 API 请求。