232 lines
10 KiB
Markdown
232 lines
10 KiB
Markdown
# PRD ① 设备端（rk3588-agent + media-server）远程管理能力（V1）
|
||
|
||
## 1. 背景
|
||
当前 `media-server` 已提供 HTTP 控制台与配置热更新能力（`/api/*`、`/api/config/reload`、`/api/config/rollback` 等）。由于 **大文件模型上传** 在现有 C++ 自研 HTTP Server 上实现成本较高（需要流式接收/写盘/校验/限流），本期采用更工程化的拆分：
|
||
|
||
- `media-server`：继续专注业务图（推理/推流/报警）与热更新。
|
||
- `rk3588-agent`（Go 新增常驻进程）：对外提供局域网管理面能力：UDP 发现、模型/配置上传落盘、触发 `media-server` reload/rollback、代理读取 graphs/logs。
|
||
|
||
> 本 PRD 覆盖“轻量热更新/重载/回滚（业务图级）”。systemd/重启系统等运维级操作可作为后续扩展，但不作为 V1 验收项。
|
||
|
||
## 2. 目标
|
||
1. 管理端可通过 UDP 广播在 1 秒内发现同网段 10 台设备（由 `rk3588-agent` 响应）。
|
||
2. 管理端可通过 `rk3588-agent` 上传配置 JSON，设备端原子写入后触发 `media-server` reload 生效。
|
||
3. 管理端可通过 `rk3588-agent` 上传模型文件到设备固定目录，并返回可直接在配置中引用的 `model_path`。
|
||
4. 所有对外写操作必须鉴权（Token），读操作默认可不鉴权（可配置）。
|
||
|
||
## 3. 非目标（V1 不做）
|
||
- systemd start/stop/restart `media-server`（可在 agent 后续扩展）
|
||
- 设备重启/固件升级/插件升级
|
||
- 跨网段发现（保留后端可做网段扫描 fallback）
|
||
- 完整 RBAC/用户体系
|
||
|
||
## 4. 现状可复用能力（不修改语义）
|
||
- HTTP Server：`src/http_server.cpp`
|
||
- Graph/热更新：`GraphManager::ReloadFromFile`、`GraphManager::RollbackFromLastGood`
|
||
- 配置 Expand + Validate：`utils/config_expand.*`、`utils/config_schema.h`
|
||
- 运行状态：`GET /api/graphs`、`GET /api/graphs/{name}`、`GET /api/logs/recent`
|
||
|
||
## 5. 新增功能范围（V1）
|
||
|
||
### 5.1 新增进程：rk3588-agent（Go）
|
||
`rk3588-agent` 作为常驻服务，提供：
|
||
|
||
- UDP 广播发现（Option A）：对管理端 Search 做响应。
|
||
- HTTP 管理 API（对外）：模型上传、配置下发、触发 reload/rollback、代理 graphs/logs。
|
||
- 本地调用 `media-server`：通过 `http://127.0.0.1:<media_port>/api/...` 触发 reload/rollback/读取 graphs/logs。
|
||
|
||
#### 5.1.1 agent 代码目录结构（建议，开发可直接照此建工程）
|
||
建议以 Go module 形式独立工程（可放在同仓库 `agent/` 目录，也可独立仓库）。
|
||
|
||
```text
|
||
agent/
|
||
go.mod
|
||
cmd/
|
||
rk3588-agent/
|
||
main.go
|
||
internal/
|
||
config/ # 读取/校验 /etc/rk3588-agent/config.json
|
||
discovery/ # UDP 35688 discover responder
|
||
httpapi/ # 对外 HTTP 路由：/v1/* + auth
|
||
mediaserver/ # 对内 HTTP client：调用 127.0.0.1:9000/api/*
|
||
modelstore/ # 模型落盘/sha256/manifest
|
||
files/ # 原子写盘（tmp+rename）、权限校验
|
||
sysinfo/ # hostname/ip/uptime/device_id
|
||
log/ # 统一日志封装（stdout/journald）
|
||
```
|
||
|
||
### 5.2 media-server 变更范围（V1）
|
||
V1 目标是将大文件上传从 `media-server` 移出，因此 **media-server 可不新增大文件上传接口**。仅要求：
|
||
|
||
- 保持现有 `/api/config/reload`、`/api/config/rollback`、`/api/graphs`、`/api/logs/recent` 等接口可用。
|
||
- （可选安全加固，非 V1 必须）限制 `media-server` HTTP 仅监听 `127.0.0.1` 或对写接口增加 Token 鉴权。
|
||
|
||
## 6. 配置与落盘约定
|
||
|
||
### 6.1 新增 agent 配置项（建议）
|
||
agent 需要独立配置（例如 `/etc/rk3588-agent/config.json`）。建议：
|
||
|
||
```json
|
||
{
|
||
"agent": {
|
||
"listen": "0.0.0.0:9100",
|
||
"token": "CHANGE_ME",
|
||
"require_token_for_read": false,
|
||
"discovery_enable": true,
|
||
"discovery_port": 35688,
|
||
"device_name": "rk3588-cam-01",
|
||
"device_id_path": "/var/lib/rk3588-agent/device_id",
|
||
"models_dir": "/opt/rk3588sys/models",
|
||
"max_upload_mb": 200,
|
||
"config_path": "/etc/rk3588sys/config.json",
|
||
"media_server_base_url": "http://127.0.0.1:9000",
|
||
"media_server_timeout_ms": 3000,
|
||
"media_server_retry": { "max_attempts": 3, "backoff_ms": [200, 500] }
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明（V1 关键字段）：
|
||
- `config_path`：agent 写入配置文件的目标路径（与 media-server `--config` 一致）。
|
||
- `device_id_path`：device_id 持久化文件路径（不存在则自动生成并写入）。
|
||
- `media_server_base_url`：agent 调用 media-server 的本机地址，建议固定 `127.0.0.1`。
|
||
- `media_server_timeout_ms`：agent 调用 media-server 的 HTTP 总超时。
|
||
- `media_server_retry`：仅对“控制类请求”（reload/rollback）启用的重试策略。
|
||
|
||
### 6.2 设备侧文件系统布局（部署约定）
|
||
为保证权限与可维护性，约定如下路径：
|
||
|
||
- 可执行文件：
|
||
- `/opt/rk3588sys/bin/media-server`
|
||
- `/opt/rk3588sys/agent/rk3588-agent`
|
||
- 配置文件：
|
||
- `/etc/rk3588sys/config.json`（media-server `--config` 指向）
|
||
- `/etc/rk3588-agent/config.json`
|
||
- 状态/持久化：
|
||
- `/var/lib/rk3588-agent/device_id`
|
||
- 模型仓库：
|
||
- `/opt/rk3588sys/models/manifest.json`
|
||
- `/opt/rk3588sys/models/files/*.rknn`
|
||
|
||
> 说明：如不希望以 root 运行，可将 `config_path` 改到 `/opt/rk3588sys/config/config.json` 并给 agent 用户写权限；V1 为减少权限复杂度，建议 agent 以 root 运行。
|
||
|
||
### 6.3 systemd service（部署字段，开发/运维可直接照抄）
|
||
|
||
#### 6.3.1 rk3588-agent.service
|
||
路径建议：`/etc/systemd/system/rk3588-agent.service`
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=RK3588Sys Agent
|
||
After=network-online.target
|
||
Wants=network-online.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=root
|
||
ExecStart=/opt/rk3588sys/agent/rk3588-agent --config /etc/rk3588-agent/config.json
|
||
Restart=always
|
||
RestartSec=2
|
||
WorkingDirectory=/
|
||
LimitNOFILE=65535
|
||
|
||
# 可选：基础加固（需要确认路径）
|
||
NoNewPrivileges=true
|
||
PrivateTmp=true
|
||
ProtectHome=true
|
||
ProtectSystem=full
|
||
ReadWritePaths=/etc/rk3588sys /etc/rk3588-agent /opt/rk3588sys/models /var/lib/rk3588-agent
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
#### 6.3.2 media-server.service（建议统一纳入部署约定）
|
||
路径建议：`/etc/systemd/system/media-server.service`
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=RK3588Sys Media Server
|
||
After=network-online.target
|
||
Wants=network-online.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=root
|
||
ExecStart=/opt/rk3588sys/bin/media-server --config /etc/rk3588sys/config.json
|
||
Restart=always
|
||
RestartSec=2
|
||
LimitNOFILE=65535
|
||
|
||
# （可选）性能调参：多路推理并发 / RGA 并发
|
||
Environment=RK3588_RKNN_CTX_POOL_SIZE=3
|
||
Environment=RK3588_RGA_MAX_INFLIGHT=2
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
> V1 不要求 agent 控制 systemd，但要求两服务可开机自启。
|
||
|
||
### 6.5 性能调参说明（新增）
|
||
- `RK3588_RKNN_CTX_POOL_SIZE`：同一模型的 RKNN context 池大小（默认 3）。
|
||
- `RK3588_RGA_MAX_INFLIGHT`：RGA 全局并发上限（默认 2）。
|
||
|
||
### 6.4 模型目录结构
|
||
- `${models_dir}/manifest.json`
|
||
- `${models_dir}/files/<name>__<sha256>.<ext>`（`ext` 默认 `rknn`，白名单控制）
|
||
|
||
## 7. 约束与安全
|
||
- agent 对外写接口必须 `X-RK-Token`。
|
||
- 上传限制：必须 `Content-Length`；大小不得超过 `max_upload_mb`。
|
||
- agent 写盘采用原子写（临时文件 + rename）。
|
||
- agent 与 `media-server` 的本地通信固定走 `127.0.0.1`（避免暴露内部控制面）。
|
||
|
||
### 7.1 agent 内部调用 media-server 的 URL/超时/重试策略
|
||
agent 只调用 media-server 的既有接口（对内 base URL = `media_server_base_url`）：
|
||
|
||
- Reload：`POST {base}/api/config/reload`
|
||
- Rollback：`POST {base}/api/config/rollback`
|
||
- Graphs：`GET {base}/api/graphs`
|
||
- Graph detail：`GET {base}/api/graphs/{name}`
|
||
- Logs：`GET {base}/api/logs/recent?limit=...`
|
||
|
||
超时策略（建议默认值）：
|
||
- 读接口（graphs/logs）：总超时 `1000ms`（不重试）
|
||
- 控制接口（reload/rollback）：总超时 `media_server_timeout_ms`（默认 `3000ms`），允许重试
|
||
|
||
重试策略（仅控制接口）：
|
||
- `max_attempts = 3`（首次 + 2 次重试）
|
||
- 触发条件：连接失败/超时/5xx（不对 4xx 重试）
|
||
- backoff：`[200ms, 500ms]`
|
||
|
||
配置下发联动策略（`PUT /v1/config`）：
|
||
1) agent 原子写入 `config_path`
|
||
2) 调用 reload（按控制接口重试策略）
|
||
3) 若 reload 最终失败：调用 rollback（按控制接口重试策略）
|
||
4) 返回 500，错误消息包含 reload 与 rollback 的结果（便于定位）
|
||
|
||
### 7.2 启动顺序与可用性
|
||
- 建议 systemd 启动顺序：两者都 After network-online。
|
||
- agent 对外可先起来；当 media-server 尚未启动时：
|
||
- `/v1/graphs`、`/v1/logs/recent` 返回 500（error=connect refused/timeout）
|
||
- `/v1/config` 返回 500（写盘可成功，但 reload 失败会触发 rollback；错误信息提示 media-server 不可用）
|
||
|
||
## 8. 验收标准（Acceptance Criteria）
|
||
1. 同网段 10 台设备，管理端 Search（UDP broadcast）在 1 秒内都能发现；列表包含 `device_id/ip/agent_port/media_port/version/git_sha`。
|
||
2. agent `PUT /v1/config`：
|
||
- 发送合法 config，设备写盘并触发 `media-server` reload 成功，graphs 状态正常。
|
||
- 发送非法 config，agent 返回 400；或 reload 失败则 agent 自动 rollback 并返回 500（错误信息可定位）。
|
||
3. agent `PUT /v1/models/{name}`：上传成功返回 sha256/path；在配置中引用该 path 并 reload 后，相关节点能正常 Init（以日志/metrics 验证）。
|
||
4. 无 token 调用写接口返回 401；错误返回 JSON：`{"error":"..."}`。
|
||
|
||
## 9. 开发任务拆分（建议）
|
||
- [ ] 新增 `rk3588-agent`：HTTP 服务 + Token 鉴权 + 日志
|
||
- [ ] UDP discovery：协议解析/回复、device_id 获取与持久化、停止逻辑
|
||
- [ ] `GET /v1/info`：聚合 device/version/git_sha/ports/uptime
|
||
- [ ] `PUT /v1/config`：原子写盘 + 触发 `media-server` reload；失败自动 rollback
|
||
- [ ] `PUT /v1/models/{name}`：流式落盘 + sha256 + manifest 写入
|
||
- [ ] `GET /v1/models`：读取 manifest
|
||
- [ ] 代理接口：graphs、graph detail、logs recent、reload、rollback
|
||
- [ ] 统一错误码与日志（见接口清单表）
|