𝐗𝐀𝐈 𝐗𝐀𝐏𝐈

私有部署

本文档将引导您完成在自己的服务器上部署 XAI Gateway 的过程。部署过程依赖于 Docker 和 Docker Compose，请确保您的服务器已准备好相应环境。

前提条件

  • 一台拥有 root 权限的海外 Linux 服务器, 推荐US Region AWS t3.small 2核2G 10G 磁盘机型 。
  • 三个已解析到该服务器 IP 地址的域名，例如：
    • api.your-domain.com (用于 API 服务)
    • manage.your-domain.com (用于用户管理后台)
    • admin.your-domain.com (用于系统管理后台)

部署步骤

第 1 步：安装 Docker

我们推荐使用 Docker 官方脚本来安装，它支持大多数主流的 Linux 发行版。

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

第 2 步：安装 Docker Compose

此命令会从 GitHub 下载最新稳定版的 Docker Compose。

curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose

第 3 步：授予执行权限

为刚刚下载的 Docker Compose 二进制文件添加可执行权限。

chmod +x /usr/local/bin/docker-compose

第 4 步：生成 docker-compose.yml 配置文件

这是最关键的一步。您需要通过我们的部署服务生成一个为您量身定制的 docker-compose.yml 文件。

执行以下命令，但请务必将 xai_mail 和 xai_api 的值替换为您自己的信息：

curl -X POST https://deploy.xaixapi.com/xai \
  -H "Content-Type: application/json" \
  -d '{
    "xai_mail": "[email protected]",
    "xai_api": "api.your-domain.com"
  }' | jq -r '.content' > docker-compose.yml

参数说明:

  • xai_mail (必需): 您的管理员邮箱地址。它将用于接收重要通知和初始化管理员账户。
  • xai_api (必需): 您为服务准备的 API 域名。将此域名正确解析到您服务器的 IP 地址。服务启动后，所有 API 请求都将发送到此地址。

第 5 步：启动服务

使用生成的配置文件，在后台启动所有服务。

docker-compose -f docker-compose.yml up -d

第 6 步：配置 Nginx 反向代理

为了让您的服务通过域名访问，并提供管理后台，您需要配置 Nginx 作为反向代理。

6.1 下载管理后台静态资源

在配置 Nginx 之前，请先下载管理后台所需的静态资源文件包，并解压到 Nginx 的 html 目录下。

# 假设 Nginx 的根目录是 /usr/share/nginx/html 或 /var/www/html

# 下载静态资源
wget https://filelist.cn/disk/0/pages.tgz
tar xzf pages.tgz

执行后，您的目录结构应如下所示：

${NGINX_HTML_PATH}/
└── pages/
    ├── admin/
    │   └── ... (admin 后台文件)
    └── manage/
        └── ... (manage 后台文件)
6.2 安装 Nginx
# Ubuntu/Debian
sudo apt update && sudo apt install nginx -y

# CentOS/RHEL
sudo yum install nginx -y
# 或者 (RHEL 8+)
sudo dnf install nginx -y
6.3 创建 Nginx 配置文件

建议备份并替换整个 nginx.conf 文件，以获得最佳兼容性。

# 备份现有配置
sudo mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

# 创建新配置文件
sudo vim /etc/nginx/nginx.conf

将以下内容完整复制到 /etc/nginx/nginx.conf 文件中。 请务必将 api.your-domain.com、manage.your-domain.com 和 admin.your-domain.com 替换为您的实际域名。

user root;
worker_processes auto;
worker_cpu_affinity auto;
worker_rlimit_nofile 65535;

events {
    use epoll;
    worker_connections 65535;
    multi_accept on;
}

