ProberX API 文档

Dashboard 开放 HTTP API，覆盖认证、工作空间、服务器、监控、告警、通知、Cron、运维工具等全部能力，共 150+ 端点。

概览

所有 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 安装包下载地址（可选，缺省用最新版）

文件与防火墙

通过 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

监控探测

从 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. 拉取服务器历史指标

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 天触发），到期前推送一次告警

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"