Cyrene/Deploy.md

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. 配置环境变量

cp .env.example .env
# 编辑 .env，至少配置:
#   LLM_API_URL  /  LLM_API_KEY / LLM_MODEL
#   ADMIN_USERNAME / ADMIN_PASSWORD

2. 启动数据库

./ethend.sh db:start

3. 编译并启动全部服务

./ethend.sh start --build

首次运行会编译全部后端 Go 服务（约 1-2 分钟），之后按依赖顺序启动全部服务，每步等待健康检查通过。

4. 打开控制台

地址	说明
http://localhost:9090	ethend 管理面板
http://localhost:5173	前端聊天界面

详细 CLI 用法见 docs/api/ethend.md。

---

方式二：手动逐服务启动

适用于需要精细控制或调试单个服务的场景。

1. 配置 + 数据库

cp .env.example .env   # 编辑配置
docker compose -f docker-compose.dev.db.yml up -d

2. 按依赖顺序编译并启动

# 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

开发环境（基础设施 + 后端服务）

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。前端需本地启动。

生产环境

# 1. 配置环境变量
cp .env.example .env
# 编辑 .env，填入真实的 API Key 和密码

# 2. 启动所有服务
docker compose up -d

包含 Caddy 反向代理（自动 TLS）。详细说明见 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, plugins — 15 个通用插件/工具)
├── 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

---

数据库管理

# 通过 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

---

数据库备份

# 备份数据库
./scripts/pg-backup.sh backup

# 从最新备份恢复
./scripts/pg-backup.sh restore

备份文件保存在 backups/ 目录，自动保留最近 7 个。详见 docs/pg-backup-migration.md。

---

平台迁移

从 Linux 迁移到 Windows 的详细指南见 Migration.md。

---

附：Windows 部署说明

启动脚本

脚本	终端	说明
ethend.bat	CMD / PowerShell	双击即可运行，无需 Git Bash
ethend.sh	Git Bash	完整 CLI（推荐）

:: 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 已自动处理此差异，手动编译时需要注意：

# 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：

GOWORK=off go build -o main.exe ./cmd/main.go

端口与进程管理

Windows 没有 fuser / ss 命令，等价操作为：

# 查看端口占用
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：

# 检查 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