refactor: DevTools → ethend 重命名 + 加入生产环境

- 目录 devtools/ → ethend/ - CLI 脚本 devtools.sh/.bat → ethend.sh/.bat - 环境变量 DEVTOOLS_PORT → ETHEND_PORT - docker-compose.yml 新增 ethend 服务（生产部署） - 同步更新全部文档、注释和配置文件 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-30 09:32:36 +08:00
parent 27187997b3
commit 365f5ceb2f
30 changed files with 455 additions and 189 deletions
@@ -0,0 +1,241 @@
+# Cyrene ethend 文档
+
+ethend 是 Cyrene 项目的开发管理控制台，提供 Web UI + CLI 两种使用方式。默认端口 **9090**。
+
+---
+
+## 目录
+
+1. [CLI 命令 (ethend.sh)](#1-cli-命令)
+2. [Web 控制台面板](#2-web-控制台面板)
+3. [REST API](#3-rest-api)
+
+---
+
+## 1. CLI 命令
+
+`./ethend.sh [命令] [选项]`
+
+### 基本命令
+
+| 命令 | 说明 |
+|------|------|
+| `start` | 启动 ethend 控制台 |
+| `start --build` | 编译全部后端服务后启动 |
+| `start --fresh` | 强制重启全部后端服务后启动 |
+| `stop` | 停止 ethend 控制台 |
+| `status` | 查看所有服务状态（运行/停止、PID、uptime） |
+| `logs <服务ID> [行数]` | 查看服务日志 |
+| `build [服务ID]` | 编译服务（不指定则编译全部） |
+| `db:start` | 启动 Docker 数据库容器 |
+| `db:stop` | 停止 Docker 数据库容器 |
+| `db:status` | 检查数据库连接状态 |
+| `help` | 显示帮助 |
+
+### 选项
+
+| 选项 | 说明 |
+|------|------|
+| `--port, -p <端口>` | 指定 ethend 端口 (默认: 9090) |
+| `--fresh` | 启动前强制重启全部后端服务 |
+| `--build` | 启动前编译全部服务 |
+
+### 可用服务 ID
+
+`gateway`, `ai-core`, `memory-service`, `voice-service`, `iot-debug-service`, `plugin-manager`, `platform-bridge`, `frontend`
+
+### 示例
+
+```bash
+./ethend.sh                           # 快速启动
+./ethend.sh start --build             # 编译后启动
+./ethend.sh start --fresh             # 全新重启
+./ethend.sh logs gateway 20           # 查看 Gateway 最近 20 行日志
+./ethend.sh build ai-core             # 仅编译 AI-Core
+./ethend.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)
+
+| 操作 | 说明 |
+|------|------|
+| 一键启动 | 按依赖顺序启动全部 8 个服务 |
+| 强制重启 | 先停止全部再重新启动 |
+| 单个启动/停止/重启 | 针对每个服务的独立操作 |
+| 编译 | 重新编译 Go 服务并启动 |
+
+启动顺序：memory-service → 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)
+
+代理到 `ai-core`，查询工具调用记录和统计数据，按工具名筛选、分页。
+
+### 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
+
+ethend 自身暴露的 REST API，供脚本和外部工具使用。
+
+### 健康检查
+
+```
+GET /api/health
+→ { "status": "ok", "service": "cyrene-ethend", "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 凭据登录并缓存）。
+
+| ethend 路径 | 目标服务 | 实际路径 |
+|---------------|----------|----------|
+| `/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*` | AI-Core | `/api/v1/tools/calls*` |
+| `/api/voice/status` | Voice-Service | `/api/v1/status` |
+| `/api/voice/transcribe` | Voice-Service | `/api/v1/transcribe` |
+| `/api/voice/logs` | ethend 内部 | 内存环形缓冲区 |
+| `/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 |
+| `voice-service` | 语音识别服务 | 8093 | Go |
+| `plugin-manager` | 插件管理器 | 8094 | Go |
+| `platform-bridge` | 多平台桥接 | 8095 | Go |
+| `frontend` | Frontend | 5173 | Vite |