phptits
0d6cd37579
- Monorepo: NestJS API (Fastify) + React web (antd/ProComponents) + shared packages - PostgreSQL/Prisma (unified resources, relations graph, audit, events, jobs) - Auth/RBAC/workspace isolation, credential vault (AES-256-GCM) - Servers/SSH, Docker discovery & lifecycle, Job Center - Websites & deployments (git provider credential clone, env, health verification) - Domains/DNS (Cloudflare adapter), certificates (TLS probe), monitoring - Automation (cron/event/webhook HMAC + notifications), AI Gateway, MCP (29 tools) - AI chat window (LLM function-calling + rules fallback, SSE streaming, approvals) - Notes: Vditor WYSIWYG markdown editor, non-blocking autosave - Tests: 35 unit/security tests; UI audit clean (desktop+mobile, deep links)
118 lines
5.0 KiB
Markdown
118 lines
5.0 KiB
Markdown
# DevOS v1 API 契约
|
||
|
||
基址：`/api/v1`。所有响应为 JSON；变更（mutation）契约：zod DTO 校验 → 工作区授权 → 风险判定 → 审计记录 → 事件（如适用）→ 响应头 `X-Request-Id`。
|
||
|
||
## 错误契约
|
||
|
||
```json
|
||
{ "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）
|