refactor: 认证系统重构 + DevTools CLI 重写 + 文档全面更新

- auth: Login 简化为管理员始终通过 .env 验证，GetProfile 修正 admin DB 查询 - devtools: .sh/.bat 同步重写为完整 CLI (start/stop/status/logs/build/db:*) - docs: 新增 devtools.md，重写 Deploy.md (三种方式+Windows说明)，更新 README/gateway-api - voice-service: DashScope 实时流式 STT 支持 - gateway: Phase 6 多模型配置 + 多端客户端管理 + WebSocket 增强 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-24 14:55:47 +08:00
parent 83e94d9e97
commit 7eb5e984c2
18 changed files with 2405 additions and 677 deletions
@@ -1,184 +1,366 @@
 # Cyrene 部署指南

+三种方式启动开发环境：**DevTools 一键**（推荐）、**手动逐服务**、**Docker Compose**。
+
+---
+
 ## 环境要求

- Go 1.21+
- Node.js 20+
- Docker & Docker Compose
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| Go | 1.21+ | 编译后端服务 |
+| Node.js | 20+ (LTS) | 前端 / DevTools |
+| Docker & Docker Compose | — | 数据库 & 基础设施 |
+| Git Bash (Windows) | — | 运行 devtools.sh |

-## 快速启动
+### Windows 额外要求

-### 1. 环境变量配置
+- **Git for Windows**（提供 Git Bash 终端），安装时选择 "Git Bash Here"
+- Go 和 Node.js 需加入系统 **PATH**（安装时勾选 "Add to PATH"）
+- Docker Desktop 需启用 **WSL 2** 后端
+
+Windows 提供两个启动脚本：
+
+| 脚本 | 终端 | 适用场景 |
+|------|------|----------|
+| `devtools.bat` | CMD / PowerShell | 双击运行，无需 Git Bash |
+| `devtools.sh` | Git Bash | 完整 CLI 体验（推荐） |
+
+两者支持相同的命令集，日常开发推荐使用 Git Bash 运行 `./devtools.sh`；快速启动可直接双击 `devtools.bat`。
+
+---
+
+## 方式一：DevTools 一键启动（推荐）
+
+### 1. 配置环境变量

 ```bash
 cp backend/.env.example backend/.env
-# 编辑 backend/.env，至少配置 LLM_API_KEY
+# 编辑 backend/.env，至少配置:
+#   LLM_API_URL  /  LLM_API_KEY / LLM_MODEL
+#   ADMIN_USERNAME / ADMIN_PASSWORD
 ```

-### 2. 启动基础设施
+### 2. 启动数据库

 ```bash
+./devtools.sh db:start
+```
+
+### 3. 编译并启动全部服务
+
+```bash
+./devtools.sh start --build
+```
+
+首次运行会编译全部后端 Go 服务（约 1-2 分钟），之后按依赖顺序启动全部 9 个服务，每步等待健康检查通过。
+
+### 4. 打开控制台
+
+| 地址 | 说明 |
+|------|------|
+| `http://localhost:9090` | DevTools 管理面板 |
+| `http://localhost:5173` | 前端聊天界面 |
+
+详细 CLI 用法见 [docs/api/devtools.md](docs/api/devtools.md)。
+
+---
+
+## 方式二：手动逐服务启动
+
+适用于需要精细控制或调试单个服务的场景。
+
+### 1. 配置 + 数据库
+
+```bash
+cp backend/.env.example backend/.env   # 编辑配置
 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 一键管理：
+### 2. 按依赖顺序编译并启动

 ```bash
