设备 API

设备相关端点位于 /api/v1 下。所有请求都需要 X-API-Key；各操作还需要对应的设备或备份权限。

端点一览

方法	路径	权限	说明
GET	/api/v1/devices	devices.view	分页查询设备
GET	/api/v1/devices/unreachable	devices.view	查询可达性状态为离线的设备
GET	/api/v1/devices/{device_id}	devices.view	查询设备详情
POST	/api/v1/devices	devices.create	创建设备
PUT	/api/v1/devices/{device_id}	devices.update	更新设备
DELETE	/api/v1/devices/{device_id}	devices.delete	删除设备
GET	/api/v1/devices/{device_id}/backups	backups.view	查询设备备份历史

查询设备

GET /api/v1/devices?q=core&group_id=1&page=1&limit=50

查询参数：

参数	类型	默认值	说明
q	string	—	在设备名称或地址中进行包含匹配
group_id	integer	—	按分组筛选，同时包含该分组的子分组
page	integer	1	页码，最小值为 1
limit	integer	50	每页数量，范围 1-100

所需权限：devices.view。响应为统一分页结构，items 中的每一项都是设备对象。

查询不可达设备

GET /api/v1/devices/unreachable?page=1&limit=50

所需权限：devices.view。该接口固定筛选 reachability_status=false，响应格式与设备列表相同。状态为 null（尚未检查）的设备不会被此接口返回。

获取单台设备

GET /api/v1/devices/{device_id}

路径参数 device_id 为整数。所需权限：devices.view。

设备对象字段：

字段	类型	说明
id	integer	设备 ID
name	string	设备名称
host	string	主机名或 IP 地址
port	integer	SSH/Telnet 端口
login_method	string	ssh 或 telnet
encoding	string	配置输出编码
platform	string	平台标识，例如 cisco_ios
group_id	integer/null	所属分组 ID；null 表示未分组
credential_id	integer/null	使用的凭据 ID
default_template_id	integer/null	默认备份模板 ID
created_at	string	创建时间，JSON datetime 字符串
reachability_status	boolean/null	最近一次可达性状态
last_reachability_check	string/null	最近一次可达性检查时间
reachability_error	string/null	最近一次检查错误
reachability_duration_ms	integer/null	最近一次检查耗时（毫秒）

示例：

{
  "id": 1,
  "name": "core-sw-01",
  "host": "192.0.2.10",
  "port": 22,
  "login_method": "ssh",
  "encoding": "utf-8",
  "platform": "cisco_ios",
  "group_id": 1,
  "credential_id": 1,
  "default_template_id": 1,
  "created_at": "2026-08-14T10:00:00",
  "reachability_status": true,
  "last_reachability_check": "2026-08-14T10:05:00",
  "reachability_error": null,
  "reachability_duration_ms": 182
}

创建设备

POST /api/v1/devices
Content-Type: application/json

所需权限：devices.create。成功响应状态码为 201 Created。

请求字段：

字段	类型	必填	默认值	说明
name	string	是	—	设备名称，不能重复
host	string	是	—	主机名或 IP 地址
port	integer	否	22	连接端口
login_method	string	否	ssh	支持 ssh、telnet
encoding	string	否	utf-8	支持 utf-8、gb18030、gbk、gb2312
platform	string	是	—	平台标识，参见设备厂商支持列表
group_id	integer	否	0	0 表示未分组
credential_id	integer	是	—	已存在的凭据 ID
default_template_id	integer	否	0	默认备份模板 ID；0 表示不设置

示例：

{
  "name": "core-sw-01",
  "host": "192.0.2.10",
  "port": 22,
  "login_method": "ssh",
  "encoding": "utf-8",
  "platform": "cisco_ios",
  "group_id": 1,
  "credential_id": 1,
  "default_template_id": 1
}

创建时会校验凭据和模板是否存在；如果设置模板，还会校验模板平台与设备平台是否兼容。设备名称以及 host + port 组合必须唯一。

更新设备

PUT /api/v1/devices/{device_id}
Content-Type: application/json

所需权限：devices.update。请求体字段均可选，未提供的字段保持原值：

{
  "port": 2222,
  "encoding": "utf-8",
  "credential_id": 2
}

更新同样会校验目标分组、凭据、模板和平台兼容性，并且会检查设备名称及 host + port 的唯一性。

删除设备

DELETE /api/v1/devices/{device_id}

所需权限：devices.delete。成功响应：

{
  "status": "success"
}

存在活动备份任务时不能删除设备，接口返回 409，错误码为 DEVICE_DELETE_ACTIVE_BACKUPS。

查询设备备份历史

GET /api/v1/devices/{device_id}/backups?page=1&limit=10

所需权限：backups.view。该接口默认每页 10 条，limit 范围为 1-200。返回字段和备份内容读取方式见备份 API。设备及其备份历史会按 API Key 用户的设备组范围校验。

常见业务错误码

错误码	HTTP 状态	说明
DEVICE_NOT_FOUND	404	设备不存在
DEVICE_ACCESS_FORBIDDEN	403	设备不在当前用户可访问的设备组范围内
DEVICE_NAME_EXISTS	400	设备名称已存在
DEVICE_HOST_EXISTS	400	主机地址与端口组合已存在
DEVICE_CREDENTIAL_NOT_FOUND	400	指定凭据不存在
DEVICE_TEMPLATE_NOT_FOUND	400	指定模板不存在
DEVICE_TEMPLATE_PLATFORM_MISMATCH	400	模板平台与设备平台不兼容
DEVICE_TELNET_PLATFORM_UNSUPPORTED	400	该平台不支持 Telnet
DEVICE_DELETE_ACTIVE_BACKUPS	409	设备存在活动备份任务