devos/docs/API.md

DevOS v1 API 契约

基址：/api/v1。所有响应为 JSON；变更（mutation）契约：zod DTO 校验 → 工作区授权 → 风险判定 → 审计记录 → 事件（如适用）→ 响应头 X-Request-Id。

错误契约

{ "error": { "code": "RESOURCE_NOT_FOUND", "message": "Server not found", "requestId": "uuid" } }

错误码：VALIDATION_ERROR(400) / UNAUTHORIZED(401) / FORBIDDEN(403) / RESOURCE_NOT_FOUND(404) / CONFLICT(409) / UPSTREAM_FAILURE(502) / TIMEOUT(504) / INTERNAL_ERROR(500)。

认证

方法	路径	说明
POST	/auth/register	{email,password,name?} → {token,user}（自动创建 OWNER 工作区）
POST	/auth/login	{email,password} → {token,expiresIn,user}（JWT HS256，12h）
GET	/auth/me	当前用户 + 工作区列表
POST	/auth/logout	无状态登出（审计记录）

鉴权：Authorization: Bearer <jwt>；工作区：X-Workspace-Id 头（缺省用 token wid 或第一个成员关系）。角色：VIEWER 只读，MEMBER 可操作，ADMIN 管理成员/凭据，OWNER 全权。

工作区

• GET /workspaces 我的列表
• POST /workspaces {name} 创建（创建者 OWNER）
• GET /workspaces/:id 详情（须为成员；路径参数越权返回 403）
• GET|POST /workspaces/:id/members、POST /workspaces/:id/members/:memberId（改角色）、DELETE .../:memberId

资源（统一模型）

• GET /resources?type=&status=&q=&page=&pageSize=
• POST /resources（通用类型：PROJECT/REPOSITORY/DATABASE/DOCUMENT/BACKUP/EMAIL_ACCOUNT/TASK/NOTE）
• GET|PATCH|DELETE /resources/:id（DELETE 需 ADMIN）
• GET|POST /resources/:id/relations、DELETE /resources/:id/relations/:rid

服务器

• GET|POST /servers；创建：{name,host,port,username,provider:"ssh"|"local",authType,password|privateKey|credentialId}
  • provider:"local"：通过本机 /var/run/docker.sock 管理（无需凭据）
• GET|DELETE /servers/:id
• POST /servers/:id/connect 连通性探测（刷新状态、发 server.online/offline 事件）
• GET /servers/:id/status 含 docker 可用性
• POST /servers/:id/exec {command,timeoutMs}（审计；危险命令风险 CRITICAL）
• POST /servers/:id/restart {confirm:true}（ADMIN；HIGH）

容器

• GET /containers 全工作区
• POST /servers/:id/containers 发现（docker ps → 入库/更新 + runs_container 关系）
• GET /servers/:id/containers
• GET /containers/:id/inspect（env 键脱敏）
• POST /containers/:id/restart {confirm:true}

网站

• GET|POST /websites：{name,primaryDomain?,serverId?,repositoryUrl?,deployType,port,healthPath,env?,domainId?}
• GET|PATCH|DELETE /websites/:id
• POST /websites/:id/deploy → 创建部署（HIGH）
• GET /websites/:id/logs?limit= 最近部署日志
• GET /websites/:id/health 即时健康检查

部署

• GET /deployments?websiteId=；GET /deployments/:id（含 logs）
• POST /deployments {websiteId,branch?,trigger?}
• POST /deployments/:id/cancel（QUEUED 立即取消；RUNNING 步骤间生效）

域名

• GET|POST /domains：{name,provider:"CLOUDFLARE"|"MANUAL",credentialId?}
• GET|DELETE /domains/:id
• GET /domains/:id/records（CLOUDFLARE 实时拉取并同步本地）
• POST /domains/:id/records {type,name,value,ttl?,proxied?}（upsert）
• POST /domains/:id/records/:localId/delete

监控

• GET|POST /monitors：{name,kind:"HTTP"|"TCP",target,intervalSec?,timeoutMs?,websiteId?,enabled?}
• GET /monitors/:id（含 50 条结果历史）
• PATCH /monitors/:id {enabled}；DELETE /monitors/:id

自动化

• GET|POST /automations：{name,triggerType,triggerConfig:{cron|eventType|secret},conditions:[{path,op,value}],actions:[{type,args,timeoutMs,retries}],enabled}
• GET /automations/:id（含 20 条执行历史）
• POST /automations/:id/enable|disable|run
• POST /automations/:id/webhook（公开；X-Webhook-Secret 头校验）
• DELETE /automations/:id（ADMIN）

AI

• GET|POST /ai/runs：{objective} → 创建后异步规划；HIGH/CRITICAL 停在 AWAITING_APPROVAL
• GET /ai/runs/:id（plan/toolCalls/verification）
• POST /ai/runs/:id/approve|reject（ADMIN）

凭据

• GET|POST /credentials（ADMIN）：{name,type,provider?,secret} — 明文仅存在于请求瞬间，任何响应不含密文
• PATCH /credentials/:id（轮换）、DELETE /credentials/:id（ADMIN）

审计与事件

• GET /audit?page=&pageSize=&resourceType=&resourceId=&action=
• GET /events?page=&pageSize=&eventType=

系统

• GET /health（公开）
• GET /dashboard（工作台统计）

MCP

• POST /api/v1/mcp — Streamable HTTP（无状态）。请求头：Authorization: Bearer <jwt>、Accept: application/json, text/event-stream
• 工具：devos.server.list/status/exec/getDockerContainers、devos.website.list/deploy/logs/health、devos.deployment.get/list、devos.domain.list/records、devos.automation.list/run
• 所有调用经 ToolRegistry → 各模块 service（同授权/审计；actorType=MCP）