XuJiacheng
19e65d78dc
refactor(backend): 重构后端服务以支持Redis协议 feat(backend): 添加Redis客户端和服务模块 feat(backend): 实现命令和日志路由处理Redis交互 refactor(frontend): 重构前端状态管理和组件结构 feat(frontend): 实现基于Redis的日志和命令功能 docs: 添加Redis集成协议文档 chore: 更新ESLint配置和依赖
3.8 KiB
3.8 KiB
Redis 对接协议（供外部项目 AI 生成代码使用）
本文档定义“外部项目 ↔ BLS Project Console”之间通过 Redis 交互的 Key 命名、数据类型、写入方式、读取方式与数据格式。
约束：每个需要关联本控制台的外部项目，必须在本项目使用的同一个 Redis 实例中：
- 写入 2 个 Key（状态 + 控制台信息）
- 读取 1 个 Key（控制指令队列）
1. 命名约定
令：
projectName：外部项目名称（建议只用字母数字下划线A-Za-z0-9_；如使用中文也可，但需保证统一且 UTF-8）。
固定后缀：
- 状态：
${projectName}_项目状态 - 控制台：
${projectName}_项目控制台 - 控制：
${projectName}_控制
示例（projectName = 订单系统）：
订单系统_项目状态订单系统_项目控制台订单系统_控制
2. 外部项目需要写入的 2 个 Key
2.1 ${projectName}_项目状态
- Redis 数据类型：STRING
- 写入方式：
SET ${projectName}_项目状态 <status> - value：状态枚举（必须为以下之一）
在线离线故障报错
建议（非强制）：
- 定期刷新（如 5~30 秒）
- 可设置 TTL 防止僵尸在线（如
SET key value EX 60）
2.2 ${projectName}_项目控制台
- Redis 数据类型：LIST（作为项目向控制台追加的“消息队列/日志队列”）
- 写入方式（推荐 FIFO）：
RPUSH ${projectName}_项目控制台 <json>
value（推荐格式）：一条 JSON 字符串，表示“错误/调试信息”或日志记录。
推荐 JSON Schema（字段尽量保持稳定，便于控制台解析）：
{
"timestamp": "2026-01-12T12:34:56.789Z",
"level": "info",
"message": "连接成功",
"metadata": {
"module": "redis",
"host": "127.0.0.1"
}
}
字段说明：
timestamp：ISO-8601 时间字符串level：建议取值info|warn|error|debug（小写）message：日志文本metadata：可选对象（附加信息）
3. 外部项目需要读取的 1 个 Key（控制指令）
3.1 ${projectName}_控制
- Redis 数据类型：LIST（控制台向目标项目下发的“命令队列”）
- 队列模式（必须）：Redis List 队列（生产
RPUSH，消费BLPOP；必要时配合LTRIM） - 控制台写入方式（FIFO）：
RPUSH ${targetProjectName}_控制 <json> - 外部项目读取方式（阻塞消费，推荐）：
BLPOP ${projectName}_控制 0
说明：
BLPOP本身会原子性地“取出并移除”队列头元素，通常不需要额外LTRIM。 如果你的运行环境/客户端库无法可靠使用BLPOP，或你希望采用“读取 + 修剪（LTRIM）”的显式确认方式，可使用兼容模式：
LRANGE ${projectName}_控制 0 0读取 1 条- 处理成功后执行
LTRIM ${projectName}_控制 1 -1修剪已消费元素
value：JSON 对象（在 Redis 中以 JSON 字符串形式存储）。
推荐 JSON Schema：
{
"id": "cmd-1700000000000-abc123",
"timestamp": "2026-01-12T12:35:00.000Z",
"source": "BLS Project Console",
"command": "reload",
"args": {
"force": true
}
}
字段说明：
id：命令唯一 ID（用于追踪）timestamp：命令下发时间source：固定可写BLS Project Consolecommand：命令名称或命令文本args：可选对象参数
4. 兼容与错误处理建议
- JSON 解析失败：外部项目应记录错误，并丢弃该条消息（避免死循环阻塞消费）。
- 消息过长：建议控制单条消息大小（例如 < 64KB）。
- 字符编码：统一 UTF-8。
5. 与本项目代码的对应关系（实现中）
后端通过 /api/commands 将命令写入 ${targetProjectName}_控制；通过 /api/logs 读取 ${projectName}_项目控制台（以仓库当前实现为准）。