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