REST / WebSocket API

API 定位：批量提取 KVM 屏幕 / OCR / 审计数据用作 AI 训练样本。不是用作 Agent runtime control（那走 in-process gRPC，不暴露 HTTP）。

认证

所有 API 走 JWT — 先 login 拿 token，header 加 Authorization: Bearer <token>。

TOKEN=$(curl -sk -X POST https://<KVM>:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<your-pw>"}' \
  | jq -r .token)

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://<KVM>:8080/api/kvm/status

JWT 有效期 24h，可在配置里改。失效后会 401 — 重新 login。

关键 endpoint

数据提取（AI 训练 use case）

Endpoint	用途
`GET /api/v1/snapshots/list?from=<ts>&to=<ts>&page=<n>`	分页列出屏幕快照（JPEG）
`GET /api/v1/snapshots/<id>`	单张快照原图
`GET /api/v1/ocr/results?from=<ts>&page=<n>`	OCR 文本 + bbox 列表
`GET /api/v1/audit/export?format=jsonl&from=<ts>`	审计日志 jsonl 流（签名链）
`GET /api/v1/recording/list`	屏幕录像 segment 列表（HLS）
`GET /api/v1/manifest`	全量数据 manifest（一次 GET 知所有可下载范围）

控制接口（运维 use case）

Endpoint	用途
`GET /api/kvm/status`	设备状态（HDMI / 视频 / HID / 客户端数）
`POST /api/kvm/video/resolution`	切分辨率（`{width,height,fps}`）
`POST /api/kvm/shortcut`	发组合键（`{shortcut:"ctrl_alt_del"}`）
`POST /api/kvm/power/{on,off,reset}`	电源控制（需目标机 BIOS 配合 WoL）

信令 / 视频流

Endpoint	协议	用途
`WSS /ws`	WebSocket	WebRTC 信令（SDP offer/answer + ICE）
WebRTC peer	RTP/SRTP	H.264 视频 + datachannel HID

v2.0.4 起 /ws 强制 JWT 鉴权。无 token 直接 401。之前 v1.x → v2.0.3 是 wide-open，CVE-2026-05-22-001 已修。

指标 / 可观测性（v2.1.0 新增,无 auth）

Endpoint	协议	用途
`GET /api/metrics`	Prometheus 0.0.4 text	28 字段 — fps / encode latency / shmring 健康 / TWCC 自适应状态

关键字段（详见仓内 docs/API.md §18）:

kvm_video_frames_captured_total — L1 capture fps（rate(...) [10s]）
kvm_mpp_encode_latency_us{quantile} — L3 编码 p50/p95/p99(rc.2 实测 p50=4019µs, p99=4121µs)
kvm_video_shmring_writes_total — Lever #2 快路径帧数(应等于 frames_captured)
kvm_adaptive_loss_ema_bp / kvm_adaptive_rtt_ema_ms — TWCC 自适应控制器状态
kvm_hid_latency_us{quantile} — HID 写延迟 p50/p95/p99

直接 scrape 例:

curl -sk https://<host>:8080/api/metrics | grep -E '^kvm_(video|mpp_encode)_' | head

分页 + 长期 token

数据提取场景设计：

分页：page + page_size（默认 50，max 500）
manifest：单一 endpoint 返回所有可下载范围（起止 timestamp / 总数 / 分片大小），客户端按此拉
长期 token：admin 在 /api/v1/tokens/issue 签发 90 天 token 给爬虫用，不需要每天 login

错误码

HTTP	含义	处理
200 / 202	成功（202 = 异步操作已接受）	—
400	请求参数错（如 `{width: -1}`）	检查 payload
401	token 缺失 / 过期	重新 login
403	权限不够（如普通用户调 admin endpoint）	升级 role
409	资源冲突（如同时切两次分辨率）	重试
429	限流	退避后重试
5xx	服务端错	查 `journalctl -u kvm-server`

完整 API 文档

仓库内 docs/API.md + docs/API_FOR_DATA_EXTRACTION.md 含完整 OpenAPI 风格描述。

认证​

关键 endpoint​

数据提取（AI 训练 use case）​

控制接口（运维 use case）​

信令 / 视频流​

指标 / 可观测性（v2.1.0 新增,无 auth）​

分页 + 长期 token​

错误码​

完整 API 文档​

认证