Cyrene/Deploy.md

Cyrene 部署指南

环境要求

• Go 1.21+
• Node.js 20+
• Docker & Docker Compose

快速启动

1. 环境变量配置

cp backend/.env.example backend/.env
# 编辑 backend/.env，至少配置 LLM_API_KEY

2. 启动基础设施

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 一键管理：

./devtools.sh start all     # 编译并顺序启动所有后端 + 前端
./devtools.sh status        # 查看各服务运行状态
./devtools.sh restart gateway # 单独重启某个服务

或手动逐服务启动（每个在新终端中）：

# 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. 启动前端

cd frontend/web && npm install && npm run dev

访问 http://localhost:5173

5. 启动 DevTools 管理面板 (可选)

cd devtools && npm install && npm start

访问 http://localhost:9090

使用 Docker Compose 完整启动

开发环境

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

启动所有基础设施 + 6 个后端服务（AI-Core、Gateway、Memory Service、Tool Engine、Voice Service、IoT Debug Service），前端仍需本地启动。

生产环境

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。