111 lines
3.8 KiB
Markdown
111 lines
3.8 KiB
Markdown
|
# 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（字段尽量保持稳定，便于控制台解析）：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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）”的显式确认方式，可使用兼容模式：
|
|||
|
|
> 1) `LRANGE ${projectName}_控制 0 0` 读取 1 条
|
|||
|
|
> 2) 处理成功后执行 `LTRIM ${projectName}_控制 1 -1` 修剪已消费元素
|
|||
|
|
|
|||
|
|
value：**JSON 对象**（在 Redis 中以 JSON 字符串形式存储）。
|
|||
|
|
|
|||
|
|
推荐 JSON Schema：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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 Console`
|
|||
|
|
- `command`：命令名称或命令文本
|
|||
|
|
- `args`：可选对象参数
|
|||
|
|
|
|||
|
|
## 4. 兼容与错误处理建议
|
|||
|
|
|
|||
|
|
- JSON 解析失败：外部项目应记录错误，并丢弃该条消息（避免死循环阻塞消费）。
|
|||
|
|
- 消息过长：建议控制单条消息大小（例如 < 64KB）。
|
|||
|
|
- 字符编码：统一 UTF-8。
|
|||
|
|
|
|||
|
|
## 5. 与本项目代码的对应关系（实现中）
|
|||
|
|
|
|||
|
|
后端通过 `/api/commands` 将命令写入 `${targetProjectName}_控制`；通过 `/api/logs` 读取 `${projectName}_项目控制台`（以仓库当前实现为准）。
|