XuJiacheng
910f1c353f
- 新增Redis集成模块，支持心跳写入与控制台日志队列 - 优化Kafka消费者实现，支持多实例与自动重连 - 改进消息处理器，支持批量处理与多层解码 - 更新数据库表结构，调整字段类型与约束 - 添加Redis与Kafka的配置项和环境变量支持 - 补充测试用例和文档说明
3.9 KiB
3.9 KiB
Redis 对接协议（供 AI 生成代码使用）
本文档定义“外部项目 ↔ BLS Project Console”之间通过 Redis 交互的 Key 命名、数据类型、写入方式、读取方式与数据格式。
约束：每个需要关联本控制台的外部项目，必须在本项目使用的同一个 Redis 实例中：
- 写入 2 个 Key（心跳 + 控制台信息）
- 命令下发为 HTTP API 调用
1. 命名约定
令：
projectName：外部项目名称（建议只用字母数字下划线A-Za-z0-9_；如使用中文也可，但需保证统一且 UTF-8）。
固定后缀：
- 心跳：
${projectName}_项目心跳 - 控制台：
${projectName}_项目控制台
示例（projectName = 订单系统）：
订单系统_项目心跳订单系统_项目控制台
2. 外部项目需要写入的 2 个 Key
2.1 ${projectName}_项目心跳
- Redis 数据类型：STRING
- 写入方式：
SET ${projectName}_项目心跳 <json> - value：JSON 字符串，必须包含目标项目可被调用的
apiBaseUrl，以及活跃时间戳lastActiveAt
推荐 JSON Schema：
{
"apiBaseUrl": "http://127.0.0.1:4001",
"lastActiveAt": 1760000000000
}
字段说明：
apiBaseUrl：目标项目对外提供的 API 地址（基地址，后端将基于它拼接apiName）lastActiveAt：状态时间（活跃时间戳，毫秒）。建议每 3 秒刷新一次。
在线/离线判定（BLS Project Console 使用）：
- 若
now - lastActiveAt > 10_000ms，则认为该应用 离线 - 否则认为 在线
建议：
lastActiveAt使用Date.now()生成（毫秒）- 可设置 TTL（可选）：例如
SET key value EX 30
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. 命令下发方式（HTTP API 控制）
控制台不再通过 Redis 写入控制指令队列；改为由 BLS Project Console 后端根据目标项目心跳里的 apiBaseUrl 直接调用目标项目 HTTP API。
3.1 控制台输入格式
一行文本按空格拆分：
- 第一个 token：
apiName（接口名/路径片段） - 剩余 token：参数列表（字符串数组）
示例：
reloadreload forceuser/refreshCache tenantA
3.2 目标项目需要提供的 API
后端默认使用 POST 调用：
POST {apiBaseUrl}/{apiName}
请求体（JSON）示例：
{
"commandId": "cmd-1700000000000-abc123",
"timestamp": "2026-01-13T00:00:00.000Z",
"source": "BLS Project Console",
"apiName": "reload",
"args": ["force"],
"argsText": "force"
}
返回建议：
- 2xx 表示成功
- 非 2xx 表示失败（控制台会展示 upstreamStatus 与部分返回内容）
4. 兼容与错误处理建议
- JSON 解析失败：外部项目应记录错误，并丢弃该条消息（避免死循环阻塞消费）。
- 消息过长：建议控制单条消息大小（例如 < 64KB）。
- 字符编码：统一 UTF-8。
5. 与本项目代码的对应关系（实现中）
- 后端通过
/api/commands：从${targetProjectName}_项目心跳读取apiBaseUrl与lastActiveAt，在线时调用目标项目 API。 - 后端通过
/api/logs：读取${projectName}_项目控制台；并基于${projectName}_项目心跳返回在线/离线与 API 地址信息。