服务端指南

Quguo Limited2024-01-19

服务端指南

开始

PocketLittle Toy 的服务端组件负责处理语音命令并使用 AI 模型生成响应。我们提供 Docker 部署和手动部署两种选项。

系统要求

CPU：2核或以上
内存：最低4GB，建议8GB
存储：最低20GB
操作系统：Ubuntu 20.04 或更新版本
Docker 版本 20.10 或更新版本

前置条件

已安装 Docker 和 Docker Compose
AI 模型的有效 API 密钥（OpenAI、DeepSeek 等）
域名（可选，用于 HTTPS）
基本的 Linux 和 Docker 知识

部署文件

目录结构

server/
├── docker-compose.yml
├── .env
├── config/
│   ├── nginx/
│   │   └── nginx.conf
│   └── app/
│       └── config.yaml
├── data/
│   └── db/
└── logs/

配置文件

.env：环境变量

OPENAI_API_KEY=你的api密钥
DEEPSEEK_API_KEY=你的api密钥
PORT=3000

config.yaml：应用配置

server:
  port: 3000
  host: 0.0.0.0

ai:
  default_model: gpt-3.5-turbo
  timeout: 30000
  max_tokens: 2000

audio:
  sample_rate: 16000
  channels: 1
  format: wav

部署方法

Docker 部署（推荐）

克隆仓库：

git clone https://github.com/your-repo/pkl-server.git
cd pkl-server

配置环境变量：

cp .env.example .env
# 编辑 .env 文件设置你的配置

启动服务：
```
docker-compose up -d
```

手动部署

安装依赖：
```
npm install
# 或者
yarn install
```

配置应用：

cp config.example.yaml config.yaml
# 编辑 config.yaml

启动服务器：
```
npm run start
# 或者
yarn start
```

常见问题

连接问题

检查服务器是否运行：
```
docker-compose ps
# 或者
pm2 status
```
验证网络连接：
```
curl http://localhost:3000/health
```

API 问题

验证 .env 中的 API 密钥
检查 API 配额和限制
查看服务器日志：
```
docker-compose logs -f app
```

性能问题

监控系统资源：
```
docker stats
# 或者
htop
```
检查错误日志：
```
tail -f logs/error.log
```

维护

备份

数据库备份：

docker-compose exec db pg_dump -U postgres > backup.sql

配置备份：
```
tar -czf config-backup.tar.gz config/
```

更新

拉取最新更改：
```
git pull origin main
```

更新容器：

docker-compose pull
docker-compose up -d

监控

设置健康检查
配置日志轮转
监控系统指标
设置关键问题告警

安全

保持系统更新
使用 HTTPS
配置防火墙
定期安全审计

API 文档

认证

POST /api/auth
Content-Type: application/json

{
  "device_id": "你的设备ID",
  "api_key": "你的API密钥"
}

语音处理

POST /api/voice
Content-Type: multipart/form-data

audio_file: <二进制数据>

聊天完成

POST /api/chat
Content-Type: application/json

{
  "message": "你好",
  "model": "gpt-3.5-turbo"
}

更详细的 API 文档，请访问我们的 API 参考。

服务端指南

ON THIS PAGE