-./devtools.sh start all     # 编译并顺序启动所有后端 + 前端
-./devtools.sh status        # 查看各服务运行状态
-./devtools.sh restart gateway # 单独重启某个服务
+# 1) 记忆服务 (端口 8091)
+cd backend/memory-service && go build -o main.exe ./cmd/main.go && ./main.exe
+
+# 2) 工具引擎 (端口 8092)
+cd backend/tool-engine && go build -o main.exe ./cmd/main.go && ./main.exe
+
+# 3) 插件管理器 (端口 8094)
+cd backend/plugin-manager && go build -o main.exe ./cmd/main.go && ./main.exe
+
+# 4) IoT 调试服务 (端口 8083)
+cd backend/iot-debug-service && go build -o main.exe ./cmd/main.go && ./main.exe
+
+# 5) 语音服务 (端口 8093)
+cd backend/voice-service && go build -o main.exe ./cmd/main.go && ./main.exe
+
+# 6) AI-Core (端口 8081)
+cd backend/ai-core && go build -o main.exe ./cmd/main.go && ./main.exe
+
+# 7) 多平台桥接 (端口 8095)
+cd backend/platform-bridge && go build -o main.exe ./cmd/main.go && ./main.exe
+
+# 8) Gateway (端口 8080)
+cd backend/gateway && go build -o main.exe ./cmd/main.go && ./main.exe
+
+# 9) 前端 (端口 5173)
+cd frontend/web && npm install && npx vite --host 0.0.0.0
 ```

-或手动逐服务启动（每个在新终端中）：
+> **注意**: Linux/macOS 下去掉 `.exe` 后缀。GOWORK=off 是必需的（项目使用 Go workspace）。

-```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
+## 方式三：Docker Compose

-# 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 完整启动
-
-### 开发环境
+### 开发环境（基础设施 + 6 个后端服务）

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

-启动所有基础设施 + 6 个后端服务（AI-Core、Gateway、Memory Service、Tool Engine、Voice Service、IoT Debug Service），前端仍需本地启动。
+启动服务：postgres, redis, qdrant, minio, nats, memory-service, tool-engine, voice-service, iot-debug-service, ai-core, gateway。前端需本地启动。
+
+> plugin-manager 和 platform-bridge 目前不包含在 docker-compose 中，需本地启动。

 ### 生产环境

 ```bash
+# 编辑 .env，配置生产密钥
 docker compose up -d
 ```

 额外包含 Caddy 反向代理（自动 TLS），前端静态文件由 Gateway 直接托管。

+---
+
 ## 项目架构

 ```
 Cyrene/
-├── frontend/web/             # React 前端 (Vite + TypeScript + Tailwind + Zustand)
+├── frontend/web/                # React 前端 (Vite + TypeScript)
 ├── 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                 # 反向代理配置
+│   ├── ai-core/                 # AI 推理核心 (LLM 编排、人设注入、工具调用、后台思考)
+│   ├── gateway/                 # API 网关 (JWT、路由、限流、WebSocket Hub)
+│   ├── memory-service/          # 记忆服务 (CRUD、语义检索、衰减、自动提取)
+│   ├── tool-engine/             # 工具引擎 (13+ 内置工具：计算器/HTTP/IoT/文件等)
+│   ├── voice-service/           # 语音服务 (DashScope STT + Edge-TTS)
+│   ├── iot-debug-service/       # IoT 调试服务 (8 个模拟智能家居设备)
+│   ├── plugin-manager/          # 插件管理器 (14 个内置插件)
+│   ├── platform-bridge/         # 多平台桥接 (QQ / Telegram / Discord / Webhook)
+│   └── pkg/                     # 共享包 (logger)
+├── devtools/                    # DevTools 管理面板 (Express + WebSocket)
+├── scripts/                     # 辅助脚本 (migrate / tunnel / whisper-setup)
+├── test/                        # E2E 测试
+├── docs/                        # 文档
+├── docker-compose.dev.db.yml    # 开发基础设施
+├── docker-compose.dev.yml       # 开发环境 (DB + 后端)
+├── docker-compose.yml           # 生产环境 (+ Caddy)
+└── devtools.sh                  # DevTools CLI
 ```

+---
+
 ## 服务端口

