REST API 参考

219 端点，覆盖所有功能，适合自动化集成与二次开发

基础信息

Ginkgo Backup 在本地 127.0.0.1:9275 提供 REST API。所有响应为 JSON，时间戳为 Unix 微秒（int64），列表端点支持 limit/offset 分页。Pro 专属端点以 (Pro) 标注。

Base URL

http://127.0.0.1:9275

认证

所有 /api/v1/ 端点（/health 和 /settings/ca-cert 除外）需要 Bearer Token 认证。Token 在首次启动时自动生成并保存到 ~/.ginkgo-backup/config.json。本地连接可根据配置自动认证。

Header

Authorization: Bearer <token>

速率限制

600 请求/分钟。建议轮询间隔：备份进度 500ms、监控状态 3s、检查点 30s、挂载状态 5s。

响应格式

成功响应直接返回 JSON 对象或数组。错误响应：

Error

{
  "error": "description of the error",
  "code": "ERROR_CODE"
}

分页

列表端点支持 limit 和 offset 参数，响应包含：

Example

{
  "items": [...],
  "total": 1000,
  "has_more": true
}

端点列表

健康检查

方法	路径	说明
GET	`/api/v1/health`	服务器健康检查（无需认证）
GET	`/health`	/api/v1/health 的别名

认证

方法	路径	说明
POST	`/api/v1/auth/login`	登录并获取会话 Token
POST	`/api/v1/auth/logout`	使当前会话失效
GET	`/api/v1/auth/status`	查询认证状态（未设置密码时返回 needs_setup）
POST	`/api/v1/auth/setup-password`	设置初始密码（首次配置）
GET	`/api/v1/auth/login-audit`	列出登录审计日志
POST	`/api/v1/auth/revoke-sessions`	吊销所有其他会话
GET	`/api/v1/auth/totp/status`	查询 TOTP 2FA 状态
POST	`/api/v1/auth/totp/setup`	开始 TOTP 2FA 设置
POST	`/api/v1/auth/totp/confirm`	使用验证码确认 TOTP 2FA
POST	`/api/v1/auth/totp/disable`	禁用 TOTP 2FA

系统状态

方法	路径	说明
GET	`/api/v1/status`	系统状态概览
GET	`/api/v1/index/health`	索引数据库健康检查
GET	`/api/v1/index/dedup`	去重统计
GET	`/api/v1/index/stats`	索引统计
POST	`/api/v1/index/compact`	压缩索引数据库
POST	`/api/v1/index/fix-first-seen`	修复首次出现时间戳
GET	`/api/v1/watch/status`	文件监控服务状态

备份源

方法	路径	说明
GET	`/api/v1/sources`	列出所有备份源
POST	`/api/v1/sources`	创建备份源
GET	`/api/v1/sources/{id}`	获取备份源详情
PUT	`/api/v1/sources/{id}`	更新备份源配置
DELETE	`/api/v1/sources/{id}`	删除备份源

备份操作

方法	路径	说明
POST	`/api/v1/backup/run`	触发备份
POST	`/api/v1/backup/preflight`	备份前预检（估算大小、检查磁盘）
GET	`/api/v1/backup/progress`	获取当前备份进度
GET	`/api/v1/backup/state`	获取备份状态（idle/running/error）
POST	`/api/v1/backup/cancel`	取消运行中的备份
GET	`/api/v1/backup/checkpoints`	列出备份检查点
GET	`/api/v1/backup/checkpoints/{id}`	获取检查点详情
GET	`/api/v1/backup/recover-sessions`	列出可恢复的备份会话

快照

方法	路径	说明
GET	`/api/v1/snapshots`	列出快照（query: source_id）
GET	`/api/v1/snapshots/{id}`	获取快照详情
GET	`/api/v1/snapshots/changes`	列出快照内文件变更
GET	`/api/v1/snapshots/space-estimate`	估算快照占用空间

文件浏览与历史

