备份 API

当前公共 API 提供备份历史查询和配置内容读取，不提供触发备份、删除备份或修改备份记录的端点。备份通常由 Web 界面、调度器或任务系统产生。

查询设备备份历史

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

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

查询参数：

参数	类型	默认值	说明
`page`	integer	`1`	页码，最小值为 `1`
`limit`	integer	`10`	每页数量，范围 `1-200`

成功响应使用统一分页结构：

{
  "items": [
    {
      "id": "0f4e5e1b-8a95-4b3b-9b5b-7e9c7d2e0f10",
      "started_at": "2026-08-14 10:00:00",
      "finished_at": "2026-08-14 10:00:08",
      "success": true,
      "error_message": null,
      "config_snapshot_hash": "sha256-or-snapshot-hash"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

备份记录字段：

字段	类型	说明
`id`	string	备份记录 UUID
`started_at`	string	开始时间，按请求上下文时区格式化
`finished_at`	string/null	完成时间；未完成时为 `null`
`success`	boolean	备份是否成功
`error_message`	string/null	失败原因；成功时通常为 `null`
`config_snapshot_hash`	string/null	配置快照哈希；没有快照时为 `null`

设备不存在时返回 BACKUP_DEVICE_NOT_FOUND 或资源不存在错误；设备超出 API Key 用户的设备组范围时返回 BACKUP_DEVICE_FORBIDDEN 或设备访问拒绝错误。

获取备份配置内容

GET /api/v1/backups/{backup_id}/content

路径参数：

参数	类型	说明
`backup_id`	UUID	备份记录 ID，使用备份历史返回的 `items[].id`

所需权限：backups.view。成功响应：

{
  "config_text": "! configuration snapshot\\n..."
}

记录不存在时返回 BACKUP_NOT_FOUND。记录存在但没有可用配置文本时，config_text 为 null；调用方不要仅凭 HTTP 200 判断配置内容一定存在。

数据安全

配置备份可能包含公网地址、账号引用、SNMP 字符串或其他敏感信息。调用方应使用只拥有 backups.view 的 API Key，避免把完整配置写入应用日志、监控标签、Issue 或第三方工单系统。

查询设备备份历史​

获取备份配置内容​

推荐调用流程​

数据安全​

查询设备备份历史

获取备份配置内容

推荐调用流程

数据安全