158 lines
4.9 KiB
Markdown
158 lines
4.9 KiB
Markdown
# PRD ③ 管理端后端（Go managerd）V1
|
||
|
||
## 1. 目标与运行方式
|
||
- 提供本机 HTTP API 给 React UI 使用。
|
||
- 负责 UDP 广播发现（Option A），维护设备缓存与在线状态。
|
||
- 通过设备端 `rk3588-agent` 完成配置/模型等运维操作，并可通过 agent 代理读取 graphs/logs。
|
||
- 支持批量任务（并发、进度、失败原因）并通过 SSE 推送。
|
||
|
||
运行：单可执行 `managerd`，默认监听 `127.0.0.1:18080`（可配置）。
|
||
|
||
## 2. 外部依赖与约束
|
||
- Go 版本：>= 1.22（建议）
|
||
- 标准库优先；Web 框架可选 `chi`/`gin`（建议 chi + net/http）。
|
||
- 不需要数据库（V1 用内存 + 可选本地 JSON 持久化）。
|
||
|
||
## 3. 模块划分
|
||
|
||
### 3.1 Discovery
|
||
- 向所有可用网卡的广播地址发送 UDP discover。
|
||
- 监听本地 UDP socket 收集 replies（时间窗默认 1200ms）。
|
||
- 去重规则：按 `device_id` 去重，以最新 reply 为准。
|
||
|
||
### 3.2 Device Registry
|
||
- 内存缓存：
|
||
- `device_id -> {ip, agent_port, media_port, device_name, version, git_sha, last_seen_ms, online}`
|
||
- 定时刷新（可配置间隔）：对 online 设备拉取 `GET /v1/graphs`（agent 代理），更新摘要。
|
||
- Offline 规则：超过 `offline_after_ms`（如 10000ms）未见到，则标记离线。
|
||
|
||
### 3.3 Device Client
|
||
- 统一超时：connect 1s、overall 3s（可配置）。
|
||
- 统一错误包装：返回 `error_code + message + device_id`。
|
||
- Token：
|
||
- 全局默认 token（V1）
|
||
- 可预留 per-device token（P1）
|
||
|
||
### 3.4 Templates/Config Builder
|
||
- 模板库来源：
|
||
- V1：managerd 内置（embed）或本地 `templates/` 目录读取
|
||
- 返回前端表单 schema：V1 允许手工维护（避免解析占位符带来的不确定性）。
|
||
- 生成 root config：基于模板与 params，产出 `{global,templates,instances}`。
|
||
|
||
### 3.5 Task Runner
|
||
- 任务类型：
|
||
- `config_apply`（对 N 台设备下发 config）
|
||
- `reload`
|
||
- `rollback`
|
||
- `model_upload`（V1 可先做单设备；批量后续）
|
||
- 并发控制：默认 5（可配置）。
|
||
- 状态：`pending/running/success/failed`（逐设备与整体）。
|
||
- 推送：SSE `GET /api/tasks/:id/events`。
|
||
|
||
## 4. managerd 对前端 API 规格（V1）
|
||
|
||
### 4.1 Discovery
|
||
#### `POST /api/discovery/search`
|
||
Request:
|
||
```json
|
||
{ "timeout_ms": 1200 }
|
||
```
|
||
Response:
|
||
```json
|
||
{ "items": [ {"device_id":"...","ip":"...","agent_port":9100,"media_port":9000,"device_name":"...","version":"...","git_sha":"..."} ] }
|
||
```
|
||
|
||
### 4.2 Devices
|
||
#### `GET /api/devices`
|
||
Response:
|
||
```json
|
||
{ "items": [ {"device_id":"...","online":true,"last_seen_ms":0,"ip":"...","agent_port":9100,"media_port":9000,"device_name":"...","version":"...","git_sha":"...","graphs":[...]} ] }
|
||
```
|
||
|
||
#### `GET /api/devices/:id`
|
||
Response：包含 `info`、`graphs_summary`、`last_seen`。
|
||
|
||
### 4.3 Device actions（代理调用）
|
||
以下全部通过 agent：
|
||
- `POST /api/devices/:id/reload` → agent `POST /v1/media-server/reload`
|
||
- `POST /api/devices/:id/rollback` → agent `POST /v1/media-server/rollback`
|
||
- `GET /api/devices/:id/graphs` → agent `GET /v1/graphs`
|
||
- `GET /api/devices/:id/graphs/:name` → agent `GET /v1/graphs/{name}`
|
||
- `GET /api/devices/:id/logs?limit=200` → agent `GET /v1/logs/recent?limit=200`
|
||
|
||
### 4.4 Config apply
|
||
#### `POST /api/devices/:id/config/apply`
|
||
Request:
|
||
```json
|
||
{ "config": { } }
|
||
```
|
||
Behavior：调用 agent `PUT /v1/config`。
|
||
|
||
### 4.5 Model upload
|
||
#### `POST /api/devices/:id/models/upload`
|
||
Request：`multipart/form-data`，字段：
|
||
- `name`: string
|
||
- `file`: binary
|
||
|
||
Behavior：读取文件流，转发为 agent `PUT /v1/models/{name}`（raw body）。
|
||
|
||
### 4.6 Templates
|
||
- `GET /api/templates`
|
||
- `GET /api/templates/:name`
|
||
|
||
### 4.7 Tasks
|
||
#### `POST /api/tasks`
|
||
Request:
|
||
```json
|
||
{
|
||
"type": "config_apply",
|
||
"device_ids": ["..."],
|
||
"payload": { "config": {} }
|
||
}
|
||
```
|
||
Response:
|
||
```json
|
||
{ "task_id": "..." }
|
||
```
|
||
|
||
#### `GET /api/tasks/:id/events` (SSE)
|
||
Event `device_update` data:
|
||
```json
|
||
{ "device_id":"...","status":"running|success|failed","progress":0.0,"error":"" }
|
||
```
|
||
|
||
## 5. 错误处理规范（managerd → 前端）
|
||
- 成功：2xx + `{"ok":true}` 或正常业务 JSON
|
||
- 失败：4xx/5xx +
|
||
```json
|
||
{ "error": { "code": "...", "message": "...", "device_id": "...", "detail": "..." } }
|
||
```
|
||
|
||
建议错误码：
|
||
- `DISCOVERY_FAILED`
|
||
- `DEVICE_NOT_FOUND`
|
||
- `DEVICE_OFFLINE`
|
||
- `DEVICE_HTTP_ERROR`
|
||
- `DEVICE_TIMEOUT`
|
||
- `TASK_NOT_FOUND`
|
||
- `VALIDATION_ERROR`
|
||
|
||
## 6. 配置文件（managerd）建议
|
||
`managerd.json`：
|
||
```json
|
||
{
|
||
"listen": "127.0.0.1:18080",
|
||
"discovery_port": 35688,
|
||
"discovery_timeout_ms": 1200,
|
||
"offline_after_ms": 10000,
|
||
"agent_token": "CHANGE_ME",
|
||
"concurrency": 5
|
||
}
|
||
```
|
||
|
||
## 7. 验收标准
|
||
1. Search 可发现设备并更新 registry；离线判断正确。
|
||
2. 可通过 agent 读取 graphs/logs（`GET /v1/graphs`、`GET /v1/logs/recent`）。
|
||
3. 单设备 `config/apply`、`reload`、`rollback` 可用，错误可定位。
|
||
4. 批量 `config_apply` 任务可并发执行并通过 SSE 输出逐台结果。
|