Web_BLS_ProjectConsole/docs/redis-data-structure.md

Redis数据结构文档

概述

本文档详细说明了BLS Project Console中使用的Redis数据结构，包括新的统一项目列表结构和旧结构的迁移方案。

数据结构

1. 项目心跳列表（新结构）

键名: 项目心跳

类型: List

描述: 统一存储所有项目的心跳信息，替代原有的分散键结构。

数据格式: 每个列表元素是一个 JSON 字符串，表示一条心跳记录：

{
  "projectName": "string",
  "apiBaseUrl": "string",
  "lastActiveAt": "number"
}

字段说明:

• projectName: 项目名称（字符串）
• apiBaseUrl: 项目API基础URL（字符串）
• lastActiveAt: 最后活跃时间戳（毫秒，数字）

示例:

{
  "projectName": "用户管理系统",
  "apiBaseUrl": "http://localhost:8080",
  "lastActiveAt": 1704067200000
}

说明：外部项目会周期性向 LIST 写入多条心跳记录；控制台后端按 projectName 去重，保留 lastActiveAt 最新的一条用于在线判定与项目列表展示。

2. 项目控制台日志

键名: {projectName}_项目控制台

类型: List

描述: 存储项目的日志记录，使用Redis列表结构实现日志队列。

数据格式: 每个列表元素是一个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: 可选的附加元数据

示例:

{
  "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 存储控制指令。

指令对象格式:

{
  "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: 可选的额外参数

示例:

{
  "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. 执行迁移

   import { migrateHeartbeatData } from './services/migrateHeartbeatData.js';
   
   // 干运行模式（不实际写入数据）
   await migrateHeartbeatData({ dryRun: true });
   
   // 实际迁移
   await migrateHeartbeatData({ deleteOldKeys: false });
   
   // 迁移并删除旧键
   await migrateHeartbeatData({ deleteOldKeys: true });
   

3. 验证迁移

   • 检查项目心跳键是否包含所有项目
   • 验证每个项目的数据完整性
   • 测试项目选择和日志功能

迁移API

端点: POST /api/projects/migrate

请求体:

{
  "deleteOldKeys": false,
  "dryRun": false
}

参数说明:

• deleteOldKeys: 是否删除旧的心跳键（默认: false）
• dryRun: 是否为干运行模式（默认: false）

响应:

{
  "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数据类型
• 项目OpenSpec规范
• API文档