私有化 XAI Router 上手

私有化版本与 XAI Control 云服务在功能上保持一致，但所有数据与配置均保留在本地，适合对数据合规、网络隔离有严格要求的企业或团队。

一、环境与域名要求

1.1 服务器配置

实例推荐: 推荐使用一台拥有 root 权限的海外 Linux 服务器，例如 AWS t3.small (2核 CPU, 2GB 内存, 10GB+ 磁盘) 或同等配置的机型。

1.2 域名要求

部署前，请准备 三个 已解析到该服务器 IP 地址的域名，例如：

• api.your-domain.com (用于 API 服务)
• manage.your-domain.com (用于用户管理后台)
• admin.your-domain.com (用于系统管理后台)

二、部署步骤

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

第 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?raw=true \
  -H "Content-Type: application/json" \
  -d '{
    "xai_mail": "[email protected]",
    "xai_api": "api.your-domain.com"
  }' > docker-compose.yml

参数说明:

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

第 5 步：启动服务

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

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

此命令会根据 docker-compose.yml 文件的定义，自动拉取所需镜像并启动 XAI Router 的完整服务栈。服务启动后，您可以通过 docker-compose ps 命令查看所有容器的运行状态。

核心服务栈主要包括以下三个在服务器内部监听的组件：

• 核心 API 服务: 监听于 3443 端口。这是系统的后端主服务，负责处理所有 API 路由和逻辑。
• 配置管理服务: 监听于 3080 端口。为系统管理后台 (admin.your-domain.com) 提供数据接口,实质是对核心API的前端调用。
• 账户管理服务: 监听于 3081 端口。为用户管理后台 (manage.your-domain.com) 提供数据接口,实质是对核心API的前端调用。

请注意：这些端口仅在服务器内部暴露，您无需（也不应）直接从公网访问它们。在下一步中，我们将配置 Nginx 作为反向代理，它会将来自您域名的外部请求安全、高效地转发到这些内部服务端口。

第 6 步：配置 Nginx 反向代理

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

6.1 安装 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.2 创建 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, DELETE, 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, DELETE, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;

            proxy_pass http://xai_backend;
        }
    }

    # Admin 系统配置(仅管理员 root key 可以登录)
    server {
        listen 80;
        server_name admin.your-domain.com;
        location / {
            proxy_pass http://127.0.0.1:3080;
        }
    }

    # Manage 账户管理
    server {
        listen 80;
        server_name manage.your-domain.com;
        location / {
            proxy_pass http://127.0.0.1:3081;
        }
    }
}

6.3 重启 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. 测试服务访问：

   • 用户管理后台: 在浏览器中打开 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 登陆。
  • 访问方式: 在浏览器中打开。
  • 主要功能: 进行系统级的配置，如模型服务商管理等。