方法	路径	说明
GET	`/api/v1/files`	浏览快照内文件（支持 FTS5 搜索）
GET	`/api/v1/history`	获取文件版本历史
GET	`/api/v1/history/content`	获取指定版本的文件内容
GET	`/api/v1/history/diff`	对比两个版本的差异
GET	`/api/v1/history/download-zip`	以 zip 形式下载多个文件
GET	`/api/v1/history/download-file`	下载单个文件
POST	`/api/v1/history/restore`	从快照恢复单个文件

恢复任务

方法	路径	说明
POST	`/api/v1/restore`	启动恢复任务（批量）
GET	`/api/v1/restore/tasks`	列出恢复任务
GET	`/api/v1/restore/{id}`	获取恢复任务状态

仓库

方法	路径	说明
GET	`/api/v1/repositories`	列出所有仓库
POST	`/api/v1/repositories`	创建仓库
GET	`/api/v1/repositories/{id}`	获取仓库详情
PUT	`/api/v1/repositories/{id}`	更新仓库
DELETE	`/api/v1/repositories/{id}`	删除仓库
GET	`/api/v1/repo/compression-stats`	获取压缩统计
POST	`/api/v1/repo/scan`	扫描仓库已有数据
POST	`/api/v1/repo/connect`	连接到已有仓库
POST	`/api/v1/repo/sources-scan`	扫描仓库中的备份源
POST	`/api/v1/repo/import`	向仓库导入数据
POST	`/api/v1/repo/delete-source-data`	从仓库删除备份源数据
GET	`/api/v1/repo/is-encrypted`	检查仓库是否加密
POST	`/api/v1/repo/unlock`	解锁被锁定的仓库

GBF 底层操作

方法	路径	说明
POST	`/api/v1/gb/init`	初始化 GBF 仓库
POST	`/api/v1/gb/backup/run`	触发 GBF 备份
POST	`/api/v1/gb/restore`	从 GBF 快照恢复
POST	`/api/v1/gb/gc`	对 GBF 仓库运行垃圾回收
GET	`/api/v1/gb/snapshots`	列出 GBF 快照
POST	`/api/v1/gb/format`	格式化 GBF 仓库
POST	`/api/v1/gb/retention`	对 GBF 仓库应用保留策略

云存储

方法	路径	说明
GET	`/api/v1/cloud/backends`	列出云后端
POST	`/api/v1/cloud/backends`	创建云后端
GET	`/api/v1/cloud/backends/{id}`	获取后端详情
PUT	`/api/v1/cloud/backends/{id}`	更新后端
DELETE	`/api/v1/cloud/backends/{id}`	删除后端
POST	`/api/v1/cloud/backends/{id}/reauth`	重新授权后端
POST	`/api/v1/cloud/backends/{id}/clear-cache`	清除后端缓存
POST	`/api/v1/cloud/test`	测试云连接
GET	`/api/v1/cloud/oauth2/start`	启动 OAuth2 流程
GET	`/api/v1/cloud/oauth2/status`	查询 OAuth2 状态
GET	`/api/v1/cloud/oauth2/callback`	OAuth2 回调（无需认证）
POST	`/api/v1/cloud/oauth2/submit-code`	提交 OAuth2 授权码
GET	`/api/v1/cloud/sources`	发现云备份源

同步任务

方法	路径	说明
GET	`/api/v1/sync/jobs`	列出同步任务
GET	`/api/v1/pending-syncs`	列出待处理同步

保留与 GC

方法	路径	说明
POST	`/api/v1/retention/apply`	应用保留策略
POST	`/api/v1/retention/gc`	运行垃圾回收
GET	`/api/v1/retention/gc/status`	获取 GC 状态
GET	`/api/v1/retention/gc/directives`	获取 GC 指令
POST	`/api/v1/retention/verify`	验证备份完整性
POST	`/api/v1/retention/cloud-gc`	运行云端 GC
GET	`/api/v1/retention/cloud-gc/status`	获取云端 GC 状态
POST	`/api/v1/retention/cloud-maintenance`	运行云端维护
POST	`/api/v1/retention/delete-snapshots`	删除指定快照
POST	`/api/v1/retention/remove-source-manifests`	移除备份源清单
POST	`/api/v1/retention/reset-safety`	重置保留安全计数器

