AskaEth
8c19b79a02
- 新增 README.md 完整项目概览（架构、功能、快速开始） - 更新 Deploy.md 修正过时的服务状态和端口信息 - 整理 .gitignore 补充缺失规则并移除无效项 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
185 lines
5.7 KiB
Markdown
185 lines
5.7 KiB
Markdown
# Cyrene 部署指南
|
||
|
||
## 环境要求
|
||
|
||
- Go 1.21+
|
||
- Node.js 20+
|
||
- Docker & Docker Compose
|
||
|
||
## 快速启动
|
||
|
||
### 1. 环境变量配置
|
||
|
||
```bash
|
||
cp backend/.env.example backend/.env
|
||
# 编辑 backend/.env，至少配置 LLM_API_KEY
|
||
```
|
||
|
||
### 2. 启动基础设施
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.db.yml up -d
|
||
```
|
||
|
||
此命令启动以下服务：
|
||
|
||
| 服务 | 端口 | 用途 |
|
||
|------|------|------|
|
||
| PostgreSQL + pgvector | 5432 | 关系数据库与向量检索 |
|
||
| Redis | 6379 | 缓存与会话 |
|
||
| Qdrant | 6333 (HTTP) / 6334 (gRPC) | 向量数据库 |
|
||
| MinIO | 9000 (API) / 9001 (Console) | 对象存储 |
|
||
| NATS | 4222 / 8222 (Monitoring) | 消息队列 |
|
||
|
||
### 3. 启动后端服务
|
||
|
||
推荐使用 DevTools 一键管理：
|
||
|
||
```bash
|
||
./devtools.sh start all # 编译并顺序启动所有后端 + 前端
|
||
./devtools.sh status # 查看各服务运行状态
|
||
./devtools.sh restart gateway # 单独重启某个服务
|
||
```
|
||
|
||
或手动逐服务启动（每个在新终端中）：
|
||
|
||
```bash
|
||
# 1) 记忆服务
|
||
cd backend/memory-service && go build -o main ./cmd/main.go && ./main
|
||
|
||
# 2) 工具引擎
|
||
cd backend/tool-engine && go build -o main ./cmd/main.go && ./main
|
||
|
||
# 3) IoT 调试服务 (模拟智能家居设备)
|
||
cd backend/iot-debug-service && go build -o main ./cmd/main.go && ./main
|
||
|
||
# 4) 语音服务 (可选，需安装 whisper.cpp)
|
||
cd backend/voice-service && go build -o main ./cmd/main.go && ./main
|
||
|
||
# 5) AI-Core (LLM 推理与对话编排)
|
||
cd backend/ai-core && go build -o main ./cmd/main.go && ./main
|
||
|
||
# 6) Gateway (API 网关，最后启动)
|
||
cd backend/gateway && go build -o main ./cmd/main.go && ./main
|
||
```
|
||
|
||
### 4. 启动前端
|
||
|
||
```bash
|
||
cd frontend/web && npm install && npm run dev
|
||
```
|
||
|
||
访问 `http://localhost:5173`
|
||
|
||
### 5. 启动 DevTools 管理面板 (可选)
|
||
|
||
```bash
|
||
cd devtools && npm install && npm start
|
||
```
|
||
|
||
访问 `http://localhost:9090`
|
||
|
||
## 使用 Docker Compose 完整启动
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml up -d
|
||
```
|
||
|
||
启动所有基础设施 + 6 个后端服务（AI-Core、Gateway、Memory Service、Tool Engine、Voice Service、IoT Debug Service），前端仍需本地启动。
|
||
|
||
### 生产环境
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
额外包含 Caddy 反向代理（自动 TLS），前端静态文件由 Gateway 直接托管。
|
||
|
||
## 项目架构
|
||
|
||
```
|
||
Cyrene/
|
||
├── frontend/web/ # React 前端 (Vite + TypeScript + Tailwind + Zustand)
|
||
├── backend/
|
||
│ ├── ai-core/ # AI 推理核心 (LLM 对话编排、人设注入、工具调用、后台思考)
|
||
│ ├── gateway/ # API 网关 (JWT 认证、路由、限流、WebSocket Hub)
|
||
│ ├── memory-service/ # 记忆服务 (CRUD、语义检索、LLM 提取)
|
||
│ ├── tool-engine/ # 工具引擎 (12+ 内置工具：计算器、HTTP、IoT、文件等)
|
||
│ ├── voice-service/ # 语音服务 (Edge-TTS + Whisper STT)
|
||
│ ├── iot-debug-service/ # IoT 调试服务 (8 个模拟设备：灯/空调/窗帘/传感器/门锁)
|
||
│ └── proto/ # Protobuf 定义 (预留)
|
||
├── devtools/ # 开发管理面板 (Express)
|
||
├── scripts/ # 辅助脚本
|
||
├── test/ # E2E 测试 (CDP/Chromium)
|
||
├── docs/ # 文档与调试记录
|
||
├── debug/ # 诊断脚本
|
||
├── docker-compose.dev.db.yml # 开发基础设施 (仅 DB)
|
||
├── docker-compose.dev.yml # 开发环境 (DB + 后端服务)
|
||
├── docker-compose.yml # 生产环境 (DB + 后端 + Caddy)
|
||
└── Caddyfile # 反向代理配置
|
||
```
|
||
|
||
## 服务端口
|
||
|
||
| 端口 | 服务 |
|
||
|------|------|
|
||
| 5173 | 前端 (Vite) |
|
||
| 8080 | Gateway API |
|
||
| 8081 | AI-Core API |
|
||
| 8083 | IoT 调试服务 |
|
||
| 8091 | 记忆服务 |
|
||
| 8092 | 工具引擎 |
|
||
| 8093 | 语音服务 |
|
||
| 9090 | DevTools 管理面板 |
|
||
| 5432 | PostgreSQL |
|
||
| 6379 | Redis |
|
||
| 6333 | Qdrant HTTP |
|
||
| 6334 | Qdrant gRPC |
|
||
| 9000 | MinIO S3 |
|
||
| 9001 | MinIO Console |
|
||
| 4222 | NATS |
|
||
| 8222 | NATS Monitoring |
|
||
|
||
## 环境变量
|
||
|
||
参考 `backend/.env.example`：
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `ENV` | 运行环境 | `development` |
|
||
| `LLM_API_URL` | LLM API 地址 | `https://api.openai.com/v1` |
|
||
| `LLM_API_KEY` | LLM API 密钥 | — |
|
||
| `LLM_MODEL` | 主模型 | `gpt-4o` |
|
||
| `LLM_FALLBACK_MODEL` | 回退模型 | `gpt-4o-mini` |
|
||
| `POSTGRES_HOST` | PostgreSQL 主机 | `localhost` |
|
||
| `POSTGRES_PORT` | PostgreSQL 端口 | `5432` |
|
||
| `POSTGRES_USER` | PostgreSQL 用户 | `cyrene` |
|
||
| `POSTGRES_PASSWORD` | PostgreSQL 密码 | — |
|
||
| `POSTGRES_DB` | PostgreSQL 库名 | `cyrene_ai` |
|
||
| `REDIS_HOST` | Redis 主机 | `localhost` |
|
||
| `REDIS_PORT` | Redis 端口 | `6379` |
|
||
| `JWT_SECRET` | JWT 签名密钥 | — |
|
||
| `JWT_EXPIRY_HOURS` | JWT 过期时间 | `720` |
|
||
| `MINIO_ENDPOINT` | MinIO 地址 | `localhost:9000` |
|
||
| `MINIO_ACCESS_KEY` | MinIO Access Key | — |
|
||
| `MINIO_SECRET_KEY` | MinIO Secret Key | — |
|
||
| `VECTOR_DB_URL` | Qdrant 地址 | `http://localhost:6333` |
|
||
| `ADMIN_USERNAME` | 管理员账户 | `admin` |
|
||
| `ADMIN_PASSWORD` | 管理员密码 | — |
|
||
| `ADMIN_NICKNAME` | 昔涟对管理员的称呼 | `管理员` |
|
||
| `REGISTRATION_ENABLED` | 开放注册 | `true` |
|
||
| `ENABLE_BACKGROUND_THINKING` | 后台思考 | `true` |
|
||
| `INTERNAL_SERVICE_TOKEN` | 内部服务通信 Token | — |
|
||
| `WEBHOOK_API_KEY` | Webhook API Key | — |
|
||
| `IOT_SERVICE_URL` | IoT 服务地址 | `http://localhost:8083` |
|
||
| `TTS_PROVIDER` | TTS 引擎 | `edge-tts` |
|
||
| `TTS_VOICE` | TTS 语音 | `zh-CN-XiaoxiaoNeural` |
|
||
| `ASR_PROVIDER` | ASR 引擎 | `faster-whisper` |
|
||
| `ASR_MODEL` | ASR 模型 | `medium` |
|
||
|
||
## 平台迁移
|
||
|
||
从 Linux 迁移到 Windows 的详细指南见 [Migration.md](Migration.md)。
|