114 lines
3.4 KiB
Markdown
114 lines
3.4 KiB
Markdown
# Agent 新增接口说明（供远程运维工具对接）
|
||
|
||
> 说明：本文件仅覆盖本次新增/扩展的 agent 接口与返回字段，不包含已有接口的完整文档。
|
||
|
||
## 通用
|
||
- 鉴权：需要 `X-RK-Token`（写操作必需；读操作依配置而定）。
|
||
- 返回：统一 JSON。
|
||
|
||
## 1) 指标接口
|
||
### GET `/v1/metrics`
|
||
**用途**：资源/进程运行指标（JSON）。
|
||
|
||
**响应示例**（字段可能随平台略有不同）：
|
||
```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`
|
||
**用途**：版本信息与二进制/模型清单。
|
||
|
||
**响应示例**：
|
||
```json
|
||
{
|
||
"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`
|
||
**用途**：资产详情（配置、二进制、模型清单）。
|
||
|
||
**响应示例**：
|
||
```json
|
||
{
|
||
"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}`
|
||
**用途**：查询异步/长耗时任务状态。
|
||
|
||
**响应示例**：
|
||
```json
|
||
{
|
||
"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 可执行文件。
|
||
|
||
**请求体**：
|
||
```json
|
||
{ "backup_path": "/path/to/media-server.bak.20250101-120000" }
|
||
```
|
||
|
||
**响应示例**：
|
||
```json
|
||
{
|
||
"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 等
|