数据库维护

方法	路径	说明
POST	`/api/v1/database/vacuum`	对主 SQLite 数据库执行 vacuum
POST	`/api/v1/database/integrity-check`	运行 SQLite 完整性检查
GET	`/api/v1/databases`	列出外部数据库
GET	`/api/v1/databases/check-tool`	检查数据库备份工具是否已安装
POST	`/api/v1/databases/create`	注册外部数据库
GET	`/api/v1/databases/{id}`	获取数据库详情
POST	`/api/v1/databases/{id}/update`	更新数据库配置
POST	`/api/v1/databases/{id}/delete`	删除数据库记录
POST	`/api/v1/databases/{id}/test`	测试数据库连接
POST	`/api/v1/databases/{id}/backup`	触发数据库备份
GET	`/api/v1/databases/{id}/tasks`	列出数据库备份任务
GET	`/api/v1/maintenance/scheduler/status`	获取维护调度器状态

监控与巡逻

方法	路径	说明
GET	`/api/v1/oversight/health`	系统健康概览
GET	`/api/v1/oversight/alerts`	列出活跃告警
GET	`/api/v1/oversight/alerts/{id}`	获取告警详情
GET	`/api/v1/oversight/cleanup-logs`	列出清理/GC 日志
POST	`/api/v1/oversight/delete-audit`	删除审计日志
GET	`/api/v1/oversight/delete-audit/stats`	获取删除审计统计
POST	`/api/v1/oversight/patrol`	运行巡逻检查
GET	`/api/v1/oversight/patrol/history`	获取巡逻历史
POST	`/api/v1/oversight/verify`	运行验证
POST	`/api/v1/oversight/repair`	运行修复操作

跨仓库保护（防勒索）

方法	路径	说明
POST	`/api/v1/cross-repo/backup`	跨仓库配置备份
GET	`/api/v1/cross-repo/alerts`	列出跨仓库告警
POST	`/api/v1/cross-repo/alerts/clear`	清除跨仓库告警
POST	`/api/v1/cross-repo/recover`	跨仓库恢复
POST	`/api/v1/cross-repo/replicate`	跨仓库复制
POST	`/api/v1/cross-repo/classify-path`	分类文件路径
POST	`/api/v1/cross-repo/vault-snapshot`	创建保险库快照
POST	`/api/v1/cross-repo/config-snapshot`	创建配置快照
POST	`/api/v1/cross-repo/config-restore`	从配置快照恢复
POST	`/api/v1/cross-repo/verify-alerts`	验证跨仓库告警
POST	`/api/v1/cross-repo/ransomware-lock`	启用勒索锁

设置

方法	路径	说明
GET	`/api/v1/settings`	获取应用设置
PUT	`/api/v1/settings`	更新应用设置
GET	`/api/v1/settings/api-info`	获取 API 信息（版本、端口、TLS）
GET	`/api/v1/settings/cli-status`	检查 CLI 安装状态
POST	`/api/v1/settings/install-cli`	安装 CLI 到用户 PATH
POST	`/api/v1/settings/uninstall-cli`	从 PATH 卸载 CLI
GET	`/api/v1/settings/ca-cert`	下载 CA 证书（公开，无需认证）
GET	`/api/v1/settings/ca-trust-status`	检查 CA 信任状态
POST	`/api/v1/settings/trust-ca`	将 CA 安装到信任存储
GET	`/api/v1/settings/tls-sans`	列出 TLS SANs
POST	`/api/v1/settings/restart`	重启服务器
POST	`/api/v1/settings/regenerate-token`	重新生成 API Token
PUT	`/api/v1/settings/webui-password`	修改 WebUI 密码

配置保险库

