私有化 XAI Router 上手

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

一、环境与域名要求

1.1 服务器配置

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

1.2 域名要求

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

• api-xai.your-domain.com (API 服务)
• manage-xai.your-domain.com (账户管理)
• admin-xai.your-domain.com (配置管理)

二、部署步骤

我们提供两种部署方案，请根据您的技术栈和环境要求选择其一：

• 选项 A: Docker Compose 部署：适合单机快速部署。
• 选项 B: Kubernetes 部署：适合 Kubernetes 环境。

二、选项 A: Docker Compose 部署

本文档将引导您完成在自己的服务器上部署 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 文件。

执行以下命令, 请务必将下面 JSON 数据中的 四个参数 替换为您自己的信息：

curl -X POST https://deploy.xaixapi.com/xai?raw=true \
  -H "Content-Type: application/json" \
  -d '{
    "xai_mail": "[email protected]",
    "xai_api": "api-xai.your-domain.com",
    "xai_manage": "manage-xai.your-domain.com",
    "xai_admin": "admin-xai.your-domain.com"
  }' > docker-compose.yml

参数说明:

• xai_mail (必需): 您的管理员邮箱地址。用于初始化管理员账户和接收系统通知。
• xai_api (必需): 您为 API 服务准备的域名。所有 API 请求都将发送到此地址。请务必将此域名解析到您服务器的公网 IP 地址。
• xai_manage (必需): 您为账户管理准备的域名。这是提供给普通用户进行日常管理的服务。请务必将此域名解析到您服务器的公网 IP 地址。
• xai_admin (必需): 您为配置管理准备的域名。用于系统配置。请务必将此域名解析到您服务器的公网 IP 地址。

第 5 步：启动服务

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

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

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

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

• 核心 API 服务: 监听于 3443 端口。
• 配置管理服务: 监听于 3080 端口。
• 账户管理服务: 监听于 3081 端口。

请注意：这些端口仅在服务器内部暴露，您无需（也不应）直接从公网访问它们。在下一步中，我们将配置 Nginx 作为反向代理。

第 6 步：配置 Nginx 反向代理

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

6.1 安装 Nginx

# Ubuntu/Debian
sudo apt update && sudo apt install nginx -y

# CentOS/RHEL
sudo yum install nginx -y

6.2 创建 Nginx 配置文件

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

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

# 创建新配置文件
curl -X POST https://deploy.xaixapi.com/nginx?raw=true \
  -H "Content-Type: application/json" \
  -d '{
    "xai_api": "api-xai.your-domain.com",
    "xai_manage": "manage-xai.your-domain.com",
    "xai_admin": "admin-xai.your-domain.com"
  }' > /etc/nginx/nginx.conf

请务必将 api-xai.your-domain.com、manage-xai.your-domain.com 和 admin-xai.your-domain.com 替换为您的实际域名。

6.3 重启 Nginx

sudo systemctl restart nginx && sudo systemctl enable nginx

第 7 步：配置 HTTPS

为了保障数据安全，建议为您的所有服务配置 HTTPS。

第 8 步：验证部署

1. 检查 Docker 服务状态：

   docker-compose ps
   

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

2. 测试服务访问：

   • 账户管理后台: 在浏览器中打开 http://manage-xai.your-domain.com
   • 系统管理后台: 在浏览器中打开 http://admin-xai.your-domain.com

二、选项 B: Kubernetes 部署

对于需要高可用性、自动伸缩和强大编排能力的环境，我们推荐使用 Kubernetes 进行部署。

部署前置要求

• 一个正常运行的 Kubernetes 集群。
• kubectl 命令行工具已配置并连接到您的集群。
• 集群中已安装并配置好 Ingress Controller (例如 Nginx Ingress Controller)。
• 集群中已配置好用于动态创建持久卷 (Persistent Volume) 的 StorageClass。

第 1 步：生成 xai-router-k8s.yaml 配置文件

与 Docker Compose 类似，我们提供一个命令来生成定制化的 Kubernetes 部署清单 (Manifest)。

curl -X POST https://deploy.xaixapi.com/xai/k8s?raw=true \
  -H "Content-Type: application/json" \
  -d '{
    "xai_mail": "[email protected]",
    "xai_api": "api-xai.your-domain.com",
    "xai_manage": "manage-xai.your-domain.com",
    "xai_admin": "admin-xai.your-domain.com"
  }' > xai-router-k8s.yaml

请务必将 JSON 数据中的四个参数替换为您自己的信息。

第 2 步：审查并调整配置文件

在应用之前，请打开 xai-router-k8s.yaml 文件并根据您的环境进行以下关键调整：

2.1 (重要) 调整持久卷声明 (PVC)

为了持久化存储 Postgres 数据库和 Redis 数据，我们使用了 PersistentVolumeClaim。您需要确保 storageClassName 与您集群中可用的存储类匹配。

找到 PersistentVolumeClaim 定义部分，修改 storageClassName 字段：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: xai-router
  namespace: xai-router
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  storageClassName: alicloud-disk-ssd # <--- 在这里修改

注意：不同的云服务商或自建 K8s 环境，storageClassName 完全不同,以下建议仅供参考,以实际情况为准。

环境	常见的 storageClassName
AWS (EKS)	gp2, gp3
腾讯云 (TKE)	cbs-ssd, cloud-premium
阿里云 (ACK)	alicloud-disk-ssd, alicloud-disk-efficiency
Google Cloud (GKE)	standard, premium-rwo
自建集群 (例如使用 local-path-provisioner)	local-path

您可以通过 kubectl get sc 命令查看集群中可用的 StorageClass。

2.2 检查 Ingress 配置

确保 Ingress 资源中的 host 字段与您准备的域名一致，并且 ingressClassName 与您集群中安装的 Ingress Controller 名称匹配 (通常是 nginx)。

第 3 步：部署到 Kubernetes

使用 kubectl 应用配置文件，它会自动创建所有需要的资源，包括 Namespace, Deployment, Service, PVC 和 Ingress。

kubectl apply -f xai-router-k8s.yaml

第 4 步：验证部署

1. 检查所有资源状态：

   kubectl get all -n xai-router
   

   等待所有 Pods 的状态变为 Running。这可能需要几分钟时间，因为系统需要拉取镜像并启动服务。

2. 检查 Ingress 地址：

   kubectl get ingress -n xai-router
   

   查看 ADDRESS 列，确保 Ingress Controller 已为您的服务分配了一个外部 IP 地址。您需要将您的域名解析到此 IP。

3. 测试服务访问：

   • 账户管理后台: 在浏览器中打开 http://manage-xai.your-domain.com
   • 系统管理后台: 在浏览器中打开 http://admin-xai.your-domain.com

三、服务访问说明

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

• http(s)://api-xai.your-domain.com

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

• http(s)://manage-xai.your-domain.com

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

• http(s)://admin-xai.your-domain.com

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