AskaEth
6ef9e082a6
- 前端: VAD语音检测(@ricky0123/vad-web) + useVoiceInput双模式(流式WS/REST) - Gateway: VoiceStreamManager代理WS流式STT到voice-service - Voice-service: DashScope REST → Realtime WS → Whisper三级引擎 + ffmpeg转码 - 共享模块: pkg/audio(音频转换) + pkg/dashscope(ASR REST客户端) - 清理: 移除旧plugin-manager和pkg/plugins，完成插件→工具合并 - 文档: 完善gateway-api.md和voice-service.md语音API文档 - 工具: scripts/voice/ 语音转换脚本集 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
368 lines
10 KiB
Markdown
368 lines
10 KiB
Markdown
# Cyrene 部署指南
|
||
|
||
三种方式启动开发环境：**ethend 一键**（推荐）、**手动逐服务**、**Docker Compose**。
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Go | 1.21+ | 编译后端服务 |
|
||
| Node.js | 20+ (LTS) | 前端 / ethend |
|
||
| Docker & Docker Compose | — | 数据库 & 基础设施 |
|
||
| Git Bash (Windows) | — | 运行 ethend.sh |
|
||
|
||
### Windows 额外要求
|
||
|
||
- **Git for Windows**（提供 Git Bash 终端），安装时选择 "Git Bash Here"
|
||
- Go 和 Node.js 需加入系统 **PATH**（安装时勾选 "Add to PATH"）
|
||
- Docker Desktop 需启用 **WSL 2** 后端
|
||
|
||
Windows 提供两个启动脚本：
|
||
|
||
| 脚本 | 终端 | 适用场景 |
|
||
|------|------|----------|
|
||
| `ethend.bat` | CMD / PowerShell | 双击运行，无需 Git Bash |
|
||
| `ethend.sh` | Git Bash | 完整 CLI 体验（推荐） |
|
||
|
||
两者支持相同的命令集，日常开发推荐使用 Git Bash 运行 `./ethend.sh`；快速启动可直接双击 `ethend.bat`。
|
||
|
||
---
|
||
|
||
## 方式一：ethend 一键启动（推荐）
|
||
|
||
### 1. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env，至少配置:
|
||
# LLM_API_URL / LLM_API_KEY / LLM_MODEL
|
||
# ADMIN_USERNAME / ADMIN_PASSWORD
|
||
```
|
||
|
||
### 2. 启动数据库
|
||
|
||
```bash
|
||
./ethend.sh db:start
|
||
```
|
||
|
||
### 3. 编译并启动全部服务
|
||
|
||
```bash
|
||
./ethend.sh start --build
|
||
```
|
||
|
||
首次运行会编译全部后端 Go 服务（约 1-2 分钟），之后按依赖顺序启动全部服务，每步等待健康检查通过。
|
||
|
||
### 4. 打开控制台
|
||
|
||
| 地址 | 说明 |
|
||
|------|------|
|
||
| `http://localhost:9090` | ethend 管理面板 |
|
||
| `http://localhost:5173` | 前端聊天界面 |
|
||
|
||
详细 CLI 用法见 [docs/api/ethend.md](docs/api/ethend.md)。
|
||
|
||
---
|
||
|
||
## 方式二：手动逐服务启动
|
||
|
||
适用于需要精细控制或调试单个服务的场景。
|
||
|
||
### 1. 配置 + 数据库
|
||
|
||
```bash
|
||
cp .env.example .env # 编辑配置
|
||
docker compose -f docker-compose.dev.db.yml up -d
|
||
```
|
||
|
||
### 2. 按依赖顺序编译并启动
|
||
|
||
```bash
|
||
# 1) 记忆服务 (端口 8091)
|
||
cd backend/memory-service && go build -o main.exe ./cmd/main.go && ./main.exe
|
||
|
||
# 2) IoT 调试服务 (端口 8083)
|
||
cd backend/iot-debug-service && go build -o main.exe ./cmd/main.go && ./main.exe
|
||
|
||
# 3) 语音服务 (端口 8093)
|
||
cd backend/voice-service && go build -o main.exe ./cmd/main.go && ./main.exe
|
||
|
||
# 4) AI-Core (端口 8081)
|
||
cd backend/ai-core && go build -o main.exe ./cmd/main.go && ./main.exe
|
||
|
||
# 5) Gateway (端口 8080)
|
||
cd backend/gateway && go build -o main.exe ./cmd/main.go && ./main.exe
|
||
|
||
# 6) 前端 (端口 5173)
|
||
cd frontend/web && npm install && npx vite --host 0.0.0.0
|
||
```
|
||
|
||
> **注意**: Linux/macOS 下去掉 `.exe` 后缀。编译时必须设置 `GOWORK=off`。
|
||
|
||
---
|
||
|
||
## 方式三：Docker Compose
|
||
|
||
### 开发环境（基础设施 + 后端服务）
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml up -d
|
||
```
|
||
|
||
启动服务：postgres, redis, qdrant, minio, searxng, memory-service, voice-service, iot-debug-service, ai-core, gateway, ethend。前端需本地启动。
|
||
|
||
### 生产环境
|
||
|
||
```bash
|
||
# 1. 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env，填入真实的 API Key 和密码
|
||
|
||
# 2. 启动所有服务
|
||
docker compose up -d
|
||
```
|
||
|
||
包含 Caddy 反向代理（自动 TLS）。详细说明见 [docs/deploy/docker-compose.md](docs/deploy/docker-compose.md)。
|
||
|
||
---
|
||
|
||
## 项目架构
|
||
|
||
```
|
||
Cyrene/
|
||
├── frontend/web/ # React 前端 (Vite + TypeScript)
|
||
├── backend/
|
||
│ ├── ai-core/ # AI 推理核心 (LLM 编排、人设注入、工具调用、后台思考)
|
||
│ ├── gateway/ # API 网关 (JWT、路由、限流、WebSocket Hub)
|
||
│ ├── memory-service/ # 记忆服务 (CRUD、语义检索、衰减、自动提取)
|
||
│ ├── voice-service/ # 语音服务 (DashScope STT + Edge-TTS)
|
||
│ ├── iot-debug-service/ # IoT 调试服务 (8 个模拟智能家居设备)
|
||
│ └── pkg/ # 共享包 (logger 等)
|
||
├── ethend/ # ethend 管理面板 (Express + WebSocket)
|
||
├── scripts/ # 辅助脚本 (migrate / tunnel / whisper-setup / pg-backup)
|
||
├── searxng/ # SearXNG 搜索引擎配置
|
||
├── backups/ # 数据库备份文件
|
||
├── test/ # E2E 测试
|
||
├── docs/ # 文档
|
||
├── docker-compose.dev.db.yml # 开发基础设施
|
||
├── docker-compose.dev.yml # 开发环境 (DB + 后端 + ethend + SearXNG)
|
||
├── docker-compose.yml # 生产环境 (+ Caddy)
|
||
└── ethend.sh # ethend CLI
|
||
```
|
||
|
||
---
|
||
|
||
## 服务端口
|
||
|
||
| 端口 | 服务 | 对外 |
|
||
|------|------|------|
|
||
| 5173 | Frontend (Vite) | 是 |
|
||
| 8080 | Gateway API | **是**（唯一客户端入口） |
|
||
| 8081 | AI-Core | 否 |
|
||
| 8083 | IoT Debug | 否 |
|
||
| 8091 | Memory Service | 否 |
|
||
| 8088 | SearXNG | 否 |
|
||
| 8093 | Voice Service | 否 |
|
||
| 9090 | ethend | 是 |
|
||
| 5432 | PostgreSQL | 否 |
|
||
| 6379 | Redis | 否 |
|
||
| 6333 | Qdrant HTTP | 否 |
|
||
| 6334 | Qdrant gRPC | 否 |
|
||
| 9000 | MinIO S3 | 否 |
|
||
| 9001 | MinIO Console | 否 |
|
||
|
||
> **客户端只需连接 Gateway (8080)**。所有后端服务不直接对外暴露。
|
||
|
||
---
|
||
|
||
## 核心环境变量
|
||
|
||
完整列表见 `.env.example`。
|
||
|
||
### 必填
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `LLM_API_URL` | LLM API 地址 |
|
||
| `LLM_API_KEY` | LLM API 密钥 |
|
||
| `LLM_MODEL` | 主模型 |
|
||
| `ADMIN_USERNAME` | 管理员用户名 |
|
||
| `ADMIN_PASSWORD` | 管理员密码 |
|
||
| `JWT_SECRET` | JWT 签名密钥 |
|
||
|
||
### 推荐配置
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `LLM_FALLBACK_MODEL` | 回退模型 | `gpt-4o-mini` |
|
||
| `ENV` | 运行环境 | `development` |
|
||
| `REGISTRATION_ENABLED` | 开放注册 | `true` |
|
||
| `ADMIN_NICKNAME` | 管理员显示昵称 | `管理员` |
|
||
| `JWT_EXPIRY_HOURS` | JWT 有效期 | `720` |
|
||
| `ENABLE_BACKGROUND_THINKING` | 后台自主思考 | `true` |
|
||
| `THINK_OFFLINE_GAP_SEC` | 离线时思考间隔 | `600` |
|
||
| `ALLOWED_ORIGINS` | CORS 跨域白名单 | `http://localhost:5173,...` |
|
||
| `INTERNAL_SERVICE_TOKEN` | 服务间通信 Token | — |
|
||
| `WEBHOOK_API_KEY` | Webhook API Key | — |
|
||
|
||
### 语音 (可选)
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `DASHSCOPE_API_KEY` | 阿里云 DashScope API Key | — |
|
||
| `DASHSCOPE_STT_MODEL` | STT 模型 | `qwen3-asr-flash-...` |
|
||
| `TTS_PROVIDER` | TTS 引擎 | `edge-tts` |
|
||
| `ASR_PROVIDER` | 本地 ASR 引擎 | `faster-whisper` |
|
||
|
||
### 服务地址
|
||
|
||
| 变量 | 默认值 |
|
||
|------|--------|
|
||
| `MEMORY_SERVICE_URL` | `http://localhost:8091` |
|
||
| `VOICE_SERVICE_URL` | `http://localhost:8093` |
|
||
| `IOT_SERVICE_URL` | `http://localhost:8083` |
|
||
|
||
### 数据库 / 存储
|
||
|
||
| 变量 | 默认值 |
|
||
|------|--------|
|
||
| `POSTGRES_HOST` / `POSTGRES_PORT` | `localhost` / `5432` |
|
||
| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | `cyrene` / — / `cyrene_ai` |
|
||
| `REDIS_HOST` / `REDIS_PORT` | `localhost` / `6379` |
|
||
| `MINIO_ENDPOINT` | `localhost:9000` |
|
||
| `VECTOR_DB_URL` | `http://localhost:6333` |
|
||
|
||
---
|
||
|
||
## 数据库管理
|
||
|
||
```bash
|
||
# 通过 ethend CLI
|
||
./ethend.sh db:start # 启动
|
||
./ethend.sh db:stop # 停止
|
||
./ethend.sh db:status # 状态检查
|
||
|
||
# 直接 Docker Compose
|
||
docker compose -f docker-compose.dev.db.yml up -d
|
||
docker compose -f docker-compose.dev.db.yml down
|
||
|
||
# 开发数据库容器名
|
||
docker exec -it cyrene_postgres psql -U cyrene -d cyrene_ai
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库备份
|
||
|
||
```bash
|
||
# 备份数据库
|
||
./scripts/pg-backup.sh backup
|
||
|
||
# 从最新备份恢复
|
||
./scripts/pg-backup.sh restore
|
||
```
|
||
|
||
备份文件保存在 `backups/` 目录，自动保留最近 7 个。详见 [docs/pg-backup-migration.md](docs/pg-backup-migration.md)。
|
||
|
||
---
|
||
|
||
## 平台迁移
|
||
|
||
从 Linux 迁移到 Windows 的详细指南见 [Migration.md](Migration.md)。
|
||
|
||
---
|
||
|
||
## 附：Windows 部署说明
|
||
|
||
### 启动脚本
|
||
|
||
| 脚本 | 终端 | 说明 |
|
||
|------|------|------|
|
||
| `ethend.bat` | CMD / PowerShell | 双击即可运行，无需 Git Bash |
|
||
| `ethend.sh` | Git Bash | 完整 CLI（推荐） |
|
||
|
||
```cmd
|
||
:: CMD 中直接运行
|
||
ethend.bat start --build
|
||
ethend.bat status
|
||
ethend.bat logs gateway
|
||
|
||
:: Git Bash 中运行
|
||
./ethend.sh start --build
|
||
./ethend.sh status
|
||
```
|
||
|
||
### 编译差异
|
||
|
||
Windows 下 Go 编译产物为 `main.exe` 而非 `main`。ethend 已自动处理此差异，手动编译时需要注意：
|
||
|
||
```bash
|
||
# Windows (Git Bash / PowerShell)
|
||
go build -o main.exe ./cmd/main.go
|
||
./main.exe
|
||
|
||
# Linux / macOS
|
||
go build -o main ./cmd/main.go
|
||
./main
|
||
```
|
||
|
||
所有 Go 服务编译时必须设置 `GOWORK=off`：
|
||
|
||
```bash
|
||
GOWORK=off go build -o main.exe ./cmd/main.go
|
||
```
|
||
|
||
### 端口与进程管理
|
||
|
||
Windows 没有 `fuser` / `ss` 命令，等价操作为：
|
||
|
||
```bash
|
||
# 查看端口占用
|
||
netstat -ano | findstr ":8080"
|
||
|
||
# 杀进程 (PowerShell)
|
||
powershell -Command "Stop-Process -Id <PID> -Force"
|
||
|
||
# 或者直接用 ethend CLI（跨平台兼容）
|
||
./ethend.sh status # 查看各服务端口状态
|
||
./ethend.sh stop # 停止 ethend
|
||
```
|
||
|
||
### Docker Desktop
|
||
|
||
安装 Docker Desktop 后确保：
|
||
1. **Settings → General** → 勾选 "Use WSL 2 based engine"
|
||
2. **Settings → Resources → WSL Integration** → 启用对应发行版
|
||
3. 启动 Docker Desktop 后等待引擎就绪，再执行 `docker compose` 命令
|
||
|
||
若遇到`docker: error during connect`，说明 Docker Desktop 未运行，启动后重试。
|
||
|
||
### Node.js 版本
|
||
|
||
建议使用 **Node.js 20 LTS**。Node.js 22-24 存在 WebSocket 相关的已知问题（`UV_HANDLE_CLOSING` 崩溃），开发环境建议降级到 v20。
|
||
|
||
### Git Bash PATH
|
||
|
||
若 Git Bash 中找不到 `go` 或 `node`：
|
||
|
||
```bash
|
||
# 检查 PATH
|
||
echo $PATH
|
||
|
||
# 手动添加（添加到 ~/.bashrc 或 ~/.bash_profile）
|
||
export PATH="$PATH:/c/Program Files/Go/bin"
|
||
export PATH="$PATH:/c/Program Files/nodejs"
|
||
```
|
||
|
||
### 快速排错
|
||
|
||
| 症状 | 可能原因 | 解决 |
|
||
|------|----------|------|
|
||
| `go: command not found` | Go 未加入 PATH | 重启 Git Bash 或手动 `export PATH` |
|
||
| `Only one usage of each socket address` | 端口被占用 | `./ethend.sh stop` 或用 PowerShell 杀进程 |
|
||
| `docker: error during connect` | Docker Desktop 未启动 | 启动 Docker Desktop 等待就绪 |
|
||
| `GOWORK` 相关编译错误 | 未设置 GOWORK=off | `export GOWORK=off` 或在命令前加 `GOWORK=off` |
|
||
| `npm install` 卡住 | Windows 下 npm 网络问题 | 设置镜像 `npm config set registry https://registry.npmmirror.com` |
|