ProberX API 文档

Dashboard 开放 HTTP API，覆盖认证、工作空间、服务器、监控、告警、通知、Cron、AI 智能体（对话 / 巡检 / 自主排查 / 周报 / 工作流）、运维工具等全部能力，共 190+ 端点。

概览

所有 API 均以 https://agent.yqone.cn/api/v1 为前缀（可通过 nginx 反代到任意 Dashboard 实例）。请求与响应均为 JSON（上传除外），编码 UTF-8。

认证

登录后获取 JWT，后续请求携带 Authorization: Bearer <token> 头
Token 过期（401）时调用 POST /auth/refresh 刷新（同样把 refresh token 放在 Authorization 头）
所有工作空间内接口还需属于该工作空间（服务端按成员关系校验）

错误格式

{ "code": "NOT_FOUND", "message": "User not found" }

常见状态码：400 参数校验失败、401 未认证/Token 过期、403 无权限、404 资源不存在、429 触发限流（默认 100 次/分钟/IP）。

Agent 专用接口

/api/v1/agent/* 使用 X-Agent-Token 头认证，仅 Agent 回连使用，普通用户不会调用。

WebSocket

实时推送（指标、告警、终端）使用 wss://agent.yqone.cn/ws，连接时携带 JWT。

认证

注册与登录接口。

方法	路径	说明
POST	`/auth/register`	注册账号（邮箱 + 密码）
POST	`/auth/login`	登录，返回 access token 与 refresh token
POST	`/auth/refresh`	用 refresh token 换取新 access token（Authorization 头）
GET	`/auth/me`	获取当前登录用户信息
POST	`/auth/oauth`	GitHub OAuth 登录（需服务端配置）

参数说明

端点	字段	说明
`POST /auth/register`	`name` * `email` * `password` *	昵称（1-100 字符）邮箱地址（需为合法邮箱）密码（至少 8 位）
`POST /auth/login`	`email` * `password` *	邮箱地址密码（至少 6 位）
`POST /auth/refresh`	无 body	在 Authorization 头携带 refresh token 换取新 access token
`GET /auth/me`	无参数	返回当前登录用户信息
`POST /auth/oauth`	`provider` * `code` * `redirectUri` *	OAuth 提供商（当前支持 github） GitHub OAuth code 回调地址（需为 URL）

注册示例

curl -X POST https://agent.yqone.cn/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"我的账号","email":"me@example.com","password":"12345678"}'

成功返回 201：{"token":"...","user":{"id":"...","email":"me@example.com","name":"我的账号","avatarUrl":null}}；邮箱已被注册返回 409 Email already registered，字段不合法返回 400。

工作空间

多租户隔离：服务器、监控、告警等资源都归属某个工作空间，接口路径统一使用 :wid 参数。

方法	路径	说明
GET	`/workspaces`	工作空间列表
POST	`/workspaces`	创建工作空间
GET	`/workspaces/:wid`	工作空间详情
PATCH	`/workspaces/:wid`	更新工作空间
DELETE	`/workspaces/:wid`	删除工作空间
GET	`/workspaces/:wid/dashboard`	仪表盘统计数据
GET	`/workspaces/:wid/alert-trends`	告警趋势
GET	`/workspaces/:wid/server-comparison`	服务器指标对比

参数说明

端点	字段	说明
`POST /workspaces`	`name` *	工作空间名称（1-255 字符）
`PATCH /workspaces/:wid`	`name`? `plan`? `settings`?	名称套餐：free / pro / enterprise 自定义设置对象
`GET /workspaces/:wid/alert-trends`	`range`?	查询范围：24h / 7d / 30d（默认 7d，query 参数）

服务器

服务器是 Agent 的载体，添加后返回 Agent Token，用于在被监控机器上安装探针。

方法	路径	说明
GET	`/workspaces/:wid/servers`	服务器列表（?limit=）
POST	`/workspaces/:wid/servers`	添加服务器，返回 AGENT_TOKEN / AGENT_ID
GET	`/workspaces/:wid/servers/:id`	服务器详情
PATCH	`/workspaces/:wid/servers/:id`	更新服务器
DELETE	`/workspaces/:wid/servers/:id`	删除服务器（?uninstall 可卸载 Agent）
GET	`/workspaces/:wid/servers/:id/metrics`	历史指标（?from=&to=）
POST	`/workspaces/:wid/servers/:id/regenerate-token`	重新生成 Agent Token
GET	`/workspaces/:wid/servers/:id/install/log`	Agent 自动安装日志
POST	`/workspaces/:wid/servers/:id/pull-metrics`	立即拉取一次指标
POST	`/workspaces/:wid/servers/:id/run-probe`	手动运行一次探测（http/tcp/ping/dns/ssl）
GET	`/workspaces/:wid/servers/:id/processes`	进程列表
GET	`/workspaces/:wid/servers/:id/containers`	Docker 容器列表
POST	`/workspaces/:wid/servers/:id/agent/upgrade`	一键升级 Agent 到最新版

参数说明

端点	字段	说明
`GET /workspaces/:wid/servers`	`limit`? `cursor`?	每页数量 1-100（默认 20）分页游标（query 参数）
`POST /workspaces/:wid/servers`	`name` * `agentId`? `tags`? `isHidden`? `agentHost`? `agentPort`? `expiresAt`? `installMode`? `dashboardUrl`? `ssh`?	服务器名称自定义 Agent ID（≤64 字符）标签数组（默认 []）是否隐藏（默认 false） Agent 地址（在线安装/回连） Agent 端口（默认 9800）到期时间，格式 YYYY-MM-DD，用于到期提醒安装方式：online / offline（默认 offline）安装命令中的面板地址 ssh 对象（online 安装用）：host、port（22）、username（root）、password
`PATCH /workspaces/:wid/servers/:id`	`name`? `tags`? `isHidden`? `agentHost`? `agentPort`? `expiresAt`?	全部可选，传 null 可清除；expiresAt 支持 YYYY-MM-DD 或 null（清除到期时间并重置提醒状态）
`DELETE /workspaces/:wid/servers/:id`	`uninstall`? `ssh`?	是否同时卸载 Agent（默认 false） ssh 对象（卸载用）：host、port、username、password
`GET /workspaces/:wid/servers/:id/metrics`	`from`? `to`? `interval`?	开始时间（ISO 字符串）结束时间采样间隔（秒）
`POST /workspaces/:wid/servers/:id/run-probe`	`type` * `target` * `timeoutMs`?	探测类型：http / tcp / ping / dns / ssl 探测目标（URL/域名/IP）超时毫秒（1000-30000）
`POST /workspaces/:wid/servers/:id/agent/upgrade`	`url`?	Agent 安装包下载地址（可选，缺省用最新版）

服务器资源总览

由 ProberX Agent 原生只读采集，不依赖宝塔等控制面板。返回 8 组归一化数据：系统 / 站点 / 证书 / 数据库 / 计划任务 / 运行服务 / 安全基线 / 实时网络。每组为独立的分组结果 { ok, data?, error? }，单组异常不影响整体。

方法	路径	说明
GET	`/workspaces/:wid/servers/:sid/resource-overview`	采集服务器资源总览（8 组，Agent 需在线）

响应结构（节选）

{
  "system":        { "ok": true, "data": { "os": "Ubuntu 22.04", "hostname": "web-01",
                        "cpuPercent": 12.3, "memTotalBytes": 0, "diskTotalBytes": 0, ... } },
  "sites":         { "ok": true, "data": { "total": 3,
                        "list": [{ "id": "1", "name": "panel.yqone.cn", "rootPath": "/www/wwwroot/panel", "enabled": true }] } },
  "certificates":  { "ok": true, "data": { "total": 2, "expired": 0, "expiringSoon": 1,
                        "list": [{ "id": "1", "domains": ["panel.yqone.cn"], "issuer": "Let's Encrypt",
                                   "expiresAt": "2026-11-01T00:00:00Z", "daysLeft": 55 }] } },
  "databases":     { "ok": true, "data": { "total": 4,
                        "list": [{ "name": "proberx", "engine": "MySQL", "sizeBytes": 104857600 }] } },
  "cronTasks":     { "ok": true, "data": { "total": 5, "running": 0,
                        "list": [{ "id": "1", "name": "backup", "schedule": "0 2 * * *", "enabled": true }] } },
  "services":      { "ok": true, "data": { "total": 120, "running": 118, "failed": 1,
                        "list": [{ "name": "nginx", "description": "...", "active": true, "failed": false }] } },
  "securityScan":  { "ok": true, "data": { "state": "done", "progressPercent": null, "score": 92, "riskCount": 1 } },
  "network":       { "ok": true, "data": { "upRateKbps": 120.5, "downRateKbps": 30.1,
                        "upTotalMb": 1024, "downTotalMb": 4096, "load1": 0.4, "load5": 0.3, "load15": 0.2 } },
  "checkedAt": "2026-09-01T02:00:00.000Z"
}

面板接入（宝塔 / aaPanel）

可选能力：把服务器上的宝塔（BT）/ aaPanel 面板 API 绑定为数据源，拉取面板侧的站点、证书、数据库、FTP、计划任务等详情。密钥仅加密保存，列表与详情返回 apiKeyConfigured / apiKeyHint，不回显明文。

方法	路径	说明
GET	`/workspaces/:wid/servers/:sid/panel-bindings`	服务器面板绑定列表
POST	`/workspaces/:wid/servers/:sid/panel-bindings`	创建绑定（返回 201）
POST	`/workspaces/:wid/servers/:sid/panel-bindings/test-candidate`	测试「未保存」的候选配置（不落库），供表单先测后存
PATCH	`/workspaces/:wid/servers/:sid/panel-bindings/:bid`	更新绑定
DELETE	`/workspaces/:wid/servers/:sid/panel-bindings/:bid`	删除绑定（返回 204）
POST	`/workspaces/:wid/servers/:sid/panel-bindings/:bid/test`	测试已保存的绑定并回写连接状态
GET	`/workspaces/:wid/servers/:sid/panel-bindings/:bid/overview`	拉取绑定面板的归一化概览（系统/站点/证书/数据库/FTP/计划任务/安全/网络）

参数说明

端点	字段	说明
`POST /panel-bindings` `PATCH /panel-bindings/:bid`	`adapter`? `name`? `panelUrl` * `apiKey` * `clearApiKey`? `enabled`?	适配器：bt（默认）/ aapanel 名称（≤100 字符）面板地址（≤500，如 http://1.2.3.4:8888）面板 API 密钥（≤500；更新时非空则覆盖，PATCH 可省略）置 true 清空已保存密钥是否启用（默认 true）
`GET /panel-bindings/:bid/overview`	无参数	返回与「资源总览」一致的分组结构，另含 `ftpUsers` 分组；采集失败分组为 `{ ok:false, error }`

安全提示：面板 API 属于控制面高危凭证。建议在面板侧开启 API 白名单，仅放行 Dashboard / Agent 出口 IP；密钥字段在接口响应中一律脱敏。

虚拟化与云接入

把 vCenter、独立 ESXi、Proxmox VE 与阿里云 ECS / 腾讯云 CVM 接成数据源：清单与电源状态直接取自平台 API，无需在受管主机上安装 Agent。绑定是工作区级的；公有云按地域（region）拉取，一个绑定对应一个地域。

方法	路径	说明
GET	`/workspaces/:wid/virtualization/bindings`	绑定列表（凭据脱敏：只回 `secretConfigured` / `secretHint`）
POST	`/workspaces/:wid/virtualization/bindings`	创建绑定（返回 201）
POST	`/workspaces/:wid/virtualization/bindings/test-candidate`	测试「未保存」的候选配置（不落库），供表单先测后存
PATCH	`/workspaces/:wid/virtualization/bindings/:bid`	更新绑定（`secret` 非空则覆盖）
DELETE	`/workspaces/:wid/virtualization/bindings/:bid`	删除绑定（返回 204）
POST	`/workspaces/:wid/virtualization/bindings/:bid/test`	测试已保存的绑定并回写连接状态
GET	`/workspaces/:wid/virtualization/bindings/:bid/inventory`	归一化清单：平台摘要 / 节点（宿主机与集群）/ 虚拟机；单段失败不影响其它段
GET	`/workspaces/:wid/virtualization/bindings/:bid/vms/:vmId/state`	单台虚拟机的实时电源状态（电源操作前后刷新用）
POST	`/workspaces/:wid/virtualization/bindings/:bid/guests/:vmId/adopt`	把虚拟机纳管成一条服务器记录（返回 201）
DELETE	`/workspaces/:wid/virtualization/bindings/:bid/guests/:vmId/adopt`	取消纳管（已装 Agent 升格的记录会被拒绝）
POST	`/workspaces/:wid/virtualization/bindings/:bid/vms/:vmId/power`	电源动作（需绑定开启 `allowPower`）
GET	`/workspaces/:wid/virtualization/bindings/:bid/actions`	电源操作审计（新的在前，`?limit=`）

参数说明

端点	字段	说明
`POST /virtualization/bindings` `PATCH .../bindings/:bid`	`adapter`? `name`? `baseUrl` * `username` * `secret`? `region`? `insecureTls`? `enabled`? `allowPower`?	平台类型：`vcenter`（默认）/ `esxi` / `proxmox` / `aliyun` / `tencent` 名称（≤100，缺省用平台默认名）平台地址（≤500；公有云缺省官方入口）账号：vCenter/ESXi/Proxmox 用户名，阿里云 AccessKey ID，腾讯云 SecretId 密码：vCenter/ESXi 密码，Proxmox API Token Secret，阿里云 AccessKey Secret，腾讯云 SecretKey 公有云地域（阿里云 RegionId / 腾讯云 Region，如 cn-hangzhou / ap-guangzhou）跳过证书校验（私有化自签名场景）是否启用（默认 true）是否允许电源操作（默认 false，Proxmox / 公有云恒为只读）
`POST .../vms/:vmId/power`	`action` * `confirmName` *	动作：`start` / `stop` / `gracefulStop` / `reboot` / `suspend` 二次确认：要与平台返回的当前虚拟机名一致才执行；结果与审计一起返回
`POST .../guests/:vmId/adopt`	`name`? `os`? `tags`?	服务器名（缺省取平台返回的虚拟机名） `linux` / `windows`（决定后续安装命令走哪套，默认 linux）标签数组
`GET .../actions`	`limit`?	返回条数（1–100，默认 20）

权限建议（最小化）：vCenter 用内置 Read-only 角色（电源操作另加 VirtualMachine.Interact.PowerOn/PowerOff/Reset/Suspend）；Proxmox 用 PVEAuditor（电源另加 VM.PowerMgmt，当前版本未实现 Proxmox 写操作）；阿里云 RAM 只给 ecs:Describe*；腾讯云 CAM 只给 cvm:DescribeInstances / cvm:DescribeInstancesStatus。凭据字段在接口响应中不下发（只给是否配置与尾四位提示）。

文件与防火墙

通过 Agent 操作被监控服务器上的文件系统和 iptables 防火墙。

方法	路径	说明
GET	`/workspaces/:wid/servers/:id/files/list`	文件列表（?path=）
GET	`/workspaces/:wid/servers/:id/files/read`	读取文件内容（?path=&lines=）
GET	`/workspaces/:wid/servers/:id/files/download`	下载文件
POST	`/workspaces/:wid/servers/:id/files/upload`	上传文件（multipart）
POST	`/workspaces/:wid/servers/:id/files/mkdir`	创建目录
POST	`/workspaces/:wid/servers/:id/files/rename`	重命名文件/目录
POST	`/workspaces/:wid/servers/:id/files/write`	写入文件内容
DELETE	`/workspaces/:wid/servers/:id/files/delete`	删除文件/目录
GET	`/workspaces/:wid/servers/:id/firewall/rules`	防火墙规则列表
POST	`/workspaces/:wid/servers/:id/firewall/rules`	添加 iptables 规则
DELETE	`/workspaces/:wid/servers/:id/firewall/rules`	删除规则

参数说明

端点	字段	说明
`GET .../files/list`	`path`?	目录路径（默认 /）
`GET .../files/read`	`path` * `lines`?	文件路径读取行数
`GET .../files/download`	`path` *	文件路径
`POST .../files/upload`	multipart	form-data：path（目标路径）+ file（文件）
`POST .../files/mkdir`	`path` *	要创建的目录路径
`POST .../files/rename`	`path` * `newName` *	原路径新名称
`POST .../files/write`	`path` * `content` *	文件路径写入内容
`DELETE .../files/delete`	`path` *	要删除的文件/目录路径
`POST .../firewall/rules`	iptables 规则对象	规则参数透传 Agent（如 chain、protocol、port、action 等）
`DELETE .../firewall/rules`	`chain` * `num` *	规则链（如 INPUT）规则序号

运维工具

通过 Agent 执行系统级运维操作。以下路径均省略前缀 /workspaces/:wid/servers/:id。

方法	路径	说明
GET	`/workspaces/:wid/servers/:id/tools/services`	systemd 服务列表
POST	`/workspaces/:wid/servers/:id/tools/services`	控制服务 start/stop/restart（body: name, action）
GET	`/workspaces/:wid/servers/:id/tools/services/:name`	服务详细状态
POST	`/workspaces/:wid/servers/:id/tools/ssl`	检查证书（host/port）
POST	`/workspaces/:wid/servers/:id/tools/ssl/issue`	ACME 签发证书
POST	`/workspaces/:wid/servers/:id/tools/ssl/renew`	续期证书
GET	`/workspaces/:wid/servers/:id/tools/ssl/certs`	已签发证书列表
GET	`/workspaces/:wid/servers/:id/tools/logs`	journalctl 日志（?unit=&lines=&since=）
GET	`/workspaces/:wid/servers/:id/tools/logs/file`	文件日志（?path=&lines=）
GET	`/workspaces/:wid/servers/:id/tools/packages`	包列表（?upgradable=true）
POST	`/workspaces/:wid/servers/:id/tools/packages`	批量升级可更新包
GET	`/workspaces/:wid/servers/:id/tools/nginx`	Nginx 运行状态
POST	`/workspaces/:wid/servers/:id/tools/nginx/reload`	重载 Nginx 配置
GET	`/workspaces/:wid/servers/:id/tools/nginx/config`	读取配置文件（?path=）
GET	`/workspaces/:wid/servers/:id/tools/nginx/vhosts`	虚拟主机列表
POST	`/workspaces/:wid/servers/:id/tools/nginx/vhosts`	创建虚拟主机
DELETE	`/workspaces/:wid/servers/:id/tools/nginx/vhosts`	删除虚拟主机
GET	`/workspaces/:wid/servers/:id/tools/deploy/templates`	应用部署模板
GET	`/workspaces/:wid/servers/:id/tools/deploy/list`	已部署应用列表
POST	`/workspaces/:wid/servers/:id/tools/deploy/deploy`	部署应用（Docker Compose）
POST	`/workspaces/:wid/servers/:id/tools/deploy/remove`	移除部署
GET	`/workspaces/:wid/servers/:id/tools/deploy/logs`	部署日志（?appName=）
POST	`/workspaces/:wid/servers/:id/tools/deploy/start`	启动应用
POST	`/workspaces/:wid/servers/:id/tools/deploy/stop`	停止应用
POST	`/workspaces/:wid/servers/:id/tools/deploy/restart`	重启应用
POST	`/workspaces/:wid/servers/:id/tools/deploy/update`	更新应用
GET	`/workspaces/:wid/servers/:id/tools/deploy/progress`	部署进度（?appName=）
POST	`/workspaces/:wid/servers/:id/tools/deploy/check-ports`	检查端口占用
GET	`/workspaces/:wid/servers/:id/tools/databases`	数据库实例列表
POST	`/workspaces/:wid/servers/:id/tools/databases`	安装数据库（mysql/postgres/redis/mongo）
DELETE	`/workspaces/:wid/servers/:id/tools/databases`	卸载数据库
GET	`/workspaces/:wid/servers/:id/tools/backups`	备份列表
POST	`/workspaces/:wid/servers/:id/tools/backups/file`	创建文件备份
POST	`/workspaces/:wid/servers/:id/tools/backups/db`	创建数据库备份
DELETE	`/workspaces/:wid/servers/:id/tools/backups`	删除备份
POST	`/workspaces/:wid/servers/:id/tools/backups/restore`	恢复备份
GET	`/workspaces/:wid/servers/:id/tools/backups/cloud-config`	云存储配置
PUT	`/workspaces/:wid/servers/:id/tools/backups/cloud-config`	保存云存储配置（S3/OSS/R2/MinIO）
POST	`/workspaces/:wid/servers/:id/tools/backups/cloud/upload`	备份上传云端
POST	`/workspaces/:wid/servers/:id/tools/backups/cloud/download`	从云端下载
GET	`/workspaces/:wid/servers/:id/tools/backups/cloud/list`	云端文件列表
DELETE	`/workspaces/:wid/servers/:id/tools/backups/cloud`	删除云端文件
POST	`/workspaces/:wid/servers/:id/tools/backups/cloud/sync`	全量同步到云端
POST	`/workspaces/:wid/servers/:id/tools/backups/cloud/cleanup`	按保留天数清理
POST	`/workspaces/:wid/servers/:id/tools/backups/cloud/test`	测试云存储连接
GET	`/workspaces/:wid/servers/:id/tools/security/ssh`	SSH 登录审计
POST	`/workspaces/:wid/servers/:id/tools/security/portscan`	端口扫描
GET	`/workspaces/:wid/servers/:id/tools/security/fail2ban`	Fail2ban 状态
POST	`/workspaces/:wid/servers/:id/tools/security/fail2ban/unban`	解封 IP
POST	`/workspaces/:wid/servers/:id/tools/security/fail2ban/ban`	封禁 IP
GET	`/workspaces/:wid/servers/:id/tools/shell-ai/settings`	读取 AI 配置（provider/model/api_url）
PUT	`/workspaces/:wid/servers/:id/tools/shell-ai/settings`	保存 AI 配置（Ollama/OpenAI/DeepSeek/Claude）
POST	`/workspaces/:wid/servers/:id/tools/shell-ai/generate`	中文描述生成 Shell 命令（body: prompt, provider...）
POST	`/workspaces/:wid/servers/:id/tools/shell-ai/execute`	执行 Shell 命令并返回输出（body: command, timeout）
GET	`/workspaces/:wid/servers/:id/images`	Docker 镜像列表
POST	`/workspaces/:wid/servers/:id/images/pull`	拉取镜像
POST	`/workspaces/:wid/servers/:id/images/prune`	清理无用镜像
GET	`/workspaces/:wid/servers/:id/images/:imageId/json`	镜像详情
DELETE	`/workspaces/:wid/servers/:id/images/:imageId`	删除镜像
GET	`/workspaces/:wid/servers/:id/tools/dns/providers`	支持的 DNS 服务商列表
GET	`/workspaces/:wid/servers/:id/tools/dns/config`	DNS 服务商配置
POST	`/workspaces/:wid/servers/:id/tools/dns/config`	保存 DNS 配置
GET	`/workspaces/:wid/servers/:id/tools/dns/zones`	域名 Zone 列表
GET	`/workspaces/:wid/servers/:id/tools/dns/records`	解析记录列表（?zoneId=）
POST	`/workspaces/:wid/servers/:id/tools/dns/records`	新增解析记录
PUT	`/workspaces/:wid/servers/:id/tools/dns/records/:recordId`	更新解析记录
DELETE	`/workspaces/:wid/servers/:id/tools/dns/records/:recordId`	删除解析记录

参数说明

端点	字段	说明
`POST .../tools/services`	`name` * `action` *	systemd 服务名操作：start / stop / restart
`GET .../tools/services/:name`	路径参数	服务名
`POST .../tools/ssl`	`domain` *	域名
`POST .../tools/ssl/issue`	`domain` * `email` * `webroot`?	域名用于 ACME 的邮箱 Web 根目录（HTTP-01 验证）
`POST .../tools/ssl/renew`	`domain` *	域名
`GET .../tools/logs`	`unit`? `lines`? `since`?	systemd 单元名行数起始时间
`GET .../tools/logs/file`	`path` * `lines`?	文件路径行数
`GET .../tools/packages`	`upgradable`?	true 时仅返回可更新包
`GET .../tools/nginx/config`	`path`?	配置文件路径
`POST .../tools/nginx/vhosts`	`domain` * `target_port` * `web_root`? `use_ssl`? `ssl_email`?	站点域名反代目标端口 Web 根目录是否自动签发 SSL SSL 邮箱
`DELETE .../tools/nginx/vhosts`	`domain` *	站点域名
`POST .../tools/deploy/deploy`	`template_id` * `app_name` * `env` *	部署模板 ID 应用名环境变量对象
`POST .../tools/deploy/remove`	`appName` *	应用名
`POST .../tools/deploy/start\|stop\|restart\|update`	`appName` *	应用名
`GET .../tools/deploy/logs\|progress`	`appName` *	应用名（query 参数）
`POST .../tools/deploy/check-ports`	`ports` *	端口数组，如 ["80","443"]
`POST .../tools/databases`	`type` * `version`? `port` * `password`?	数据库类型（如 mysql / postgres）版本监听端口密码
`DELETE .../tools/databases`	`type` *	数据库类型
`POST .../tools/backups/file`	`source_path` * `name` *	要备份的目录备份名
`POST .../tools/backups/db`	`db_type` * `name` *	数据库类型备份名
`DELETE .../tools/backups`	`name` *	备份名
`POST .../tools/backups/restore`	`name` *	要恢复的备份名
`PUT .../tools/backups/cloud-config`	对象	云存储配置（provider、凭据、桶/路径等，透传 Agent）
`POST .../tools/backups/cloud/upload`	`name` *	本地备份名
`POST .../tools/backups/cloud/download`	`name` *	云端备份名
`DELETE .../tools/backups/cloud`	`name` *	云端备份名
`POST .../tools/backups/cloud/cleanup`	对象	清理策略（如保留份数）
`POST .../tools/security/portscan`	`target` * `ports`?	扫描目标（IP/域名）端口范围字符串
`POST .../tools/security/fail2ban/ban\|unban`	`ip` * `jail`?	IP 地址监狱名称（可选）
`GET\|PUT .../tools/shell-ai/settings`	`provider` * `model`? `api_key`? `api_url`?	LLM 提供商（proberx / openai / deepseek / custom 等）模型名 API Key 自定义接口地址
`POST .../tools/shell-ai/generate`	`prompt` * `provider` * `model`? `api_key`? `api_url`?	中文自然语言描述提供商模型名 API Key 自定义接口地址；返回 {command, explanation}
`POST .../tools/shell-ai/execute`	`command` * `timeout`?	要执行的 shell 命令超时秒数（默认 30）；返回 {stdout, stderr, exit_code}
`POST .../images/pull`	`name` *	镜像名，如 nginx:latest
`GET\|DELETE .../images/:imageId`	路径参数	镜像 ID
`GET .../tools/dns/providers`	无参数	支持的 DNS 服务商列表
`POST .../tools/dns/config`	`provider` * `api_key` * `api_secret`?	服务商 API Key API Secret（按服务商要求）
`GET .../tools/dns/records`	`zoneId` *	域名 zone ID（query 参数）
`POST .../tools/dns/records`	`zone_id` * `name` * `type` * `content` * `ttl` * `priority`?	Zone ID 记录名（如 www）记录类型（A/AAAA/CNAME/TXT/MX 等）记录值 TTL（秒）优先级（MX 用）
`PUT .../tools/dns/records/:recordId`	同创建	recordId 为路径参数，body 同 POST records
`DELETE .../tools/dns/records/:recordId`	`zone_id` *	Zone ID

AI 智能体

自然语言驱动的智能体编排：自动路由到通用助手 / AI 巡检 / 自主排查 / AI 终端 / AI 运维周报 / 自定义工作流 / 13 个专项诊断助手。对话任务为异步模型（返回 taskId 后轮询），巡检与排查结果可导出报告。

智能体目录与对话

方法	路径	说明
GET	`/agents`	智能体目录（5 个内置 + 13 个专项诊断助手；仅需登录）
POST	`/workspaces/:wid/servers/:id/agents/chat`	发起一次智能体对话/任务（异步，返回 taskId）
GET	`/workspaces/:wid/agents/chat/:taskId`	轮询任务状态（steps / text / status）

参数说明

端点	字段	说明
`POST /agents/chat`	`agent`? `workflowId`? `message` * `history`?	智能体 id：assistant / inspection / diagnosis / terminal / weekly / workflow / website-diag / mysql-diag / traffic-diag / security-diag / webshell-diag / server-diag / cron-diag / file-diag / ftp-diag / ssl-diag / log-diag / dns-diag / perf-diag；缺省自动路由 agent=workflow 时指定要运行的工作流用户消息（1-2000 字符）最近对话上下文，最多 20 条（role: user / assistant）

AI 巡检（健康报告）

方法	路径	说明
GET	`/workspaces/:wid/inspections`	巡检报告列表（?limit=&serverId=）
GET	`/workspaces/:wid/servers/:id/inspections`	某服务器巡检报告列表
POST	`/workspaces/:wid/servers/:id/inspections`	生成巡检报告（同步，body: title? / hours?）
GET	`/workspaces/:wid/inspections/:rid`	报告详情
GET	`/workspaces/:wid/inspections/:rid/html`	导出 HTML
GET	`/workspaces/:wid/inspections/:rid/markdown`	导出 Markdown
GET	`/workspaces/:wid/inspections/:rid/pdf`	导出 PDF
GET	`/workspaces/:wid/inspections/:rid/docx`	导出 Word (DOCX)
DELETE	`/workspaces/:wid/inspections/:rid`	删除报告

自主排查（多步诊断）

方法	路径	说明
GET	`/workspaces/:wid/diagnoses`	排查记录列表（?limit=&serverId=）
GET	`/workspaces/:wid/servers/:id/diagnoses`	某服务器排查记录列表
POST	`/workspaces/:wid/servers/:id/diagnoses`	发起自主排查（同步到完成，body: goal* / title? / trigger?）
GET	`/workspaces/:wid/diagnoses/:rid`	排查详情（时间线 / 根因 / 置信度 / 建议）
GET	`/workspaces/:wid/diagnoses/:rid/pdf`	导出 PDF 报告
GET	`/workspaces/:wid/diagnoses/:rid/docx`	导出 Word (DOCX) 报告
POST	`/workspaces/:wid/diagnoses/:rid/stop`	中止正在运行的排查
POST	`/workspaces/:wid/diagnoses/:rid/verify`	复检（只读）→ recovered / still_failing
GET	`/workspaces/:wid/diagnoses/:rid/repairs`	基于故障点生成的白名单修复方案
POST	`/workspaces/:wid/diagnoses/:rid/repairs/execute`	执行白名单修复（body: key* / confirmed?），成功后自动复检
DELETE	`/workspaces/:wid/diagnoses/:rid`	删除记录

参数说明

端点	字段	说明
`POST /diagnoses`	`goal` * `title`? `trigger`?	故障目标描述（4-1000 字符）标题（≤255）触发方式：manual（默认）/ auto
`POST /inspections`	`title`? `hours`?	报告标题（≤255）统计窗口小时数（1-168）

AI 运维周报

方法	路径	说明
GET	`/workspaces/:wid/reports/weekly`	汇总最近 N 天运维统计并生成中文周报（?days= 默认 7 &serverId=）
GET	`/workspaces/:wid/reports/weekly/md`	下载周报 Markdown
GET	`/workspaces/:wid/reports/weekly/docx`	下载周报 Word (DOCX)

自定义工作流

方法	路径	说明
GET	`/workspaces/:wid/workflow-tools`	工作流可编排的工具目录
GET	`/workspaces/:wid/workflows`	工作流列表
POST	`/workspaces/:wid/workflows`	创建工作流
PUT	`/workspaces/:wid/workflows/:wfid`	更新工作流
DELETE	`/workspaces/:wid/workflows/:wfid`	删除工作流
POST	`/workspaces/:wid/servers/:id/workflows/:wfid/run`	对目标服务器运行工作流（异步，返回 runId）
GET	`/workspaces/:wid/workflow-runs/:runId`	轮询工作流运行状态

参数说明

端点	字段	说明
`POST /workflows`	`name` * `description`? `trigger`? `steps` * `enabled`?	工作流名称（1-100）描述（≤1000）触发说明（≤100）步骤数组 1-20：每步 `{ id, kind: builtin\|shell\|mcp, tool, name?, args? }` 是否启用（默认 true）

工作区 AI 设置

方法	路径	说明
GET	`/workspaces/:wid/ai-settings`	读取工作区 AI 接口配置（Shell AI / 智能体 / 巡检 / 周报共用）
PUT	`/workspaces/:wid/ai-settings`	保存 AI 配置
POST	`/workspaces/:wid/ai-settings/test`	用当前或候选配置发起连通性测试（不落库）

参数说明

端点	字段	说明
`PUT /ai-settings`	`enabled`? `provider`? `apiUrl`? `model`? `apiKey`? `clearApiKey`?	是否启用 Provider：ollama / openai / deepseek / claude / custom 等 OpenAI 兼容接口地址（如 http://127.0.0.1:11434/v1）模型名（如 proberx-coder / deepseek-chat / gpt-4o-mini） API Key（非空覆盖；可为空字符串走本机 Ollama）置 true 清空已保存密钥

监控探测

从 Agent 发起 HTTP/TCP/Ping/DNS/SSL 探测任务，并查看历史结果。

方法	路径	说明
GET	`/workspaces/:wid/monitors`	监控任务列表
POST	`/workspaces/:wid/monitors`	创建监控任务（http/tcp/ping/dns/ssl）
PATCH	`/workspaces/:wid/monitors/:id`	更新监控任务
DELETE	`/workspaces/:wid/monitors/:id`	删除监控任务
GET	`/workspaces/:wid/monitors/:id/results`	任务最近探测结果
GET	`/workspaces/:wid/probe-results`	全部探测结果（?monitorId=）

参数说明

端点	字段	说明
`POST /workspaces/:wid/monitors`	`name` * `type` * `target` * `intervalSec`? `timeoutMs`? `settings`?	监控任务名类型：http / tcp / ping / dns / ssl / grpc 目标（URL / 域名 / IP）间隔秒数 10-3600（默认 60）超时毫秒 1000-30000（默认 5000）任务自定义设置
`PATCH /workspaces/:wid/monitors/:id`	`name`? `type`? `target`? `intervalSec`? `timeoutMs`? `settings`? `isEnabled`?	同创建字段，全部可选；isEnabled 控制启停
`GET /workspaces/:wid/monitors/:id/results`	`limit`?	返回条数（query 参数）

告警

基于指标的告警规则与事件管理。

方法	路径	说明
GET	`/workspaces/:wid/alerts`	告警规则列表
POST	`/workspaces/:wid/alerts`	创建告警规则（指标/运算符/阈值/持续时长）
PATCH	`/workspaces/:wid/alerts/:id`	更新规则（含启用/禁用）
DELETE	`/workspaces/:wid/alerts/:id`	删除规则
GET	`/workspaces/:wid/alert-events`	告警事件列表
GET	`/workspaces/:wid/alerts/:id/events`	某规则的事件列表
PATCH	`/workspaces/:wid/alerts/:id/events/:eid`	确认/静默告警事件

参数说明

端点	字段	说明
`POST /workspaces/:wid/alerts`	`name` * `targetType` * `targetId`? `metric` * `operator` * `threshold` * `durationSec`? `severity`?	规则名目标类型：server / monitor 目标 ID（UUID，可选）指标名（如 cpu_percent / server_expiry）比较符：gt / gte / lt / lte / eq / neq 阈值（数字）持续秒数（默认 0）级别：warning / critical / emergency（默认 warning）
`PATCH /workspaces/:wid/alerts/:id`	`name`? `metric`? `operator`? `threshold`? `durationSec`? `severity`? `isEnabled`?	同创建字段（operator 支持 gt / lt / eq / neq），全部可选；isEnabled 控制启停
`PATCH /workspaces/:wid/alerts/:id/events/:eid`	无 body	将告警事件标记为已解决

通知

告警通知渠道配置（Webhook/Slack/钉钉/飞书/企微/邮件/Telegram 等）。

方法	路径	说明
GET	`/workspaces/:wid/notifications`	通知渠道列表
POST	`/workspaces/:wid/notifications`	创建渠道（webhook/slack/discord/email/钉钉/飞书/企微/Telegram）
PATCH	`/workspaces/:wid/notifications/:id`	更新渠道
DELETE	`/workspaces/:wid/notifications/:id`	删除渠道

参数说明

端点	字段	说明
`POST /workspaces/:wid/notifications`	`name` * `type` * `config` *	渠道名称类型：email / webhook / dingtalk / feishu / wecom / telegram / slack / discord / telegram-bot 渠道配置对象（按类型：webhook_url、token、chat_id、bot_token 等）
`PATCH /workspaces/:wid/notifications/:id`	`name`? `type`? `config`? `isEnabled`?	同创建字段，全部可选；isEnabled 控制启停

Cron 计划任务

定时任务的创建、预览、执行记录。

方法	路径	说明
GET	`/workspaces/:wid/cronjobs`	Cron 任务列表
POST	`/workspaces/:wid/cronjobs`	创建 Cron 任务
POST	`/workspaces/:wid/cronjobs/preview`	预览 Cron 表达式（未来 5 次执行时间）
PATCH	`/workspaces/:wid/cronjobs/:id`	更新任务（含启用/禁用）
DELETE	`/workspaces/:wid/cronjobs/:id`	删除任务
POST	`/workspaces/:wid/cronjobs/:id/run`	立即运行一次
GET	`/workspaces/:wid/cronjobs/:id/executions`	任务执行记录
GET	`/workspaces/:wid/cron-executions`	全部执行记录

参数说明

端点	字段	说明
`POST /workspaces/:wid/cronjobs`	`name` * `cronExpr` * `command` * `targetServers` *	任务名 5 段 cron 表达式要执行的 shell 命令目标服务器 ID 数组（UUID，至少 1 个）
`POST /workspaces/:wid/cronjobs/preview`	`cronExpr` *	cron 表达式，返回下一次执行时间预览
`PATCH /workspaces/:wid/cronjobs/:id`	`name`? `cronExpr`? `command`? `targetServers`? `isEnabled`?	同创建字段，全部可选
`POST /workspaces/:wid/cronjobs/:id/run`	无 body	立即手动执行一次

API Key

为脚本/第三方系统签发长期 API Key。

方法	路径	说明
GET	`/workspaces/:wid/api-keys`	API Key 列表
POST	`/workspaces/:wid/api-keys`	创建 API Key
PATCH	`/workspaces/:wid/api-keys/:id`	更新 Key（启用/禁用）
DELETE	`/workspaces/:wid/api-keys/:id`	删除 Key

参数说明

端点	字段	说明
`POST /workspaces/:wid/api-keys`	`name` * `permissions`? `expiresAt`?	Key 名称权限数组（默认 []）过期时间（ISO 8601 datetime，如 2026-12-31T00:00:00Z）
`PATCH /workspaces/:wid/api-keys/:id`	`name`? `permissions`?	同创建字段，全部可选

成员

工作空间成员与角色管理。

方法	路径	说明
GET	`/workspaces/:wid/members`	工作空间成员列表
PATCH	`/workspaces/:wid/members/:id`	修改成员角色
DELETE	`/workspaces/:wid/members/:id`	移除成员

参数说明

端点	字段	说明
`PATCH /workspaces/:wid/members/:id`	`role` *	角色：owner / editor / viewer

应用商店

预置应用模板，可在目标服务器一键部署。

方法	路径	说明
GET	`/workspaces/:wid/app-store`	应用模板列表
GET	`/workspaces/:wid/app-store/:id`	模板详情
POST	`/workspaces/:wid/app-store`	创建模板
PATCH	`/workspaces/:wid/app-store/:id`	更新模板
DELETE	`/workspaces/:wid/app-store/:id`	删除模板
POST	`/workspaces/:wid/app-store/seed`	导入预置模板

参数说明

端点	字段	说明
`GET /workspaces/:wid/app-store`	`category`? `search`?	分类过滤关键字搜索（query 参数）
`POST /workspaces/:wid/app-store`	`name` * `description`? `category`? `icon`? `composeYaml` * `defaultEnv`? `memoryLimit`? `cpuLimit`? `version`? `author`? `homepage`? `isEnabled`?	应用名描述分类（默认 Tools）图标名（默认 package） docker-compose YAML 内容默认环境变量对象内存限制（如 512m） CPU 限制版本作者主页是否启用
`PATCH /workspaces/:wid/app-store/:id`	同创建	同创建字段，全部可选
`POST /workspaces/:wid/app-store/seed`	无 body	预置内置示例应用

状态页

公开状态页管理；/public/status/:slug 无需认证。

方法	路径	说明
GET	`/workspaces/:wid/status-pages`	状态页列表
POST	`/workspaces/:wid/status-pages`	创建公开状态页
PATCH	`/workspaces/:wid/status-pages/:id`	更新状态页
DELETE	`/workspaces/:wid/status-pages/:id`	删除状态页
GET	`/public/status/:slug`	公开状态页（无需认证）

参数说明

端点	字段	说明
`POST /workspaces/:wid/status-pages`	`name` * `slug` * `customDomain`? `logoUrl`? `theme`?	状态页名称访问路径（小写字母数字连字符）自定义域名 Logo URL 主题配置对象
`PATCH /workspaces/:wid/status-pages/:id`	`name`? `customDomain`? `logoUrl`? `theme`? `isPublished`?	同创建字段，全部可选；isPublished 控制发布状态

Agent 内部接口

Agent 探针回连 Dashboard 使用（X-Agent-Token 认证），一般无需手动调用。

方法	路径	说明
POST	`/agent/register`	Agent 启动注册（Agent Token 认证）
POST	`/agent/heartbeat`	Agent 心跳上报
POST	`/agent/metrics`	Agent 上报指标（CPU/内存/磁盘/网络/GPU）

参数说明

端点	字段	说明
`POST /agent/register`	`agentId` * `hostInfo`?	Agent ID（≤64 字符）主机信息对象
`POST /agent/heartbeat`	`agentId` * `timestamp`? `metrics`?	Agent ID 时间戳指标对象：cpu? / mem? / disk?
`POST /agent/metrics`	`agentId` * `timestamp`? `cpu_percent`? `mem_total`? `mem_used`? `disk_total`? `disk_used`? `net_in_bytes`? `net_out_bytes`? `load_1`? `load_5`? `load_15`? `gpu_name`? `gpu_util_percent`? `gpu_mem_total`? `gpu_mem_used`? `gpu_temp`?	Agent ID 时间戳 CPU 使用率 0-100 内存总量（字节）内存已用（字节）磁盘总量（字节）磁盘已用（字节）网络入/出（字节）负载 1/5/15 分钟 GPU 名称/利用率/显存/温度

MCP

Model Context Protocol 端点，让 Claude/Cursor/Codex 等 AI 助手直接管控基础设施。

方法	路径	说明
POST	`/mcp`	MCP Streamable HTTP 端点（详见 MCP 文档）

调用方式

MCP 使用 JSON-RPC 2.0 格式，认证与普通 API 相同（Bearer JWT）。请求体：{"jsonrpc":"2.0","id":1,"method":"工具名","params":{...}}。可用工具与 REST 能力对应：服务器列表、指标查询、监控任务管理、告警规则/事件、Cron 任务、Shell AI、状态页等。

快速示例

1. 登录

curl -X POST https://agent.yqone.cn/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'

# 返回 { "token": "...", "refresh_token": "...", "user": {...} }

2. 创建工作空间

curl -X POST https://agent.yqone.cn/api/v1/workspaces \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"生产环境"}'

3. 添加服务器并获取 Agent Token

curl -X POST https://agent.yqone.cn/api/v1/workspaces/WID/servers \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"web-01","host":"1.2.3.4","port":22,"username":"root"}'

# 返回中包含 AGENT_TOKEN 与 AGENT_ID，用于一键安装 Agent

4. Shell AI 生成命令（中文 → Shell）

curl -X POST https://agent.yqone.cn/api/v1/workspaces/WID/servers/SID/tools/shell-ai/generate \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"prompt":"帮我看看磁盘还剩多少空间","provider":"custom"}'

# 返回 { "command": "df -h", ... }  —— 默认模型 proberx-coder（Ollama 本地部署）

5. 拉取服务器历史指标

curl "https://agent.yqone.cn/api/v1/workspaces/WID/servers/SID/metrics?from=2026-08-13T00:00:00Z&to=2026-08-14T00:00:00Z" \
  -H "Authorization: Bearer TOKEN"

6. 设置服务器到期时间（到期前 7 天自动告警）

# 设置到期时间（YYYY-MM-DD，精确到天）
curl -X PATCH https://agent.yqone.cn/api/v1/workspaces/WID/servers/SID \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"expiresAt":"2026-12-31"}'

# 清除到期时间
curl -X PATCH https://agent.yqone.cn/api/v1/workspaces/WID/servers/SID \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"expiresAt":null}'

# 系统将自动创建「服务器到期提醒」规则（剩余 ≤7 天触发），到期前推送一次告警

7. 查看服务器资源总览（免面板）

curl "https://agent.yqone.cn/api/v1/workspaces/WID/servers/SID/resource-overview" \
  -H "Authorization: Bearer TOKEN"
# 返回 system / sites / certificates / databases / cronTasks / services / securityScan / network 8 组数据

8. 发起一次 AI 巡检并导出 PDF

# 生成巡检报告
curl -X POST https://agent.yqone.cn/api/v1/workspaces/WID/servers/SID/inspections \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"例行健康巡检"}'

# 用返回的 RID 导出 PDF
curl -OJ "https://agent.yqone.cn/api/v1/workspaces/WID/inspections/RID/pdf" \
  -H "Authorization: Bearer TOKEN"