tian cfe42bdad3 Expose agent build metadata

2026-04-18 12:16:10 +08:00

11 KiB

Raw Blame History

设备端远程管理接口清单表（V1：对外 rk3588-agent；对内 media-server）

目标：供管理端（Go）与设备端联调对照。

约定：

对外：rk3588-agent HTTP 端口默认 9100（可配置），UDP 发现端口默认 35688。

对内：media-server 继续提供现有 /api/*（默认 9000），由 agent 本机调用。

0. 通用规范

0.1 基础 URL

Agent Base: http://<device_ip>:<agent_port>
Media-server Base（仅 agent 使用）: http://127.0.0.1:<media_port>

0.2 鉴权（agent 对外）

Header：X-RK-Token: <token>
必须鉴权：所有写接口（PUT/POST 会改变设备状态或写盘）
读接口：默认可不鉴权；若 agent.require_token_for_read=true 则也必须鉴权

0.3 统一响应格式

成功（通用）：{"ok":true}
失败（通用）：{"error":"<message>"}（与现有 ErrorJson() 风格一致）

0.4 统一错误码/HTTP 状态（agent 对外）

agent 不要求返回结构化 error_code（保持 {"error":...}），但要求 HTTP 状态码语义稳定：

场景	HTTP	error.message 示例
未鉴权/Token 错误/缺失	401	`unauthorized`
JSON 解析失败 / 字段缺失 / 校验失败	400	`invalid json: ...` / `validation failed: ...`
资源不存在	404	`not found`
方法不允许	405	`method not allowed`
冲突（如 node_id 不唯一等）	409	`... not unique ...`
写盘失败/内部异常/reload 崩溃性失败	500	`internal error: ...`
上传过大	413（推荐）或 400	`payload too large`

0.5 端口与协议

UDP 发现：35688/udp（可配置）
Agent HTTP：9100/tcp（默认，可配置）
Media-server HTTP：9000/tcp（默认，可配置）

1. UDP 发现协议（Option A）

1.1 Discover 请求（manager → broadcast）

发送目标：同网段广播地址 255.255.255.255:35688 或各网卡广播地址

数据格式：两行 UTF-8 文本

Line1（固定魔法串）：

RK3588SYS_DISCOVERY_V1

Line2（JSON）：

{"type":"discover","req_id":"<uuid>","reply_port":0}

字段：

type: 固定 discover
req_id: 管理端生成 UUID，用于匹配回复
reply_port: 保留字段（V1 可固定 0）

1.2 Discover 回复（device → manager 单播）

发送目标：请求报文 source ip:source port

两行文本：

Line1：

RK3588SYS_DISCOVERY_V1

Line2（JSON）：

{
  "type":"discover_reply",
  "req_id":"<uuid>",
  "device_id":"rk3588-...",
  "device_name":"rk3588-cam-01",
  "hostname":"rk3588",
  "ip":"10.0.0.21",
  "agent_port":9100,
  "media_port":9000,
  "version":"0.0.0-dev",
  "build_id":"20260418.141245",
  "build_type":"release",
  "git_sha":"e5894c2",
  "uptime_sec":12345
}

字段说明：

device_id: 稳定唯一（优先 /etc/machine-id，否则 MAC/序列号；最后 fallback 生成并落盘）
device_name: 可配置的人类可读名称（agent 配置 device_name）
agent_port: agent HTTP 端口
media_port: media-server HTTP 端口（用于调试/展示；管理端可不直连）

2. 设备信息（agent 对外）

2.1 `GET /v1/info`

用途：设备列表/详情页展示、联调确认端口/版本/配置路径。

Auth：读接口（见 0.2）

Response 200：

{
  "device_id":"rk3588-...",
  "device_name":"rk3588-cam-01",
  "hostname":"rk3588",
  "ip":"10.0.0.21",
  "agent_port":9100,
  "media_port":9000,
  "version":"0.0.0-dev",
  "build_id":"20260418.141245",
  "build_type":"release",
  "git_sha":"e5894c2",
  "config_path":"/etc/rk3588sys/config.json",
  "last_good_path":"/etc/rk3588sys/config.json.last_good.json",
  "uptime_sec":12345
}

失败：401/500 + {"error":"..."}

3. 配置下发（agent 对外）

3.1 `PUT /v1/config`

用途：管理端上传完整 root config（可含 templates/instances），agent 原子写盘后触发 media-server reload。

Auth：必须（401）

Headers：

Content-Type: application/json
X-RK-Token: ...

Body：root config JSON

agent 处理步骤（必须满足）：

解析 JSON（语法有效即可；语义校验交由 media-server reload）
原子写入 config_path
调用 media-server：POST /api/config/reload
若 reload 失败：调用 media-server：POST /api/config/rollback，并返回 500（包含 reload/rollback 错误信息）

Response 200：

{"ok":true}

失败：

400：JSON 解析失败
500：写盘失败 / reload 失败（已尝试 rollback）

4. 模型管理（agent 对外）

4.1 `PUT /v1/models/{name}`

用途：上传模型文件并落盘，维护 manifest，返回可引用的 path。

Auth：必须（401）

Path params：

name: string（建议仅允许 [A-Za-z0-9._-]，超出则 400）

Headers：

Content-Type: application/octet-stream
Content-Length: <n>（必须）
X-RK-Token: ...
X-Model-Sha256: <hex>（可选；若存在必须匹配实际 sha256，否则 400）

Body：二进制文件（建议限制扩展名白名单 .rknn；V1 可由 name 或内容类型控制）

Response 200：

{
  "ok": true,
  "name": "yolov5s-640",
  "sha256": "...",
  "path": "/opt/rk3588sys/models/files/yolov5s-640__abcd.rknn",
  "size": 12345678
}

失败：

400：缺 Content-Length / name 非法 / sha256 不匹配
413（推荐）或 400：超过 max_upload_mb
500：写盘失败/manifest 更新失败

4.2 `GET /v1/models`

用途：列出设备端已有模型。

Auth：读接口（见 0.2）

Response 200：

{
  "items": [
    {
      "name": "yolov5s-640",
      "sha256": "...",
      "path": "/opt/rk3588sys/models/files/...",
      "size": 123,
      "mtime_ms": 1730000000000
    }
  ]
}

失败：500 + {"error":"..."}

5. 业务图热更新/回滚（agent 对外）

5.1 `POST /v1/media-server/reload`

用途：触发本机 media-server POST /api/config/reload。

Auth：必须（401）

Response 200：{"ok":true}

失败：500 + {"error":"..."}

5.2 `POST /v1/media-server/rollback`

用途：触发本机 media-server POST /api/config/rollback。

Auth：必须（401）

Response 200：{"ok":true}

失败：500 + {"error":"..."}

5.3 `PUT /v1/media-server/configs/{name}`

用途：上传 media-server 配置文件到 agent.media_server_process.configs_dir。

Auth：必须（401）

Headers：

Content-Type: application/json
X-RK-Token: ...

Path params：

name: string（仅允许 [A-Za-z0-9._-]，禁止 /、\\、..；若无 .json 后缀则自动追加）

Body：media-server 配置 JSON

Response 200：

{
  "ok": true,
  "name": "cam1.json",
  "path": "/opt/rk3588sys/configs/cam1.json",
  "size": 1234,
  "mtime_ms": 1730000000000
}

失败：

400：name 非法 / Content-Type 非 application/json / JSON 无效 / 空 body
401：unauthorized
413：超过 max_upload_mb
501：configs_dir 未配置
500：写盘失败

5.4 `PUT /v1/media-server/binary`

用途：更新 media-server 可执行文件（仅允许在 media-server 未运行时覆盖）。

Auth：必须（401）

Headers：

Content-Type: application/octet-stream
Content-Length: <n>（必须）
X-RK-Token: ...
X-Binary-Sha256: <hex>（可选；若存在必须匹配实际 sha256，否则 400）

Body：二进制文件（media-server 可执行文件）

Response 200：

{
  "ok": true,
  "path": "/opt/rk3588sys/bin/media-server",
  "sha256": "...",
  "size": 12345678,
  "mtime_ms": 1730000000000,
  "backup_path": "/opt/rk3588sys/bin/media-server.bak.20260117-123000"
}

失败：

400：缺 Content-Length / Content-Type 非 application/octet-stream / sha256 不匹配
401：unauthorized
409：media-server 正在运行（需先 stop）
413：超过 max_upload_mb
501：未启用进程控制（agent 配置 agent.media_server_process.enable=false 或未配置）
500：写盘/替换失败

6. 主程序进程控制（agent 对外）

说明：该能力用于“启动/重启/关闭主程序（media-server）并选择加载哪个配置文件”。

agent 启动 media-server 时会显式传入：--config <resolved_config_path>，因此不依赖 media-server 内部默认配置。

路径说明：

agent.media_server_process 下的 exec_path/work_dir/configs_dir/pid_file 支持绝对或相对路径；若为相对路径，则以 agent 启动参数 --config <agent_config_path> 的配置文件所在目录为基准解析。

agent.config_path 建议使用绝对路径；若使用相对路径：

PUT /v1/config 写盘时，以 agent 进程当前工作目录（CWD） 为基准；

通过 /v1/media-server/start|restart（缺省 config）启动时，会把该相对路径原样传给 media-server，最终以 media_server_process.work_dir 为基准解析。

6.1 `POST /v1/media-server/start`

用途：启动本机 media-server（若已运行则幂等返回 ok；若已运行但 config 不同则 409）。

Auth：必须（401）

Body（可选，JSON）：

{"config":"cam1"}

说明：若请求 body 非空，则必须带 Content-Type: application/json；若 body 为空，可不带该 header。

config 解析规则：

为空/缺省：使用 agent.config_path
非空：只允许文件名/配置名（禁止包含 /、\\、..）；若不带扩展名自动补 .json；最终从 agent.media_server_process.configs_dir 下解析为 <configs_dir>/<config>.json

Response 200：

{"ok":true,"running":true,"pid":1234,"config_path":"/etc/rk3588sys/config.json"}

失败：

400：config 不合法 / config 文件不存在
409：已运行但 config 不同（提示使用 restart）
501：未启用进程控制（agent 配置 agent.media_server_process.enable=false 或未配置）
500：启动失败 / 写 pidfile 失败

6.2 `POST /v1/media-server/restart`

用途：重启本机 media-server（可切换 config）。

Auth：必须（401）

Body（可选，JSON）：

{"config":"cam1"}

说明：若请求 body 非空，则必须带 Content-Type: application/json；若 body 为空，可不带该 header。

Response 200：

{"ok":true,"running":true,"pid":1234,"config_path":"/home/orangepi/Desktop/OrangePi3588Media/configs/cam1.json"}

失败：

400：config 不合法 / config 文件不存在
501：未启用进程控制
500：停止/启动失败

6.3 `POST /v1/media-server/stop`

用途：停止本机 media-server（未运行也返回 ok）。

Auth：必须（401）

Response 200：

{"ok":true,"running":false,"pid":1234,"config_path":"/etc/rk3588sys/config.json"}

失败：

501：未启用进程控制
500：停止失败

6.4 `GET /v1/media-server/status`

用途：查询本机 media-server 是否在运行（以 agent 的 pidfile 记录为准）。

Auth：读接口（见 0.2）

Response 200：

{"ok":true,"running":true,"pid":1234,"config_path":"/etc/rk3588sys/config.json","version":"RK3588 Media Server v0.1.0 (git abc1234)"}

失败：

501：未启用进程控制
500：读取 pidfile/进程存活检测失败

7. 只读代理接口（agent 对外，推荐管理端统一走 agent）

7.1 `GET /v1/graphs`

代理 media-server：GET /api/graphs

7.2 `GET /v1/graphs/{name}`

代理 media-server：GET /api/graphs/{name}

7.3 `GET /v1/logs/recent?limit=200`

代理 media-server：GET /api/logs/recent?limit=...

11 KiB Raw Blame History Unescape Escape

设备端远程管理接口清单表（V1：对外 rk3588-agent；对内 media-server）

0. 通用规范

0.1 基础 URL

0.2 鉴权（agent 对外）

0.3 统一响应格式

0.4 统一错误码/HTTP 状态（agent 对外）

0.5 端口与协议

1. UDP 发现协议（Option A）

1.1 Discover 请求（manager → broadcast）

1.2 Discover 回复（device → manager 单播）

2. 设备信息（agent 对外）

2.1 GET /v1/info

3. 配置下发（agent 对外）

3.1 PUT /v1/config

4. 模型管理（agent 对外）

4.1 PUT /v1/models/{name}

4.2 GET /v1/models

5. 业务图热更新/回滚（agent 对外）

5.1 POST /v1/media-server/reload

5.2 POST /v1/media-server/rollback

5.3 PUT /v1/media-server/configs/{name}

5.4 PUT /v1/media-server/binary

6. 主程序进程控制（agent 对外）

6.1 POST /v1/media-server/start

6.2 POST /v1/media-server/restart

6.3 POST /v1/media-server/stop

6.4 GET /v1/media-server/status

7. 只读代理接口（agent 对外，推荐管理端统一走 agent）

7.1 GET /v1/graphs

7.2 GET /v1/graphs/{name}

7.3 GET /v1/logs/recent?limit=200

11 KiB

Raw Blame History

2.1 `GET /v1/info`

3.1 `PUT /v1/config`

4.1 `PUT /v1/models/{name}`

4.2 `GET /v1/models`

5.1 `POST /v1/media-server/reload`

5.2 `POST /v1/media-server/rollback`

5.3 `PUT /v1/media-server/configs/{name}`

5.4 `PUT /v1/media-server/binary`

6.1 `POST /v1/media-server/start`

6.2 `POST /v1/media-server/restart`

6.3 `POST /v1/media-server/stop`

6.4 `GET /v1/media-server/status`

7.1 `GET /v1/graphs`

7.2 `GET /v1/graphs/{name}`

7.3 `GET /v1/logs/recent?limit=200`