-| 端口 | 服务 |
+| 端口 | 服务 | 对外 |
+|------|------|------|
+| 5173 | Frontend (Vite) | 是 |
+| 8080 | Gateway API | **是**（唯一客户端入口） |
+| 8081 | AI-Core | 否 |
+| 8083 | IoT Debug | 否 |
+| 8091 | Memory Service | 否 |
+| 8092 | Tool Engine | 否 |
+| 8093 | Voice Service | 否 |
+| 8094 | Plugin Manager | 否 |
+| 8095 | Platform Bridge | 否 |
+| 9090 | DevTools | 是 |
+| 5432 | PostgreSQL | 否 |
+| 6379 | Redis | 否 |
+| 6333 | Qdrant HTTP | 否 |
+| 6334 | Qdrant gRPC | 否 |
+| 9000 | MinIO S3 | 否 |
+| 9001 | MinIO Console | 否 |
+| 4222 | NATS | 否 |
+| 8222 | NATS Monitoring | 否 |
+
+> **客户端只需连接 Gateway (8080)**。所有后端服务不直接对外暴露。
+
+---
+
+## 核心环境变量
+
+完整列表见 `backend/.env.example`。
+
+### 必填
+
+| 变量 | 说明 |
 |------|------|
-| 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 |
+| `LLM_API_URL` | LLM API 地址 |
+| `LLM_API_KEY` | LLM API 密钥 |
+| `LLM_MODEL` | 主模型 |
+| `ADMIN_USERNAME` | 管理员用户名 |
+| `ADMIN_PASSWORD` | 管理员密码 |
+| `JWT_SECRET` | JWT 签名密钥 |

-## 环境变量
-
-参考 `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` | 昔涟对管理员的称呼 | `管理员` |
+| `ENV` | 运行环境 | `development` |
 | `REGISTRATION_ENABLED` | 开放注册 | `true` |
-| `ENABLE_BACKGROUND_THINKING` | 后台思考 | `true` |
-| `INTERNAL_SERVICE_TOKEN` | 内部服务通信 Token | — |
+| `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 | — |
-| `IOT_SERVICE_URL` | IoT 服务地址 | `http://localhost:8083` |
+
+### 语音 (可选)
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `DASHSCOPE_API_KEY` | 阿里云 DashScope API Key | — |
+| `DASHSCOPE_STT_MODEL` | STT 模型 | `qwen3-asr-flash-...` |
 | `TTS_PROVIDER` | TTS 引擎 | `edge-tts` |
-| `TTS_VOICE` | TTS 语音 | `zh-CN-XiaoxiaoNeural` |
-| `ASR_PROVIDER` | ASR 引擎 | `faster-whisper` |
-| `ASR_MODEL` | ASR 模型 | `medium` |
+| `ASR_PROVIDER` | 本地 ASR 引擎 | `faster-whisper` |
+
+### 服务地址
+
+| 变量 | 默认值 |
+|------|--------|
+| `MEMORY_SERVICE_URL` | `http://localhost:8091` |
+| `TOOL_ENGINE_URL` | `http://localhost:8092` |
+| `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
+# 通过 DevTools CLI
+./devtools.sh db:start          # 启动
+./devtools.sh db:stop           # 停止
+./devtools.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
+```
+
+---

 ## 平台迁移

 从 Linux 迁移到 Windows 的详细指南见 [Migration.md](Migration.md)。
+
+---
+
+## 附：Windows 部署说明
+
+### 启动脚本
+
+| 脚本 | 终端 | 说明 |
+|------|------|------|
+| `devtools.bat` | CMD / PowerShell | 双击即可运行，无需 Git Bash |
+| `devtools.sh` | Git Bash | 完整 CLI（推荐） |
+
+```cmd
+:: CMD 中直接运行
+devtools.bat start --build
+devtools.bat status
+devtools.bat logs gateway
+
+:: Git Bash 中运行
+./devtools.sh start --build
+./devtools.sh status
+```
+
+### 编译差异
+
+Windows 下 Go 编译产物为 `main.exe` 而非 `main`。DevTools 已自动处理此差异，手动编译时需要注意：
+
+```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"
+
+# 或者直接用 DevTools CLI（跨平台兼容）
+./devtools.sh status      # 查看各服务端口状态
+./devtools.sh stop        # 停止 DevTools
+```
+
+### 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` | 端口被占用 | `./devtools.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` |