部署与使用

Xyzen 支持多种部署方式，满足不同的使用场景。

部署方式

1. 全栈部署（推荐用于生产环境）

将 Xyzen 作为完整的全栈应用部署，包含前端界面和后端服务。

前置要求

Docker 和 Docker Compose
至少 2GB 可用内存
网络连接（用于下载依赖）

部署步骤

克隆项目

git clone https://github.com/sciol/xyzen.git
cd xyzen
yarn install

配置环境变量

cp .env.example .env
# 编辑 .env 文件，配置必要的环境变量

启动中间件

docker compose -f ./docker/docker-compose.mid.yaml --env-file ".env.example" up -d

启动后端服务

# 进入后端项目
cd service 
# 安装依赖
uv sync -dev
# 激活环境
source ./.venv/bin/activate
# 启动服务
python -m cmd.main

访问应用

打开浏览器访问 http://localhost:3000 即可使用 Xyzen。

2. 前端 NPM 包集成

如果你已经有自己的前端项目，可以通过 NPM 包的方式集成 Xyzen 的前端组件。

安装包

yarn add @sciol/xyzen

基本使用

import { XyzenProvider, useXyzen } from '@sciol/xyzen'

function App() {
  return (
    <XyzenProvider 
      apiKey="your-api-key"
      endpoint="https://your-xyzen-server.com"
    >
      <YourApp />
    </XyzenProvider>
  )
}

配置说明

参数	类型	必填	说明
`apiKey`	string	是	你的 API 密钥
`endpoint`	string	是	Xyzen 后端服务地址
`model`	string	否	默认使用的模型，如 'gpt-4'
`timeout`	number	否	请求超时时间（毫秒），默认 30000

本地测试

在集成到生产环境之前，建议先在本地测试：

# 克隆示例项目
git clone https://github.com/sciol/xyzen-examples.git
cd xyzen-examples

# 安装依赖
yarn install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 启动开发服务器
yarn dev

环境配置

必需的环境变量

# 数据库配置
DATABASE_URL=postgresql://username:password@localhost:5432/xyzen

# Redis 配置
REDIS_URL=redis://localhost:6379

# API 密钥
XYZEN_API_KEY=your-secret-api-key

# AI 服务商配置
OPENAI_API_KEY=your-openai-key
ALIYUN_API_KEY=your-aliyun-key
# ... 其他 AI 服务商配置

可选配置

# 日志级别
LOG_LEVEL=info

# 服务端口
PORT=8000

# CORS 配置
CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

性能优化

生产环境建议

使用反向代理：配置 Nginx 或 Apache 作为反向代理
启用 HTTPS：使用 Let's Encrypt 或商业证书
数据库优化：根据数据量调整 PostgreSQL 配置
缓存策略：合理配置 Redis 缓存
监控告警：设置系统监控和告警

资源需求

组件	最小配置	推荐配置
CPU	1 核	2 核
内存	2GB	4GB
存储	10GB	50GB
网络	10Mbps	100Mbps

故障排除

常见问题

服务启动失败
- 检查端口是否被占用
- 确认环境变量配置正确
- 查看日志文件排查错误
数据库连接失败
- 确认数据库服务正在运行
- 检查连接字符串格式
- 验证用户名密码权限
AI 服务调用失败
- 检查 API 密钥是否有效
- 确认网络连接正常
- 查看 AI 服务商状态