http {
    include mime.types;
    default_type application/octet-stream;
    charset utf-8;
    http2 on;

    # 基础
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 600;
    keepalive_requests 10000;
    reset_timedout_connection on;

    # 压缩
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_min_length 1024;
    gzip_buffers 16 8k;
    gzip_types text/plain text/css text/xml text/javascript application/json application/javascript application/xml+rss application/x-javascript application/x-font-ttf application/vnd.ms-fontobject font/opentype image/svg+xml image/x-icon text/event-stream;

    # 客户端请求
    client_max_body_size 256m;
    client_body_buffer_size 1m;
    client_header_buffer_size 2k;
    large_client_header_buffers 4 8k;

    # 代理
    proxy_read_timeout 900s;
    proxy_send_timeout 900s;
    proxy_connect_timeout 60s;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Connection "";
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # 流式响应
    proxy_cache off;
    proxy_buffering off;
    proxy_request_buffering off;
    chunked_transfer_encoding on;

    # 日志
    log_format main "$status  $request_time  $request_method  $http_host$request_uri  [$http_user_agent]  [$time_local]  [$http_x_forwarded_for $remote_addr]  $http_referer";
    access_log /var/log/nginx/access.log main buffer=32k flush=30s;
    error_log /var/log/nginx/error.log;

    # 上游服务 (指向 Docker 容器)
    upstream xai_backend {
        server 127.0.0.1:3443;
        keepalive 32;
        keepalive_timeout 60s;
    }

    # API 服务
    server {
        listen 80;
        server_name api.your-domain.com;

        # WebSocket 支持
        location /v1/realtime {
            proxy_pass http://xai_backend;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }

        # 其他所有API请求
        location / {
            if ($request_method = 'OPTIONS') {
               add_header 'Access-Control-Allow-Origin' '*';
               add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, OPTIONS';
               add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type';
               add_header 'Access-Control-Max-Age' 1728000;
               add_header 'Content-Type' 'text/plain; charset=utf-8';
               add_header 'Content-Length' 0;
               return 204;
            }

            add_header 'Access-Control-Allow-Origin' '*' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;

            proxy_pass http://xai_backend;
        }
    }

    # Manage 账户管理 (静态网站)
    server {
        listen 80;
        server_name manage.your-domain.com;
        # Nginx 静态资源目录, 请根据 6.1 步骤中的实际路径调整
        root /usr/share/nginx/html/pages/manage;
        index index.html;
        location / {
            try_files $uri $uri/ /index.html;
        }
    }

    # Admin 系统配置 (静态网站)
    server {
        listen 80;
        server_name admin.your-domain.com;
        # Nginx 静态资源目录, 请根据 6.1 步骤中的实际路径调整
        root /usr/share/nginx/html/pages/admin;
        index index.html;
        location / {
            try_files $uri $uri/ /index.html;
        }
    }
}
6.4 重启 Nginx
# 测试配置文件语法
sudo nginx -t

# 重启 Nginx 服务并设置开机自启
sudo systemctl restart nginx
sudo systemctl enable nginx

第 7 步：配置 HTTPS（推荐）

建议为您的所有服务配置 HTTPS。

第 8 步：验证部署

  1. 检查 Docker 服务状态：

    docker-compose ps

    确保所有服务都处于 Up 或 running 状态。

  2. 测试服务访问：

    • API 服务: curl http://api.your-domain.com
    • 用户管理后台: 在浏览器中打开 http://manage.your-domain.com
    • 系统管理后台: 在浏览器中打开 http://admin.your-domain.com

部署完成：服务访问说明

恭喜您，部署已完成！现在您拥有三个核心服务，可通过不同域名访问：

  • http://api.your-domain.com

    • 用途: API 接口网关。这是系统的核心，所有对大模型的请求都通过此域名进行。
    • 访问方式: 通过代码、SDK 或 API 调试工具（如 Postman）进行调用。

  • http://manage.your-domain.com

    • 用途: 用户管理后台。供您的终端用户或客户使用。
    • 访问方式: 在浏览器中打开。
    • 主要功能: 用户可以在此平台注册、获取 API Key、查看自己的消费额度、查询请求日志, 创建/查看/充值/更新/删除子账户等。

  • http://admin.your-domain.com

    • 用途: 系统管理后台。系统管理员使用, 仅允许 XAI API ROOT Key 登陆。
    • 访问方式: 在浏览器中打开。
    • 主要功能: 进行系统级的配置，如模型服务商管理等。
账户层级与继承 →