API 概览
本文档描述 EasyNetBak 的版本化公共 API。它与页面内部使用的 /api/ 接口不是同一套接口；对外集成请只使用 /api/v1/。
基础地址与版本
将 <server> 替换为 EasyNetBak 的访问地址：
https://<server>/api/v1
当前公共 API 共覆盖设备、分组、凭据、备份模板、备份记录和系统统计。
认证
所有 /api/v1/ 请求都必须携带 X-API-Key：
X-API-Key: nb_your_api_key
API Key 在 Web 管理界面的 API Key 页面创建，需要 api_keys.create 权限。完整明文 Key 只在创建完成时显示一次；服务端只保存哈 希值。API Key 失效、过期或被删除后不能继续使用。
API Key 绑定到创建它的用户，API 请求仍会使用该用户的角色和权限进行校验。API Key 不会绕过权限检查，也不会回退使用浏览器 Session Cookie。
示例：
curl "http://localhost:8000/api/v1/stats" \
-H "X-API-Key: nb_your_api_key"
不要把 Key 放在 URL 查询参数中，也不要写入 Git、普通业务日志或监控标签。
当前端点
| 资源 | 方法 | 路径 | 所需权限 |
|---|---|---|---|
| 设备 | GET | /devices | devices.view |
| 设备 | GET | /devices/unreachable | devices.view |
| 设备 | GET | /devices/{device_id} | devices.view |
| 设备 | POST | /devices | devices.create |
| 设备 | PUT | /devices/{device_id} | devices.update |
| 设备 | DELETE | /devices/{device_id} | devices.delete |
| 设备备份历史 | GET | /devices/{device_id}/backups | backups.view |
| 分组 | GET | /groups | groups.view |
| 分组 | GET | /groups/tree | groups.view |
| 分组 | GET | /groups/{group_id} | groups.view |
| 分组 | POST | /groups | groups.create |
| 分组 | PUT | /groups/{group_id} | groups.update |
| 分组 | DELETE | /groups/{group_id} | groups.delete |
| 凭据 | GET | /credentials | credentials.view |
| 凭据 | GET | /credentials/{credential_id} | credentials.view |
| 凭据 | POST | /credentials | credentials.create |
| 凭据 | PUT | /credentials/{credential_id} | credentials.update |
| 凭据 | DELETE | /credentials/{credential_id} | credentials.delete |
| 备份模板 | GET | /templates | templates.view |
| 备份模板 | GET | /templates/{template_id} | templates.view |
| 备份模板 | POST | /templates | templates.create |
| 备份模板 | PUT | /templates/{template_id} | templates.update |
| 备份模板 | DELETE | /templates/{template_id} | templates.delete |
| 备份内容 | GET | /backups/{backup_id}/content | backups.view |
| 系统统计 | GET | /stats | dashboard.view |
管理员角色默认拥有全部权限。具体请求字段和响应模型见左侧各资源页面。
数据范围与权限边界
- 设备列表、不可达设备、设备详情、更新、删除以及设备备份历史会按用户的设备组范围过滤或校验。
- 读取备份内容也会校验备份所属设备是否在用户可见设备组内。
- 当前
POST /devices实现只检查devices.create，创建时的group_id不额外执行设备组范围校验。 - 分组、凭据、备份模板和系统统计接口当前按权限校验；这些公共 API 路由本身不额外应用设备组过滤。
分页
列表接口使用 page 和 limit：
GET /api/v1/devices?page=1&limit=50
普通列表默认 page=1、limit=50，limit 范围为 1-100。设备备份历史默认 limit=10，范围为 1-200。页码从 1 开始。
分页响应统一包含：
{
"items": [],
"pagination": {
"page": 1,
"limit": 50,
"total": 0,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}
当没有数据时，total 为 0，total_pages 仍为 1。
成功响应
GET：200 OKPOST：201 CreatedPUT：200 OKDELETE：200 OK，正文通常为{ "status": "success" }
错误响应
API 错误统一使用以下结构：
{
"error": {
"code": "PERMISSION_DENIED",
"message": "Permission denied",
"request_id": "request-id-from-response-header",
"details": {}
}
}
常见状态码：
| 状态码 | 常见 code | 含义 |
|---|---|---|
400 | 业务错误码 | 请求内容不满足业务规则 |
401 | UNAUTHORIZED | 缺少、无效、过期或已失效的 API Key |
403 | PERMISSION_DENIED | 用户缺少接口所需权限，或资源超出设备组范围 |
404 | RESOURCE_NOT_FOUND 或资源专用错误码 | 资源不存在 |
409 | CONFLICT 或资源专用错误码 | 当前资源状态不允许操作 |
422 | VALIDATION_ERROR | 查询参数或 JSON 请求体校验失败 |
500 | INTERNAL_ERROR | 服务端内部错误 |
校验失败时，详细字段错误位于 error.details.errors。业务错误的 code 可能是 DEVICE_NAME_EXISTS、RESOURCE_CREDENTIAL_IN_USE 等资源专用代码，具体见对应页面。
每个响应都会带有 X-Request-ID，错误正文中的 error.request_id 与该响应头一致。排查问题时请保留这个 ID。
OpenAPI 与交互式文档
运行 EasyNetBak 后，可以访问：
- Swagger UI：
http://localhost:8000/docs?lang=zh-CN - OpenAPI JSON：
http://localhost:8000/openapi.json?lang=zh-CN
Swagger UI 用于确认当前运行版本实际生成的参数、响应模型和错误响应；本页的手工说明用于解释接口约定和使用边界。