AskaEth
7eb5e984c2
- 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>
243 lines
7.9 KiB
Markdown
243 lines
7.9 KiB
Markdown
# Cyrene DevTools 文档
|
||
|
||
DevTools 是 Cyrene 项目的开发管理控制台，提供 Web UI + CLI 两种使用方式。默认端口 **9090**。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [CLI 命令 (devtools.sh)](#1-cli-命令)
|
||
2. [Web 控制台面板](#2-web-控制台面板)
|
||
3. [REST API](#3-rest-api)
|
||
|
||
---
|
||
|
||
## 1. CLI 命令
|
||
|
||
`./devtools.sh [命令] [选项]`
|
||
|
||
### 基本命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `start` | 启动 DevTools 控制台 |
|
||
| `start --build` | 编译全部后端服务后启动 |
|
||
| `start --fresh` | 强制重启全部后端服务后启动 |
|
||
| `stop` | 停止 DevTools 控制台 |
|
||
| `status` | 查看所有服务状态（运行/停止、PID、uptime） |
|
||
| `logs <服务ID> [行数]` | 查看服务日志 |
|
||
| `build [服务ID]` | 编译服务（不指定则编译全部） |
|
||
| `db:start` | 启动 Docker 数据库容器 |
|
||
| `db:stop` | 停止 Docker 数据库容器 |
|
||
| `db:status` | 检查数据库连接状态 |
|
||
| `help` | 显示帮助 |
|
||
|
||
### 选项
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--port, -p <端口>` | 指定 DevTools 端口 (默认: 9090) |
|
||
| `--fresh` | 启动前强制重启全部后端服务 |
|
||
| `--build` | 启动前编译全部服务 |
|
||
|
||
### 可用服务 ID
|
||
|
||
`gateway`, `ai-core`, `memory-service`, `tool-engine`, `voice-service`, `iot-debug-service`, `plugin-manager`, `platform-bridge`, `frontend`
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
./devtools.sh # 快速启动
|
||
./devtools.sh start --build # 编译后启动
|
||
./devtools.sh start --fresh # 全新重启
|
||
./devtools.sh logs gateway 20 # 查看 Gateway 最近 20 行日志
|
||
./devtools.sh build ai-core # 仅编译 AI-Core
|
||
./devtools.sh db:status # 检查数据库状态
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Web 控制台面板
|
||
|
||
`http://localhost:9090` — 左侧导航栏共 14 个面板。
|
||
|
||
### 2.1 仪表盘 (Dashboard)
|
||
|
||
首页总览：服务运行数、活跃会话数、消息总数、记忆总数、数据库状态、系统资源占用。5 秒自动刷新 + WebSocket 实时推送。
|
||
|
||
### 2.2 记忆管理 (Memory)
|
||
|
||
对 Memory-Service 的 CRUD 操作。支持搜索、添加、删除记忆，按 `user_id` 筛选。
|
||
|
||
### 2.3 会话监看 (Sessions)
|
||
|
||
查看所有活跃会话，按用户分组，查看消息历史，支持多端客户端列表。
|
||
|
||
### 2.4 服务管理 (Services)
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| 一键启动 | 按依赖顺序启动全部 9 个服务 |
|
||
| 强制重启 | 先停止全部再重新启动 |
|
||
| 单个启动/停止/重启 | 针对每个服务的独立操作 |
|
||
| 编译 | 重新编译 Go 服务并启动 |
|
||
|
||
启动顺序：memory-service → tool-engine → plugin-manager → iot-debug-service → voice-service → ai-core → platform-bridge → gateway → frontend。每步等待健康检查通过。
|
||
|
||
### 2.5 性能监控 (Performance)
|
||
|
||
实时 CPU / 内存 使用率，每个服务独立监控，历史曲线图表，定期采集 pidusage。
|
||
|
||
### 2.6 IoT 设备 (IoT Devices)
|
||
|
||
代理到 `iot-debug-service`，管理 8 个模拟设备：
|
||
- 卧室设备：灯、空调、温度传感器、湿度传感器
|
||
- 客厅设备：灯、空调、窗帘
|
||
- 安防设备：智能门锁
|
||
|
||
支持开关切换、属性设置、操作历史查询。WebSocket 实时推送状态变更。
|
||
|
||
### 2.7 工具调用 (Tool Calls)
|
||
|
||
代理到 `tool-engine`，查询工具调用记录和统计数据，按工具名筛选。
|
||
|
||
### 2.8 语音识别 (STT)
|
||
|
||
STT 转录日志（内存环形缓冲，最多 200 条），支持上传音频文件转录并记录处理时长、识别结果。
|
||
|
||
### 2.9 数据库监看 (Database)
|
||
|
||
检查 PostgreSQL / Redis / Qdrant / MinIO / NATS 端口状态，执行 Docker Compose 管理（启动/停止/重启），查询 PostgreSQL 记忆表行数。
|
||
|
||
### 2.10 自主思考 (Thinking)
|
||
|
||
代理到 `memory-service`，查看后台自主思考日志，支持按 `user_id` 筛选。
|
||
|
||
### 2.11 记忆时间线 (Timeline)
|
||
|
||
合并记忆 + 思考日志为统一时间线，按时间降序排列。
|
||
|
||
### 2.12 第三方聊天 (Chat Platforms)
|
||
|
||
代理到 `platform-bridge`，管理 QQ / Telegram 等平台的 Bot 配置和消息日志。
|
||
|
||
### 2.13 客户端管理 (Clients)
|
||
|
||
代理到 Gateway，查看所有已知客户端（设备名、UA、在线状态、备注），支持设置备注。
|
||
|
||
### 2.14 模型配置 (Model Config)
|
||
|
||
代理到 Gateway Admin API，管理多模型配置系统：
|
||
|
||
| 子标签 | 说明 |
|
||
|--------|------|
|
||
| Providers | LLM 服务商配置（API URL、Key、超时等） |
|
||
| Models | 模型定义（名称、Provider、参数、优先级、标签） |
|
||
| Routing | 路由规则（用途 → 模型回退链） |
|
||
|
||
---
|
||
|
||
## 3. REST API
|
||
|
||
DevTools 自身暴露的 REST API，供脚本和外部工具使用。
|
||
|
||
### 健康检查
|
||
|
||
```
|
||
GET /api/health
|
||
→ { "status": "ok", "service": "cyrene-devtools", "uptime": 3600, "wsClients": 2 }
|
||
```
|
||
|
||
### 服务管理
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/services` | 所有服务状态 |
|
||
| GET | `/api/services/:id` | 单个服务状态 |
|
||
| POST | `/api/services/:id/start` | 启动服务 |
|
||
| POST | `/api/services/:id/stop` | 停止服务 |
|
||
| POST | `/api/services/:id/restart` | 重启服务 |
|
||
| POST | `/api/services/:id/build` | 编译服务 |
|
||
| POST | `/api/services/start-all` | 按序启动全部 |
|
||
| POST | `/api/services/start-all-fresh` | 强制重启全部 |
|
||
| POST | `/api/services/stop-all` | 停止全部 |
|
||
|
||
### 仪表盘
|
||
|
||
```
|
||
GET /api/dashboard
|
||
→ { services, performance, sessions, memory, database, system }
|
||
```
|
||
|
||
### 日志
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/logs/:id` | 最近 N 行 (`?lines=200&offset=0`) |
|
||
| GET | `/api/logs/:id/recent` | 最近 100 行 |
|
||
| DELETE | `/api/logs/:id` | 清空日志 |
|
||
|
||
### 数据库
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/database/status` | 端口检查 + 记忆表行数 |
|
||
| GET | `/api/db/status` | 简单在线状态 |
|
||
| POST | `/api/db/start` | docker compose up |
|
||
| POST | `/api/db/stop` | docker compose down |
|
||
| POST | `/api/db/restart` | docker compose down + up |
|
||
|
||
### 代理路由 (均需 Gateway 在线)
|
||
|
||
所有代理路由自动获取 Gateway JWT Token（通过 admin 凭据登录并缓存）。
|
||
|
||
| DevTools 路径 | 目标服务 | 实际路径 |
|
||
|---------------|----------|----------|
|
||
| `/api/memory/*` | Gateway | `/api/v1/memory/*` |
|
||
| `/api/sessions*` | Gateway | `/api/v1/admin/sessions*` |
|
||
| `/api/clients*` | Gateway | `/api/v1/admin/clients*` |
|
||
| `/api/model-config/*` | Gateway | `/api/v1/admin/models/*` |
|
||
| `/api/iot/devices*` | IoT Debug | `/api/v1/devices*` |
|
||
| `/api/tool-calls*` | Tool-Engine | `/api/v1/tools/calls*` |
|
||
| `/api/voice/status` | Voice-Service | `/api/v1/status` |
|
||
| `/api/voice/transcribe` | Voice-Service | `/api/v1/transcribe` |
|
||
| `/api/voice/logs` | DevTools 内部 | 内存环形缓冲区 |
|
||
| `/api/v1/thinking*` | Memory-Service | `/api/v1/thinking*` |
|
||
| `/api/memory-timeline` | Memory-Service | 合并 Memories + Thinking |
|
||
| `/api/chat-platforms/*` | Platform-Bridge | `/api/v1/*` |
|
||
| `/api/proxy/:id/health` | 各服务 | 健康检查 |
|
||
|
||
### 性能监控
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/performance` | 当前性能快照 |
|
||
| GET | `/api/performance/dashboard` | 仪表盘聚合数据 |
|
||
| GET | `/api/performance/history` | 所有服务历史 |
|
||
| GET | `/api/performance/:id` | 单个服务历史 |
|
||
| GET | `/api/performance/:id/summary` | 汇总统计 |
|
||
|
||
### WebSocket
|
||
|
||
```
|
||
ws://localhost:9090/ws
|
||
```
|
||
|
||
实时推送类型：`log`（服务日志）、`status`（服务状态变更）、`stt-log`（STT 处理日志）。
|
||
|
||
---
|
||
|
||
## 服务全览
|
||
|
||
| 服务 ID | 名称 | 端口 | 类型 |
|
||
|---------|------|------|------|
|
||
| `gateway` | Gateway | 8080 | Go |
|
||
| `ai-core` | AI-Core | 8081 | Go |
|
||
| `iot-debug-service` | IoT Debug | 8083 | Go |
|
||
| `memory-service` | 记忆服务 | 8091 | Go |
|
||
| `tool-engine` | 工具引擎 | 8092 | Go |
|
||
| `voice-service` | 语音识别服务 | 8093 | Go |
|
||
| `plugin-manager` | 插件管理器 | 8094 | Go |
|
||
| `platform-bridge` | 多平台桥接 | 8095 | Go |
|
||
| `frontend` | Frontend | 5173 | Vite |
|