XuJiacheng
282f7268ed
- 新增统一项目列表Redis键和迁移工具 - 实现GET /api/projects端点获取项目列表 - 实现POST /api/projects/migrate端点支持数据迁移 - 更新前端ProjectSelector组件使用真实项目数据 - 扩展projectStore状态管理 - 更新相关文档和OpenSpec规范 - 添加测试用例验证新功能
137 lines
4.0 KiB
Markdown
137 lines
4.0 KiB
Markdown
# 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：
|
||
|
||
```json
|
||
{
|
||
"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（字段尽量保持稳定，便于控制台解析）：
|
||
|
||
```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. 命令下发方式（HTTP API 控制）
|
||
|
||
控制台不再通过 Redis 写入控制指令队列；改为由 BLS Project Console 后端根据目标项目心跳里的 `apiBaseUrl` 直接调用目标项目 HTTP API。
|
||
|
||
### 3.1 控制台输入格式
|
||
|
||
一行文本按空格拆分：
|
||
|
||
- 第一个 token：`apiName`（接口名/路径片段）
|
||
- 剩余 token：参数列表（字符串数组）
|
||
|
||
示例：
|
||
|
||
- `reload`
|
||
- `reload force`
|
||
- `user/refreshCache tenantA`
|
||
|
||
### 3.2 目标项目需要提供的 API
|
||
|
||
后端默认使用 `POST` 调用：
|
||
|
||
- `POST {apiBaseUrl}/{apiName}`
|
||
|
||
请求体（JSON）示例：
|
||
|
||
```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 地址信息。
|