扩展

API 参考

OpsKeeper 的 HTTP API 是控制平面的规范接口。opskeeper-teamharness 中的 MCP 工具与下面的端点一一对应。

基础 URL 与鉴权

所有端点都在 /api/v1 下。鉴权方式：Authorization: Bearer <jwt>。JWT 由 POST /api/v1/auth/login 颁发，通过 POST /api/v1/auth/refresh 刷新。

事件

incidents

GET    /api/v1/incidents
GET    /api/v1/incidents/:id
GET    /api/v1/incidents/:id/timeline
GET    /api/v1/incidents/:id/evidence
GET    /api/v1/incidents/:id/proposals
GET    /api/v1/incidents/:id/audit

提案

proposals

POST   /api/v1/proposals
GET    /api/v1/proposals/:id
POST   /api/v1/proposals/:id/approve
POST   /api/v1/proposals/:id/reject
GET    /api/v1/proposals/pending

审批一份提案会把审批绑定到该提案的资源、命令、payload 哈希。控制平面会拒绝派发与已被篡改的提案。

技能

skills

GET    /api/v1/skills
GET    /api/v1/skills/:name
POST   /api/v1/skills/:name/deploy
DELETE /api/v1/skills/:name
POST   /api/v1/skills/:name/rotate-secret

审计

audit

GET    /api/v1/audit?from=&to=&incident_id=&limit=
POST   /api/v1/audit/replay    # 端到端走完整条 HMAC 链
GET    /api/v1/audit/events/:id

插件

plugins

GET    /v1/plugins
GET    /v1/plugins/:id
POST   /v1/plugins/:id/install
POST   /v1/plugins/:id/uninstall
POST   /v1/plugins/:id/enable
POST   /v1/plugins/:id/disable
POST   /v1/plugins/:id/sync
POST   /v1/plugins/:id/push

Webhook

webhooks

POST   /api/v1/webhook/alerts   # 由源端用 HMAC 签名
POST   /api/v1/webhook/git        # 用于变更事件关联

错误

所有错误都返回带 code、message，以及可选 details 的 JSON：

error

{
  "code": "proposal_hash_mismatch",
  "message": "资源、命令或 payload 哈希与已审批提案不一致",
  "details": {
    "proposal_id": "prop-...",
    "expected_payload_hash": "sha256:...",
    "actual_payload_hash": "sha256:..."
  }
}

中间件

中间件层文档在仓库的 docs/api/middleware.md。涵盖限流、请求签名，以及在每次变更类调用上发账本事件的审计中间件。