OrangePi3588Media/docs/Agent_API_Extensions.md

Agent 新增接口说明（供远程运维工具对接）

说明：本文件仅覆盖本次新增/扩展的 agent 接口与返回字段，不包含已有接口的完整文档。

通用

• 鉴权：需要 X-RK-Token（写操作必需；读操作依配置而定）。
• 返回：统一 JSON。

1) 指标接口

GET /v1/metrics

用途：资源/进程运行指标（JSON）。

响应示例（字段可能随平台略有不同）：

{
  "timestamp_ms": 1710000000000,
  "uptime_sec": 12345,
  "cpu": {"usage_pct": 12.3, "sample_ms": 1000, "total_ticks": 123, "idle_ticks": 45},
  "memory": {"total_kb": 1024000, "available_kb": 512000, "free_kb": 128000, "buffers_kb": 64000, "cached_kb": 256000},
  "load_avg": {"one": 0.12, "five": 0.20, "fifteen": 0.30},
  "disk": {"path": "/", "total_bytes": 1000000, "free_bytes": 200000, "used_bytes": 800000, "used_pct": 80},
  "disk_io": {"read_bytes": 123456, "write_bytes": 654321},
  "net": {"rx_bytes": 111, "tx_bytes": 222},
  "media_server": {"supported": true, "running": true, "pid": 1234, "config_path": "/path", "started_at_ms": 1710000000000, "uptime_sec": 120}
}

2) 版本与资产

GET /v1/versions

用途：版本信息与二进制/模型清单。

响应示例：

{
  "agent": {
    "version": "0.0.0-dev",
    "build_id": "20260418.141245",
    "build_type": "release",
    "git_sha": "...",
    "binary": {"path": "...", "sha256": "...", "size": 123, "mtime_ms": 1710000000000}
  },
  "media_server": {
    "supported": true,
    "version": "...",
    "binary": {"path": "...", "sha256": "...", "size": 456, "mtime_ms": 1710000000000}
  },
  "models": {
    "count": 2,
    "items": [{"name": "yolo", "sha256": "...", "path": "...", "size": 123, "mtime_ms": 1710000000000}]
  }
}

GET /v1/assets

用途：资产详情（配置、二进制、模型清单）。

响应示例：

{
  "agent_binary": {"path": "...", "sha256": "...", "size": 123, "mtime_ms": 1710000000000},
  "config": {"path": "...", "sha256": "...", "size": 456, "mtime_ms": 1710000000000},
  "config_last_good": {"path": "...", "sha256": "...", "size": 456, "mtime_ms": 1710000000000},
  "media_server_binary": {"path": "...", "sha256": "...", "size": 789, "mtime_ms": 1710000000000},
  "models": {"items": [...]}
}

3) 任务状态查询

GET /v1/tasks/{id}

用途：查询异步/长耗时任务状态。

响应示例：

{
  "id": "...",
  "type": "media_binary_update",
  "status": "success",
  "started_at_ms": 1710000000000,
  "ended_at_ms": 1710000001000,
  "error": "",
  "result": {"path": "...", "sha256": "..."}
}

4) media-server 二进制回滚

POST /v1/media-server/binary/rollback

用途：使用备份文件回滚 media-server 可执行文件。

请求体：

{ "backup_path": "/path/to/media-server.bak.20250101-120000" }

响应示例：

{
  "ok": true,
  "path": "...",
  "sha256": "...",
  "size": 123,
  "mtime_ms": 1710000000000,
  "backup_path": "...",
  "task_id": "..."
}

5) 关键接口新增字段

• /v1/media-server/status、/v1/media-server/start、/v1/media-server/restart、/v1/media-server/stop
  • 新增字段：started_at_ms

6) 操作审计（服务端日志）

• 审计日志（JSONL）默认落盘：{baseDir}/logs/agent_audit.jsonl
• 覆盖操作：配置更新/应用、模型上传、media-server 启停与更新/回滚、face_gallery 更新与 reload 等