66 lines
1.6 KiB
Markdown
66 lines
1.6 KiB
Markdown
|
## Context
|
|||
|
|
|
|||
|
|
命令下发从 Redis 队列模式迁移为 HTTP API 调用模式。
|
|||
|
|
|
|||
|
|
约束：
|
|||
|
|
|
|||
|
|
- 输入约定来自 UI：用户输入一行文本，按空格拆分。
|
|||
|
|
- 需要通过 `targetProjectName` 将命令路由到目标项目的 `baseUrl`。
|
|||
|
|
|
|||
|
|
## Goals / Non-Goals
|
|||
|
|
|
|||
|
|
- Goals
|
|||
|
|
- 控制台通过后端统一出站调用目标项目 API（避免浏览器跨域/鉴权差异）
|
|||
|
|
- 统一请求格式，便于目标项目实现与观测
|
|||
|
|
- 明确失败行为（目标项目不可达/超时/非 2xx）
|
|||
|
|
|
|||
|
|
- Non-Goals
|
|||
|
|
- 不定义目标项目内部如何执行命令
|
|||
|
|
- 不在本次变更中引入鉴权体系（如需后续可另开 change）
|
|||
|
|
|
|||
|
|
## Decision: baseUrl mapping via env JSON
|
|||
|
|
|
|||
|
|
改为由目标项目的 Redis 心跳模块提供 `apiBaseUrl`。
|
|||
|
|
|
|||
|
|
### Heartbeat key
|
|||
|
|
|
|||
|
|
- Redis key: `${projectName}_项目心跳`
|
|||
|
|
- Redis type: STRING
|
|||
|
|
- Value: JSON string
|
|||
|
|
|
|||
|
|
示例：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"apiBaseUrl": "http://127.0.0.1:4001",
|
|||
|
|
"lastActiveAt": 1760000000000
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Liveness rule
|
|||
|
|
|
|||
|
|
- 目标项目应每 3 秒刷新一次 `lastActiveAt`（毫秒时间戳）
|
|||
|
|
- 若后端检测到 `now - lastActiveAt > 10_000`，则视为离线并拒绝下发
|
|||
|
|
|
|||
|
|
## Decision: request shape
|
|||
|
|
|
|||
|
|
- UI 输入：`<apiName> <arg1> <arg2> ...`
|
|||
|
|
- 后端对目标项目调用：默认 `POST ${baseUrl}/${apiName}`
|
|||
|
|
- body（JSON）：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"commandId": "cmd-...",
|
|||
|
|
"timestamp": "ISO-8601",
|
|||
|
|
"source": "BLS Project Console",
|
|||
|
|
"apiName": "reload",
|
|||
|
|
"args": ["a", "b"],
|
|||
|
|
"argsText": "a b"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Timeouts / retries
|
|||
|
|
|
|||
|
|
- 单次请求设置合理超时（例如 5s）。
|
|||
|
|
- 默认不重试（避免重复执行产生副作用）；如需重试需目标项目提供幂等语义。
|