方法	路径	说明
GET	`/api/v1/config-vault/targets`	列出保险库目标
POST	`/api/v1/config-vault/targets`	创建保险库目标
GET	`/api/v1/config-vault/targets/{id}`	获取保险库目标
PUT	`/api/v1/config-vault/targets/{id}`	更新保险库目标
DELETE	`/api/v1/config-vault/targets/{id}`	删除保险库目标
POST	`/api/v1/config-vault/backup`	运行配置保险库备份
GET	`/api/v1/config-vault/health`	获取保险库健康状态

加密密钥

方法	路径	说明
POST	`/api/v1/keys/export`	导出加密密钥
POST	`/api/v1/keys/import`	导入加密密钥

灾难恢复

方法	路径	说明
POST	`/api/v1/recovery/start`	启动灾难恢复
POST	`/api/v1/recovery/cancel`	取消恢复
GET	`/api/v1/recovery/progress`	获取恢复进度
POST	`/api/v1/recovery-code/export`	导出恢复码
POST	`/api/v1/recovery-code/import`	导入恢复码

AI 集成

方法	路径	说明
POST	`/api/v1/integrations/ai/sync`	将 AI 工具规则文件同步到项目
GET	`/api/v1/integrations/ai/status`	获取 AI 集成状态
GET	`/api/v1/integrations/ai/diagnostics`	获取 AI 诊断上下文
GET	`/api/v1/integrations/ai/skill-templates`	获取 AI 技能模板预设
POST	`/api/v1/ai/generate-note`	生成 AI 快照备注
POST	`/api/v1/ai/diagnose`	运行 AI 诊断（Pro）
POST	`/api/v1/ai/repair`	运行 AI 引导修复（Pro）
POST	`/api/v1/ai/skill`	调用 AI 技能（Pro）

置顶与备注

方法	路径	说明
GET	`/api/v1/pins`	列出置顶快照
POST	`/api/v1/pins/create`	置顶快照（保护不被 GC）
POST	`/api/v1/pins/delete`	取消置顶
GET	`/api/v1/notes`	列出快照备注
POST	`/api/v1/notes/cleanup-orphaned`	清理孤立备注
POST	`/api/v1/notes/sync`	将备注同步到云端

会话与日志

方法	路径	说明
GET	`/api/v1/sessions`	列出备份会话
GET	`/api/v1/sessions/{id}`	获取会话详情
GET	`/api/v1/sessions/stats`	获取会话统计
GET	`/api/v1/logs`	列出操作日志
GET	`/api/v1/logs/stats`	获取日志统计
GET	`/api/v1/logs/raw`	获取原始日志条目

暂存区

方法	路径	说明
POST	`/api/v1/staging/push`	推送文件到暂存区（通用，保留 note_source）
POST	`/api/v1/staging/push-ai`	推送文件并标记为 AI 生成（强制 note_source=ai）
GET	`/api/v1/staging/session`	获取当前暂存会话

挂载与 WebDAV

方法	路径	说明
POST	`/api/v1/mount/{source_id}`	将快照挂载为文件系统
GET	`/api/v1/webdav/session`	获取 WebDAV 会话信息
*	`/webdav/`	WebDAV 文件访问（所有方法）

文件系统操作

方法	路径	说明
GET	`/api/v1/fs/browse`	浏览本地文件系统
POST	`/api/v1/fs/mkdir`	创建目录

通知

方法	路径	说明
GET	`/api/v1/notify/config`	获取通知配置
POST	`/api/v1/notify/test-email`	发送测试邮件
POST	`/api/v1/notify/test-webhook`	发送测试 Webhook

Bug 报告

方法	路径	说明
GET	`/api/v1/bug-reports`	列出 Bug 报告
GET	`/api/v1/bug-reports/{id}`	获取 Bug 报告详情

许可证

方法	路径	说明
GET	`/api/v1/license/info`	获取许可证信息
POST	`/api/v1/license/activate`	激活许可证密钥
POST	`/api/v1/license/deactivate`	停用许可证
POST	`/api/v1/license/handshake`	与服务器验证许可证

组网备份

