XuJiacheng
7ac3949dfa
重构项目心跳数据结构为Redis LIST，更新相关文档和OpenSpec规范。主要变更包括： - 将项目心跳从STRING改为LIST类型 - 更新后端服务以支持LIST操作 - 同步更新文档和OpenSpec规范 - 统一后端端口为3001 - 添加部署指南和Windows部署文档 修复前端API请求路径，移除硬编码的localhost地址。添加PM2和Nginx配置文件模板，完善部署流程文档。更新Redis集成协议文档，明确LIST数据结构和外部项目对接规范。
273 lines
6.3 KiB
Markdown
273 lines
6.3 KiB
Markdown
# Redis数据结构文档
|
||
|
||
## 概述
|
||
|
||
本文档详细说明了BLS Project Console中使用的Redis数据结构，包括新的统一项目列表结构和旧结构的迁移方案。
|
||
|
||
## 数据结构
|
||
|
||
### 1. 项目心跳列表（新结构）
|
||
|
||
**键名**: `项目心跳`
|
||
|
||
**类型**: List
|
||
|
||
**描述**: 统一存储所有项目的心跳信息，替代原有的分散键结构。
|
||
|
||
**数据格式**: 每个列表元素是一个 JSON 字符串，表示一条心跳记录：
|
||
|
||
```json
|
||
{
|
||
"projectName": "string",
|
||
"apiBaseUrl": "string",
|
||
"lastActiveAt": "number"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `projectName`: 项目名称（字符串）
|
||
- `apiBaseUrl`: 项目API基础URL（字符串）
|
||
- `lastActiveAt`: 最后活跃时间戳（毫秒，数字）
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"projectName": "用户管理系统",
|
||
"apiBaseUrl": "http://localhost:8080",
|
||
"lastActiveAt": 1704067200000
|
||
}
|
||
```
|
||
|
||
说明：外部项目会周期性向 LIST 写入多条心跳记录；控制台后端按 `projectName` 去重，保留 `lastActiveAt` 最新的一条用于在线判定与项目列表展示。
|
||
|
||
### 2. 项目控制台日志
|
||
|
||
**键名**: `{projectName}_项目控制台`
|
||
|
||
**类型**: List
|
||
|
||
**描述**: 存储项目的日志记录，使用Redis列表结构实现日志队列。
|
||
|
||
**数据格式**: 每个列表元素是一个JSON字符串，包含日志信息。
|
||
|
||
**日志对象格式**:
|
||
```json
|
||
{
|
||
"id": "string",
|
||
"timestamp": "ISO-8601 string",
|
||
"level": "string",
|
||
"message": "string",
|
||
"metadata": "object (optional)"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `id`: 日志唯一标识符
|
||
- `timestamp`: ISO-8601格式的时间戳
|
||
- `level`: 日志级别（info, warn, error, debug）
|
||
- `message`: 日志消息内容
|
||
- `metadata`: 可选的附加元数据
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"id": "log-1704067200000-abc123",
|
||
"timestamp": "2024-01-01T00:00:00.000Z",
|
||
"level": "info",
|
||
"message": "系统启动成功",
|
||
"metadata": {
|
||
"version": "1.0.0",
|
||
"environment": "production"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 项目控制指令
|
||
|
||
**键名**: `{projectName}_控制`
|
||
|
||
**类型**: List
|
||
|
||
**描述**: 历史结构（已废弃）。当前命令下发通过 HTTP 调用目标项目 API，不再通过 Redis 存储控制指令。
|
||
|
||
**指令对象格式**:
|
||
```json
|
||
{
|
||
"commandId": "string",
|
||
"timestamp": "ISO-8601 string",
|
||
"source": "string",
|
||
"apiName": "string",
|
||
"args": "array",
|
||
"argsText": "string",
|
||
"extraArgs": "object (optional)"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `commandId`: 指令唯一标识符
|
||
- `timestamp`: ISO-8601格式的时间戳
|
||
- `source`: 指令来源（如"BLS Project Console"）
|
||
- `apiName`: 目标API接口名称
|
||
- `args`: 指令参数数组
|
||
- `argsText`: 指令参数文本
|
||
- `extraArgs`: 可选的额外参数
|
||
|
||
**示例**:
|
||
```json
|
||
{
|
||
"commandId": "cmd-1704067200000-xyz789",
|
||
"timestamp": "2024-01-01T00:00:00.000Z",
|
||
"source": "BLS Project Console",
|
||
"apiName": "/api/reload",
|
||
"args": ["config"],
|
||
"argsText": "config",
|
||
"extraArgs": {
|
||
"force": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 项目心跳（旧结构，已废弃）
|
||
|
||
**键名**: `{projectName}_项目心跳`
|
||
|
||
**类型**: String (JSON对象)
|
||
|
||
**描述**: 旧的项目心跳数据结构，已迁移到统一的项目列表结构。
|
||
|
||
**注意**: 此结构已废弃，仅用于向后兼容。新项目应使用统一的`项目心跳`列表结构。
|
||
|
||
## 数据迁移
|
||
|
||
### 迁移工具
|
||
|
||
位置: `src/backend/services/migrateHeartbeatData.js`
|
||
|
||
### 迁移步骤
|
||
|
||
1. **准备阶段**
|
||
- 确保Redis服务正常运行
|
||
- 备份现有数据（可选）
|
||
|
||
2. **执行迁移**
|
||
```javascript
|
||
import { migrateHeartbeatData } from './services/migrateHeartbeatData.js';
|
||
|
||
// 干运行模式（不实际写入数据）
|
||
await migrateHeartbeatData({ dryRun: true });
|
||
|
||
// 实际迁移
|
||
await migrateHeartbeatData({ deleteOldKeys: false });
|
||
|
||
// 迁移并删除旧键
|
||
await migrateHeartbeatData({ deleteOldKeys: true });
|
||
```
|
||
|
||
3. **验证迁移**
|
||
- 检查`项目心跳`键是否包含所有项目
|
||
- 验证每个项目的数据完整性
|
||
- 测试项目选择和日志功能
|
||
|
||
### 迁移API
|
||
|
||
**端点**: `POST /api/projects/migrate`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"deleteOldKeys": false,
|
||
"dryRun": false
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `deleteOldKeys`: 是否删除旧的心跳键（默认: false）
|
||
- `dryRun`: 是否为干运行模式（默认: false）
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "数据迁移完成",
|
||
"migrated": 2,
|
||
"projects": [...],
|
||
"listKey": "项目心跳",
|
||
"deleteOldKeys": false
|
||
}
|
||
```
|
||
|
||
## 向后兼容性
|
||
|
||
为确保平滑过渡，系统在读取项目心跳时采用以下策略：
|
||
|
||
1. **只读取新结构**: 项目列表与在线判定只读取 `项目心跳`（LIST）
|
||
2. **旧结构仅用于迁移**: `{projectName}_项目心跳` 仅作为历史数据来源，通过 `POST /api/projects/migrate` 导入一次
|
||
|
||
## 性能优化
|
||
|
||
### 1. 项目列表查询
|
||
|
||
- 使用单一键存储所有项目，减少Redis查询次数
|
||
- 支持一次性获取所有项目信息
|
||
|
||
### 2. 日志轮询
|
||
|
||
- 使用Redis列表的`lRange`命令高效获取最新日志
|
||
- 支持限制返回的日志数量
|
||
|
||
### 3. 心跳更新
|
||
|
||
- 外部项目持续向 `项目心跳`（LIST）追加心跳记录
|
||
- 建议外部项目结合 `LTRIM` 控制列表长度
|
||
|
||
## 监控和维护
|
||
|
||
### 健康检查
|
||
|
||
定期检查以下指标：
|
||
- Redis连接状态
|
||
- 项目列表完整性
|
||
- 日志队列长度
|
||
|
||
### 清理策略
|
||
|
||
- 定期清理过期的日志记录
|
||
- 移除长时间未活跃的项目
|
||
- 清理已废弃的旧键
|
||
|
||
## 安全考虑
|
||
|
||
1. **访问控制**: 确保只有授权的应用可以写入心跳数据
|
||
2. **数据验证**: 验证心跳数据的格式和内容
|
||
3. **速率限制**: 限制心跳更新频率，防止滥用
|
||
|
||
## 故障排查
|
||
|
||
### 常见问题
|
||
|
||
1. **项目列表为空**
|
||
- 检查Redis连接
|
||
- 验证`项目心跳`键是否存在
|
||
- 检查数据格式是否正确
|
||
|
||
2. **日志不显示**
|
||
- 确认项目名称正确
|
||
- 检查`{projectName}_项目控制台`键是否存在
|
||
- 验证日志数据格式
|
||
|
||
3. **命令发送失败**
|
||
- 检查项目是否在线
|
||
- 验证API地址是否正确
|
||
- 确认目标项目是否正常运行
|
||
|
||
## 版本历史
|
||
|
||
- **v2.0** (2024-01-13): 引入统一的项目列表结构
|
||
- **v1.0** (初始版本): 使用分散的项目心跳键
|
||
|
||
## 参考资料
|
||
|
||
- [Redis数据类型](https://redis.io/docs/data-types/)
|
||
- [项目OpenSpec规范](../openspec/specs/)
|
||
- [API文档](../docs/api-documentation.md)
|