mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-05-12 11:32:46 +08:00
c629b5f286
重构： - 首页 Hero 重设计：双列布局（标题+CTA+指标 / macOS 风代码窗口） - 引入渐变文字、pulse 徽章、悬停带动画的主按钮 - 功能卡片加 SVG 图标、悬停提升效果、部分卡片变成可点击链接 - 新增 HomepageShowcase 截图轮播区：Tab 切换四个核心页面（仪表盘/任务/存储/多节点） - 全站换 Arco 蓝 (#165dff) 作为主色，紫色 (#8f4bff) 作为辅助 - 导航栏加毛玻璃效果、表格加圆角与边框、菜单项圆角化 - 深色模式配色整体收敛 内容修正： - API 参考补全遗漏的端点：auth logout/profile、records batch-delete、 storage-targets star/usage/google-drive、notifications test、dashboard timeline、settings - 把 API 表格改为"方法/端点/说明"三列，加响应结构说明 - 中英文 API 文档同步更新 i18n： - code.json 补充 Hero、Features、Showcase 全部新翻译键 - 校对：16 个中英文档 frontmatter 完全对齐，无漏译 构建：双语 build 通过、产物 3.3MB
136 lines
4.9 KiB
Markdown
136 lines
4.9 KiB
Markdown
---
|
|
sidebar_position: 1
|
|
title: API Reference
|
|
description: REST API endpoints — all under /api with JWT Bearer authentication.
|
|
---
|
|
|
|
# API Reference
|
|
|
|
All endpoints are prefixed with `/api` and authenticated with a JWT Bearer token, obtained via `POST /api/auth/login`. Agent endpoints use `X-Agent-Token` instead.
|
|
|
|
## Authentication
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/auth/setup/status` | Check whether admin initialization is needed |
|
|
| `POST` | `/api/auth/setup` | Initialize the first admin (only when no user exists) |
|
|
| `POST` | `/api/auth/login` | Log in and receive a JWT |
|
|
| `POST` | `/api/auth/logout` | Log out (invalidate current token) |
|
|
| `GET` | `/api/auth/profile` | Current user profile |
|
|
| `PUT` | `/api/auth/password` | Change password |
|
|
|
|
## Backup Tasks
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/backup/tasks` | List tasks |
|
|
| `POST` | `/api/backup/tasks` | Create |
|
|
| `GET` | `/api/backup/tasks/:id` | Detail |
|
|
| `PUT` | `/api/backup/tasks/:id` | Update |
|
|
| `DELETE` | `/api/backup/tasks/:id` | Delete |
|
|
| `PUT` | `/api/backup/tasks/:id/toggle` | Enable / disable |
|
|
| `POST` | `/api/backup/tasks/:id/run` | Trigger a manual run |
|
|
|
|
## Backup Records
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/backup/records` | List records with filters |
|
|
| `GET` | `/api/backup/records/:id` | Record detail |
|
|
| `GET` | `/api/backup/records/:id/logs/stream` | Live logs (SSE) |
|
|
| `GET` | `/api/backup/records/:id/download` | Download the artifact |
|
|
| `POST` | `/api/backup/records/:id/restore` | Restore to the original source |
|
|
| `DELETE` | `/api/backup/records/:id` | Delete a record |
|
|
| `POST` | `/api/backup/records/batch-delete` | Bulk delete |
|
|
|
|
## Storage Targets
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/storage-targets` | List |
|
|
| `POST` | `/api/storage-targets` | Create |
|
|
| `GET` | `/api/storage-targets/:id` | Detail |
|
|
| `PUT` | `/api/storage-targets/:id` | Update |
|
|
| `DELETE` | `/api/storage-targets/:id` | Delete |
|
|
| `POST` | `/api/storage-targets/test` | Test connection with pending config |
|
|
| `POST` | `/api/storage-targets/:id/test` | Re-test a saved target |
|
|
| `PUT` | `/api/storage-targets/:id/star` | Toggle favourite |
|
|
| `GET` | `/api/storage-targets/:id/usage` | Query remote usage (where supported) |
|
|
| `GET` | `/api/storage-targets/rclone/backends` | List all available rclone backends |
|
|
| `POST` | `/api/storage-targets/google-drive/auth-url` | Start Google Drive OAuth |
|
|
| `POST` | `/api/storage-targets/google-drive/complete` | Complete OAuth flow |
|
|
|
|
## Nodes (Cluster)
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/nodes` | List nodes |
|
|
| `POST` | `/api/nodes` | Create a node and return its token |
|
|
| `GET` | `/api/nodes/:id` | Node detail |
|
|
| `PUT` | `/api/nodes/:id` | Rename |
|
|
| `DELETE` | `/api/nodes/:id` | Delete (rejected if tasks are still attached) |
|
|
| `GET` | `/api/nodes/:id/fs/list` | Browse a directory (remote nodes use an async RPC via Agent) |
|
|
|
|
## Agent Protocol (X-Agent-Token)
|
|
|
|
Dedicated endpoints for the Agent CLI. Authenticated via the `X-Agent-Token` header instead of JWT.
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `POST` | `/api/agent/heartbeat` | Report liveness; returns the node ID |
|
|
| `POST` | `/api/agent/commands/poll` | Claim one pending command |
|
|
| `POST` | `/api/agent/commands/:id/result` | Report command result |
|
|
| `GET` | `/api/agent/tasks/:id` | Fetch task spec with decrypted storage configs |
|
|
| `POST` | `/api/agent/records/:id` | Append logs / update record status |
|
|
|
|
## Notifications
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/notifications` | List |
|
|
| `POST` | `/api/notifications` | Create |
|
|
| `GET` | `/api/notifications/:id` | Detail |
|
|
| `PUT` | `/api/notifications/:id` | Update |
|
|
| `DELETE` | `/api/notifications/:id` | Delete |
|
|
| `POST` | `/api/notifications/test` | Test with pending config |
|
|
| `POST` | `/api/notifications/:id/test` | Re-test a saved notifier |
|
|
|
|
## Dashboard
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/dashboard/stats` | Overview statistics |
|
|
| `GET` | `/api/dashboard/timeline` | Recent activity timeline |
|
|
|
|
## Audit / System / Settings
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/audit-logs` | Audit log list |
|
|
| `GET` | `/api/system/info` | System information |
|
|
| `GET` | `/api/system/update-check` | Check for a newer release |
|
|
| `GET` | `/api/settings` | System-level settings |
|
|
| `PUT` | `/api/settings` | Update system settings |
|
|
|
|
## Response Envelope
|
|
|
|
All successful responses follow the shape:
|
|
|
|
```json
|
|
{
|
|
"code": "OK",
|
|
"message": "",
|
|
"data": { /* actual payload */ }
|
|
}
|
|
```
|
|
|
|
Errors return an HTTP 4xx/5xx plus:
|
|
|
|
```json
|
|
{
|
|
"code": "BACKUP_TASK_NOT_FOUND",
|
|
"message": "备份任务不存在",
|
|
"data": null
|
|
}
|
|
```
|