feat: 重构项目心跳为Redis LIST并更新相关文档
重构项目心跳数据结构为Redis LIST，更新相关文档和OpenSpec规范。主要变更包括： - 将项目心跳从STRING改为LIST类型 - 更新后端服务以支持LIST操作 - 同步更新文档和OpenSpec规范 - 统一后端端口为3001 - 添加部署指南和Windows部署文档 修复前端API请求路径，移除硬编码的localhost地址。添加PM2和Nginx配置文件模板，完善部署流程文档。更新Redis集成协议文档，明确LIST数据结构和外部项目对接规范。
This commit is contained in:
@@ -1,12 +1,13 @@
|
||||
# Redis 对接协议（供外部项目 AI 生成代码使用）
|
||||
|
||||
本文档定义“外部项目 ↔ BLS Project Console”之间通过 Redis 交互的 **Key 命名、数据类型、写入方式、读取方式与数据格式**。
|
||||
本文档定义"外部项目 ↔ BLS Project Console"之间通过 Redis 交互的 **Key 命名、数据类型、写入方式、读取方式与数据格式**。
|
||||
|
||||
注：本仓库对外暴露的 Redis 连接信息如下（供对方直接连接以写入心跳/日志）：
|
||||
|
||||
- 地址：`10.8.8.109`
|
||||
- 端口：默认 `6379`
|
||||
- 密码：无（空）
|
||||
- 数据库：固定 `15`
|
||||
|
||||
示例（环境变量）：
|
||||
|
||||
@@ -14,18 +15,20 @@
|
||||
REDIS_HOST=10.8.8.109
|
||||
REDIS_PORT=6379
|
||||
REDIS_PASSWORD=
|
||||
REDIS_DB=15
|
||||
```
|
||||
|
||||
示例（redis-cli）：
|
||||
|
||||
```
|
||||
redis-cli -h 10.8.8.109 -p 6379
|
||||
```
|
||||
redis-cli -h 10.8.8.109 -p 6379 -n 15
|
||||
```
|
||||
|
||||
> 约束：每个需要关联本控制台的外部项目，必须在本项目使用的同一个 Redis 实例中：
|
||||
> 约束：每个需要关联本控制台的外部项目，必须在同一个 Redis（DB15）中：
|
||||
|
||||
> - 写入 2 个 Key（心跳 + 控制台信息）
|
||||
> - 命令下发为 HTTP API 调用
|
||||
> - 更新 `项目心跳`（项目列表 + 心跳信息）
|
||||
> - 追加 `${projectName}_项目控制台`（日志队列）
|
||||
> - 命令下发为 HTTP API 调用（不通过 Redis 下发命令）
|
||||
|
||||
## 1. 命名约定
|
||||
|
||||
@@ -35,35 +38,45 @@ redis-cli -h 10.8.8.109 -p 6379
|
||||
|
||||
固定后缀：
|
||||
|
||||
- 心跳：`${projectName}_项目心跳`
|
||||
- 控制台：`${projectName}_项目控制台`
|
||||
|
||||
示例（projectName = `订单系统`）：
|
||||
|
||||
- `订单系统_项目心跳`
|
||||
- `订单系统_项目控制台`
|
||||
|
||||
## 2. 外部项目需要写入的 2 个 Key
|
||||
|
||||
### 2.1 `${projectName}_项目心跳`
|
||||
说明：当前控制台左侧“项目选择列表”只读取 `项目心跳`（LIST）。因此外部项目必须维护该 Key，否则项目不会出现在列表中。
|
||||
|
||||
- Redis 数据类型：**STRING**
|
||||
- 写入方式：`SET ${projectName}_项目心跳 <json>`
|
||||
- value：JSON 字符串，必须包含目标项目可被调用的 `apiBaseUrl`，以及活跃时间戳 `lastActiveAt`
|
||||
### 2.1 `项目心跳`
|
||||
|
||||
推荐 JSON Schema：
|
||||
- Redis 数据类型：**LIST**
|
||||
- 写入方式（推荐 FIFO）：`RPUSH 项目心跳 <json>`
|
||||
- value：每个列表元素为“项目心跳记录”的 JSON 字符串
|
||||
|
||||
示例（与当前代码读取一致；下面示例表示“逻辑结构”）：
|
||||
|
||||
```json
|
||||
{
|
||||
"apiBaseUrl": "http://127.0.0.1:4001",
|
||||
"lastActiveAt": 1760000000000
|
||||
}
|
||||
[
|
||||
{
|
||||
"projectName": "BLS主机心跳日志",
|
||||
"apiBaseUrl": "http://127.0.0.1:3000",
|
||||
"lastActiveAt": 1768566165572
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
字段说明：
|
||||
示例（Redis 写入命令）：
|
||||
|
||||
```
|
||||
RPUSH 项目心跳 "{\"projectName\":\"BLS主机心跳日志\",\"apiBaseUrl\":\"http://127.0.0.1:3000\",\"lastActiveAt\":1768566165572}"
|
||||
```
|
||||
|
||||
字段说明（每条心跳记录）：
|
||||
|
||||
- `projectName`：项目名称（用于拼接日志 Key：`${projectName}_项目控制台`）
|
||||
- `apiBaseUrl`：目标项目对外提供的 API 地址（基地址，后端将基于它拼接 `apiName`）
|
||||
- `lastActiveAt`：状态时间（活跃时间戳，毫秒）。建议每 **3 秒**刷新一次。
|
||||
- `lastActiveAt`：活跃时间戳（毫秒）。建议每 **3 秒**刷新一次。
|
||||
|
||||
在线/离线判定（BLS Project Console 使用）：
|
||||
|
||||
@@ -73,14 +86,19 @@ redis-cli -h 10.8.8.109 -p 6379
|
||||
建议：
|
||||
|
||||
- `lastActiveAt` 使用 `Date.now()` 生成（毫秒）
|
||||
- 可设置 TTL（可选）：例如 `SET key value EX 30`
|
||||
- 建议对 `项目心跳` 做长度控制（可选）：例如每次写入后执行 `LTRIM 项目心跳 -2000 -1` 保留最近 2000 条
|
||||
|
||||
去重提示：
|
||||
|
||||
- `项目心跳` 为 LIST 时，外部项目周期性 `RPUSH` 会产生多条重复记录
|
||||
- BLS Project Console 后端会按 `projectName` 去重，保留 `lastActiveAt` 最新的一条作为项目状态
|
||||
|
||||
### 2.2 `${projectName}_项目控制台`
|
||||
|
||||
- Redis 数据类型：**LIST**（作为项目向控制台追加的“消息队列/日志队列”）
|
||||
- Redis 数据类型：**LIST**（作为项目向控制台追加的"消息队列/日志队列"）
|
||||
- 写入方式（推荐 FIFO）：`RPUSH ${projectName}_项目控制台 <json>`
|
||||
|
||||
value（推荐格式）：一条 JSON 字符串，表示“错误/调试信息”或日志记录。
|
||||
value（推荐格式）：一条 JSON 字符串，表示"错误/调试信息"或日志记录。
|
||||
|
||||
推荐 JSON Schema（字段尽量保持稳定，便于控制台解析）：
|
||||
|
||||
@@ -103,11 +121,39 @@ value（推荐格式）：一条 JSON 字符串，表示“错误/调试信息
|
||||
- `message`：日志文本
|
||||
- `metadata`：可选对象（附加信息）
|
||||
|
||||
## 3. 命令下发方式（HTTP API 控制）
|
||||
## 3. 项目列表管理（重要）
|
||||
|
||||
控制台不再通过 Redis 写入控制指令队列；改为由 BLS Project Console 后端根据目标项目心跳里的 `apiBaseUrl` 直接调用目标项目 HTTP API。
|
||||
### 3.1 项目列表结构
|
||||
|
||||
### 3.1 控制台输入格式
|
||||
`项目心跳` 为 LIST，列表元素为 JSON 字符串；其“逻辑结构”如下：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"projectName": "订单系统",
|
||||
"apiBaseUrl": "http://127.0.0.1:4001",
|
||||
"lastActiveAt": 1760000000000
|
||||
},
|
||||
{
|
||||
"projectName": "用户服务",
|
||||
"apiBaseUrl": "http://127.0.0.1:4002",
|
||||
"lastActiveAt": 1760000000001
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 3.2 外部项目对接建议
|
||||
|
||||
外部项目应当：
|
||||
|
||||
1. 定期写入 `项目心跳`（RPUSH 自己的心跳记录；允许产生多条记录，由控制台按 projectName 去重）
|
||||
2. 追加 `${projectName}_项目控制台` 日志
|
||||
|
||||
## 4. 命令下发方式（HTTP API 控制）
|
||||
|
||||
由 BLS Project Console 后端根据目标项目心跳里的 `apiBaseUrl` 直接调用目标项目 HTTP API。
|
||||
|
||||
### 4.1 控制台输入格式
|
||||
|
||||
一行文本按空格拆分：
|
||||
|
||||
@@ -120,7 +166,7 @@ value（推荐格式）：一条 JSON 字符串，表示“错误/调试信息
|
||||
- `reload force`
|
||||
- `user/refreshCache tenantA`
|
||||
|
||||
### 3.2 目标项目需要提供的 API
|
||||
### 4.2 目标项目需要提供的 API
|
||||
|
||||
后端默认使用 `POST` 调用：
|
||||
|
||||
@@ -139,18 +185,69 @@ value（推荐格式）：一条 JSON 字符串，表示“错误/调试信息
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
- `commandId`：唯一命令标识符
|
||||
- `timestamp`：命令发送时间（ISO-8601 格式）
|
||||
- `source`：命令来源标识
|
||||
- `apiName`：API 接口名
|
||||
- `args`：参数数组
|
||||
- `argsText`：参数文本（空格连接）
|
||||
|
||||
返回建议：
|
||||
|
||||
- 2xx 表示成功
|
||||
- 非 2xx 表示失败（控制台会展示 upstreamStatus 与部分返回内容）
|
||||
|
||||
## 4. 兼容与错误处理建议
|
||||
### 4.3 在线/离线判定
|
||||
|
||||
发送命令前，系统会检查项目在线状态：
|
||||
|
||||
- 从 `项目心跳` 列表读取 `lastActiveAt`
|
||||
- 若 `now - lastActiveAt > 10_000ms`，则认为该应用 **离线**，拒绝发送命令
|
||||
- 否则认为 **在线**，允许发送命令
|
||||
|
||||
## 5. 与本项目代码的对应关系
|
||||
|
||||
- **后端 `/api/projects`**：只从 `项目心跳`（LIST）读取项目列表，返回所有项目及其在线状态
|
||||
- **后端 `/api/commands`**：从 `项目心跳` 中查找目标项目的 `apiBaseUrl/lastActiveAt`，在线时调用目标项目 API
|
||||
- **后端 `/api/logs`**：读取 `${projectName}_项目控制台`（LIST）；并基于 `项目心跳` 中该项目的 `lastActiveAt` 计算在线/离线与 API 地址信息
|
||||
|
||||
## 6. 兼容与错误处理建议
|
||||
|
||||
- JSON 解析失败：外部项目应记录错误，并丢弃该条消息（避免死循环阻塞消费）。
|
||||
- 消息过长：建议控制单条消息大小（例如 < 64KB）。
|
||||
- 字符编码：统一 UTF-8。
|
||||
- 心跳超时：建议外部项目每 3 秒更新一次心跳，避免被误判为离线。
|
||||
|
||||
## 5. 与本项目代码的对应关系（实现中）
|
||||
## 7. 数据迁移工具（旧数据导入）
|
||||
|
||||
- 后端通过 `/api/commands`：从 `${targetProjectName}_项目心跳` 读取 `apiBaseUrl` 与 `lastActiveAt`，在线时调用目标项目 API。
|
||||
- 后端通过 `/api/logs`：读取 `${projectName}_项目控制台`；并基于 `${projectName}_项目心跳` 返回在线/离线与 API 地址信息。
|
||||
如果需要从旧格式迁移到新格式，可使用以下 API：
|
||||
|
||||
```bash
|
||||
POST /api/projects/migrate
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"deleteOldKeys": false,
|
||||
"dryRun": false
|
||||
}
|
||||
```
|
||||
|
||||
参数说明：
|
||||
|
||||
- `deleteOldKeys`：是否删除旧格式键（默认 false）
|
||||
- `dryRun`：是否仅模拟运行（默认 false）
|
||||
|
||||
返回示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "数据迁移完成",
|
||||
"migrated": 2,
|
||||
"projects": [...],
|
||||
"listKey": "项目心跳",
|
||||
"deleteOldKeys": false
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user