方法	路径	说明
POST	`/peer/pair`	配对组网设备（邀请码，无需认证）
GET	`/peer/ping`	组网 Ping（peer token 认证）
GET	`/peer/repos`	列出 peer 接收仓库（peer token）
POST	`/peer/sync/{...}`	开始/提交/失败一个同步会话（peer token）
POST	`/peer/blob/{...}`	上传 blob 到 peer 仓库（peer token）
GET	`/peer/list`	列出 peer 上的 blob（peer token）
GET	`/api/v1/peers`	列出已配对 peer（WebUI）
POST	`/api/v1/peers/invite`	生成 peer 邀请
POST	`/api/v1/peers/pair`	从本地发起配对
GET	`/api/v1/peers/{id}`	获取 peer 详情
GET	`/api/v1/peer/discover`	在局域网中发现 peer
GET	`/api/v1/peer-repos`	列出本地接收仓库
GET	`/api/v1/peer-repos/{id}`	获取接收仓库详情

插件（Pro）

方法	路径	说明
GET	`/api/v1/plugins`	列出插件（Pro）
POST	`/api/v1/plugins/detect`	检测已安装插件（Pro）
POST	`/api/v1/plugins/create-source`	从插件创建备份源（Pro）
POST	`/api/v1/plugins/enable`	启用插件（Pro）
POST	`/api/v1/plugins/disable`	禁用插件（Pro）
POST	`/api/v1/plugins/config`	配置插件（Pro）
GET	`/api/v1/plugins/dependencies`	列出插件依赖（Pro）
POST	`/api/v1/plugins/reload`	重新加载插件（Pro）
POST	`/api/v1/plugins/restore`	从插件快照恢复（Pro）
GET	`/api/v1/plugins/snapshots`	列出插件快照（Pro）

Notion 集成（Pro）

方法	路径	说明
GET/POST	`/api/v1/notion/config`	获取/设置 Notion 配置（Pro）
GET	`/api/v1/notion/accounts`	列出 Notion 账户
POST	`/api/v1/notion/sync`	触发 Notion 同步（Pro）
POST	`/api/v1/notion/test`	测试 Notion 连接（Pro）
POST	`/api/v1/notion/auto-setup`	自动设置 Notion 集成（Pro）
POST	`/api/v1/notion/delete`	删除 Notion 账户（Pro）
POST	`/api/v1/notion/re-render`	重新渲染 Notion 内容（Pro）
GET	`/api/v1/notion/pages`	列出 Notion 页面（Pro）
GET	`/api/v1/notion/page/{id}`	获取 Notion 页面内容（Pro）
GET	`/api/v1/notion/page-versions`	列出页面版本（Pro）
POST	`/api/v1/notion/export`	导出 Notion 页面（Pro）
GET	`/api/v1/notion/snapshots`	列出 Notion 快照（Pro）
GET	`/api/v1/notion/attachment`	获取 Notion 附件（Pro）
POST	`/api/v1/notion/mount`	挂载 Notion 工作区（Pro）
POST	`/api/v1/notion/unmount`	卸载 Notion 工作区（Pro）
GET	`/api/v1/notion/mount-list`	列出 Notion 挂载（Pro）

团队（Pro）

方法	路径	说明
POST	`/api/v1/team/invite`	创建团队邀请（Pro）
POST	`/api/v1/team/join`	加入团队（Pro）
GET	`/api/v1/team/invite-info`	获取邀请信息（Pro）

示例：创建备份源并触发备份

curl

curl -X POST http://127.0.0.1:9275/api/v1/sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/user/documents",
    "name": "我的文档",
    "schedule": "daily",
    "schedule_config": "{\"hour\":2,\"minute\":30}",
    "retention": "smart",
    "excludes": ["*.tmp", "node_modules"],
    "compression_type": "zstd",
    "repo_paths": ["/backup/repo1"]
  }'

# 触发备份
curl -X POST http://127.0.0.1:9275/api/v1/backup/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_id": 1}'

# 轮询进度
curl http://127.0.0.1:9275/api/v1/backup/progress \
  -H "Authorization: Bearer $TOKEN"