Zerobyte 中文使用文档

面向自托管用户的完整操作手册 · 基于官方文档（zerobyte.app/docs）与官方 API 规范（api-docs.zerobyte.app）整理

本文档覆盖：概念介绍、安装部署、快速上手、概念详解、操作指南、配置参考、CLI 参考、故障排查，以及完整的 REST API 参考。

目录

1. 简介与核心概念
2. 安装
3. 快速上手
4. 概念：卷（Volumes）
5. 概念：仓库（Repositories）
6. 概念：备份（Backups）
7. 概念：组织（Organizations）
8. 指南：3-2-1 备份策略
9. 指南：数据恢复（Restoring Data）
10. 指南：备份 Webhook
11. 指南：性能调优
12. 指南：挂载共享与权限（ACL）
13. 指南：通知（Notifications）
14. 指南：恢复密钥与仓库密码
15. 指南：仓库维护（Repository Maintenance）
16. 指南：SSO 单点登录
17. 指南：资源自动配置（Provisioning）
18. 指南：反向代理（Reverse Proxy）
19. 指南：Tailscale Sidecar
20. 指南：Rclone 集成
21. 参考：配置（Configuration）
22. 参考：CLI 命令行工具
23. 参考：故障排查（Troubleshooting）
24. REST API 参考

1. 简介与核心概念

1.1 Zerobyte 是什么

Zerobyte 是一个基于 Restic 的备份自动化平台，专为自托管用户设计。它让你能够从浏览器轻松管理卷（Volumes）与备份仓库（Repositories），并以可视化方式编排定时备份、恢复与异地复制。

核心目标：

• 简单：无需记忆复杂的 restic 命令行，一切在 Web 界面中完成。
• 安全：数据加密、密钥管理、SSO、细粒度权限与审计。
• 自动化：定时任务、Webhook 通知、自动清理（Forget/Retention）、异地镜像（Mirror）。
• 扩展：提供完整的 REST API 与 CLI，方便脚本化与二次集成。

说明：Zerobyte 由 nicotsx 开发并开源，属于开源社区（self-hosted backup）领域。本文档以官方文档与 API 规范为准。

1.2 核心概念一览

1.3 架构组成

• Web 前端：浏览器管理界面。
• 核心服务（后端）：调度任务、管理卷/仓库/备份。
• Restic：底层备份引擎，负责加密与去重存储。
• API Server：/api/v1/* 全部 REST 接口。
• 可选组件：反向代理、Tailscale Sidecar、通知 Webhook 等。

2. 安装

Zerobyte 以 Docker 容器方式运行，需在服务器上安装 Docker 与 Docker Compose。官方推荐使用 docker compose 编排。

2.1 前置条件（Prerequisites）

Zerobyte 运行在 Docker 容器中，需要：

• 安装 Docker（参见 docs.docker.com 的安装指引）。
• 安装 Docker Compose（Docker Desktop 已内置，Linux 服务器需单独安装）。
• 验证安装：

docker --version
docker compose version

2.2 两种部署模式（重要）

Zerobyte 根据是否需要在容器内挂载远程文件系统，有两种部署模式，区别在于是否需要额外的容器权限：

⚠️ 关键参数：若要挂载远程文件系统（NFS/SMB/WebDAV/SFTP）或使用 rclone 卷，compose.yaml 中必须包含以下两项，否则对应卷类型将无法使用：

cap_add:
  - SYS_ADMIN
devices:
  - /dev/fuse:/dev/fuse

这两项的作用：

• SYS_ADMIN：授予容器管理文件系统挂载（mount）的系统级能力，是挂载远程共享的前提。
• /dev/fuse：将宿主机的 FUSE（Filesystem in Userspace，用户空间文件系统）设备映射进容器，rclone / WebDAV / SFTP 等卷依赖 FUSE 实现用户空间挂载。

安全说明：SYS_ADMIN 属于高权限能力，若仅需本地目录备份，请使用精简安装（见 2.5 节），以降低安全风险。

2.3 完整安装（含远程挂载，推荐）

创建 compose.yaml，并写入以下配置：

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.43
    container_name: zerobyte
    restart: unless-stopped
    cap_add:
      - SYS_ADMIN
    ports:
      - "4096:4096"
    devices:
      - /dev/fuse:/dev/fuse
    environment:
      - TZ=Europe/Zurich      # 设置你的时区
      - BASE_URL=http://localhost:4096  # 访问 Zerobyte 的 URL
      - APP_SECRET=94bad46...c66e25d5c2b  # 用 `openssl rand -hex 32` 生成
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte

安全提示：SYS_ADMIN 能力与 /dev/fuse 设备是挂载远程文件系统（NFS、SMB、WebDAV、SFTP）所必需的。若只需本地目录备份，请参见 2.5 精简安装。

远程挂载便捷，但可能以转换后的所有权、权限与 ACL 元数据呈现，而非源系统的原始视图。若备份对元数据敏感，使用挂载卷前请阅读 第 12 章 挂载共享与权限。

步骤 1：生成 APP_SECRET

openssl rand -hex 32

将输出替换到 environment 中的 APP_SECRET：

environment:
  - TZ=America/New_York
  - BASE_URL=http://192.168.1.100:4096
  - APP_SECRET=a1b2c3d4e5f6...  # openssl 命令的输出

步骤 2：配置卷挂载

Zerobyte 的数据存储目录必须映射到宿主机本地存储：

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte

⚠️ 切勿将 /var/lib/zerobyte 指向网络共享。这会引发权限问题与严重的性能下降，务必使用本地存储。

TrueNAS 用户：TrueNAS 上 /var/lib 是临时路径，系统升级时会重置。请改为挂载专门的 ZFS 数据集：

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /mnt/tank/docker/zerobyte:/var/lib/zerobyte

步骤 3：启动并验证

docker compose up -d
docker compose ps
docker compose logs -f zerobyte

步骤 4：访问 Web 界面

浏览器访问 BASE_URL 指定的地址（默认 http://<服务器IP>:4096）。首次访问会提示创建管理员账号。

2.4 挂载本地目录

要备份宿主机上的目录，将其挂载进容器：

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte
  - /path/to/your/photos:/photos
  - /path/to/your/documents:/documents
  - /path/to/your/media:/media

• 使用只读挂载（:ro）可防止 Zerobyte 修改源数据，但将无法恢复到原始位置。
• 挂载后重启容器使配置生效：

docker compose down
docker compose up -d

挂载后的目录会以指定路径出现在容器内（如 /photos、/documents、/media）。

2.5 精简安装（仅本地目录）

若只需备份本地挂载目录、无需远程共享挂载（NFS、SMB、WebDAV、SFTP），可使用降低权限的部署：

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.43
    container_name: zerobyte
    restart: unless-stopped
    ports:
      - "4096:4096"
    environment:
      - TZ=Europe/Zurich
      - BASE_URL=http://localhost:4096
      - APP_SECRET=94bad46...c66e25d5c2b
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte
      - /path/to/your/directory:/mydata

权衡：

• ✅ 移除 SYS_ADMIN 能力，安全性更高。
• ✅ 支持挂载进容器的本地目录备份。
• ✅ 所有仓库类型仍受支持（local、S3、GCS、Azure、rclone）。
• ❌ 无法从容器内挂载远程共享（NFS、SMB、WebDAV、SFTP）。

日后需要远程挂载时，可在 compose.yaml 中加回 cap_add: SYS_ADMIN 与 devices: /dev/fuse:/dev/fuse 即可。

若追求最接近"真实复制"的效果，优先使用本地绑定挂载（bind-mounted）目录。详见 第 12 章 挂载共享与权限。

2.6 高级配置

使用 Docker Secrets 存储敏感数据

若使用资源自动配置（Provisioning），Zerobyte 可在将值加密存入数据库之前，从环境变量或 Docker secret 文件解析凭据：

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.43
    container_name: zerobyte
    restart: unless-stopped
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse:/dev/fuse
    ports:
      - "4096:4096"
    environment:
      - TZ=Europe/Zurich
      - BASE_URL=http://localhost:4096
      - APP_SECRET=94bad46...c66e25d5c2b
      - S3_ACCESS_KEY=your-access-key
      - S3_SECRET_KEY=your-secret-key
    secrets:
      - smb_password
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte

secrets:
  smb_password:
    file: ./secrets/smb_password.txt

在编写 provisioning 文件时，可通过 env:// 与 file:// 引用这些密钥（详见 第 17 章 资源自动配置）。

挂载 rclone 配置

要使用基于 rclone 的仓库（Google Drive、Dropbox、OneDrive 等），需挂载 rclone 配置文件：

宿主机配置 rclone：

curl https://rclone.org/install.sh | sudo bash
rclone config

在 compose.yaml 中挂载配置：

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte
  - ~/.config/rclone:/root/.config/rclone:ro

重启容器：

docker compose down && docker compose up -d

rclone remote 即可在 Zerobyte 中创建仓库时使用。详见 第 20 章 Rclone 集成。

2.7 反向代理 / 域名

生产环境建议使用反向代理并启用 HTTPS，参见 第 18 章 反向代理。

2.8 更新 Zerobyte

docker compose pull
docker compose up -d
docker compose logs -f zerobyte

更新前务必查看 release notes，尤其是 v0.x.x 版本可能包含破坏性变更。

3. 快速上手

3.1 首次设置（Onboarding）

在全新安装（尚无用户）时，应用会进入**引导（Onboarding）**流程：

1. 打开 BASE_URL 指定的地址（默认 http://<服务器IP>:4096）。
2. 在 Onboarding 页填写：Email、Username、Password、Confirm Password，点击 Create admin user 创建管理员账号。
3. 创建后，页面跳转至 Download Recovery Key。输入你的账号密码确认，点击 Download Recovery Key 下载恢复密钥文件。
4. 下载后进入 Volumes 页。

⚠️ 关键：请妥善保存下载的恢复密钥文件。它包含恢复备份所需的 Restic 密码。若同时丢失服务器访问与这份文件，备份将无法恢复。参见 第 14 章 恢复密钥与仓库密码。

引导完成后，之后访问使用正常 Login 登录页。

3.2 第一步：添加一个卷（Volume）

卷代表要备份的源数据。支持本地目录、NFS、SMB、WebDAV、SFTP、rclone 挂载等类型。

添加本地目录卷

1. 先在 compose.yaml 中把要备份的目录挂载进容器：

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte
  - /path/to/your/data:/data  # 新增此行

重启容器：docker compose down && docker compose up -d

2. 进入 Volumes，点击 Create Volume。
3. 配置：Name 名称、Backend 选择 Directory、Directory Path 用文件系统浏览器选择挂载目录（如 /data）。
4. 点击 Create。

注意：目录浏览器显示的是 Zerobyte 服务器/容器文件系统的路径，而非宿主机路径。上例中宿主机 /path/to/your/data 在 Zerobyte 中显示为 /data。

添加远程卷

在卷类型中选择 NFS / SMB / WebDAV / SFTP / rclone。以 NFS 为例：

• Server：NFS 服务器主机名或 IP
• Export Path：NFS 导出路径（如 /mnt/data）
• Port：NFS 端口（默认 2049）
• Version：3、4 或 4.1
• Read-only Mode：可选，备份源推荐只读

⚠️ 远程卷需要完整安装（SYS_ADMIN 能力与 /dev/fuse 设备），见 第 2 章 安装。

通过 API 创建 NFS 卷：

curl -X POST http://localhost:4096/api/v1/volumes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "name": "my-nfs-volume",
    "config": {
      "backend": "nfs",
      "server": "192.168.1.10",
      "exportPath": "/exports/data",
      "version": "4"
    }
  }'

3.3 第二步：创建备份仓库（Repository）

仓库是备份的加密存储目标。以本地仓库为例：

1. 点击侧边栏 Repositories，点击 Create repository。
2. 配置：Name、Backend 选择 Local、Compression Mode 默认 Auto (fast)、Import existing repository 新建仓库保持不勾选。
3. 本地仓库数据默认存储在 /var/lib/zerobyte/repositories/{unique-id} 下。若自定义目录，请确保该目录已从宿主机挂载进容器，否则容器重启后仓库数据会丢失。
4. 点击 Create repository。

若导入已有仓库而非新建，请在 恢复密钥与仓库密码 中先行阅读"已有恢复密钥 vs 自定义仓库密码"的选择。

通过 API 创建 S3 仓库：

curl -X POST http://localhost:4096/api/v1/repositories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "name": "s3-backup",
    "config": {
      "backend": "s3",
      "endpoint": "https://s3.example.com",
      "bucket": "my-backup-bucket",
      "accessKeyId": "AKIA...",
      "secretAccessKey": "..."
    }
  }'

3.4 第三步：创建备份任务（Backup Job）

备份任务将卷连接到仓库，并定义何时、如何备份：

1. 点击侧边栏 Backups，点击 Create a backup job。
2. 选择数据源卷，进入该卷的备份配置表单。
3. 配置基础设置：Backup name 名称、Backup repository 仓库、Backup frequency 频率。
4. 配置调度：
   • Manual only：仅手动运行
   • Hourly 每小时
   • Daily 每日
   • Weekly 每周
   • Specific days：指定每月某几天
   • Custom (Cron)：自定义 cron 表达式
   • 选择 Daily/Weekly/Specific days 时，还需设置执行时间（Execution time）；Weekly 还需选择星期几。
5. 配置保留策略（Retention Policy）：

Keep Daily: 7
Keep Weekly: 4
Keep Monthly: 6
Keep Yearly: 1

保留策略会自动清理过期备份以节省空间；Restic 的去重保证只存储唯一数据。

6. 可选配置路径（Paths）：默认备份整个卷，可设置备份路径、包含/排除规则（如 *.tmp、node_modules/**）。
7. 可选展开 Advanced 设置 Restic 高级选项：最大重试次数、重试延迟、自定义 restic 参数（每行一个）。
8. 点击 Create 保存备份任务。

3.5 第四步：运行首次备份

1. 创建后进入备份任务详情页。
2. 点击 Backup now 立即运行。
3. 监控进度，完成后状态变为 Success，并在 Snapshots 区出现新快照。
4. 首次备份会全量上传；后续因 Restic 的增量与去重会快得多。

# 通过 API 立即运行备份
curl -X POST http://localhost:4096/api/v1/backups/{shortId}/run \
  -H "Authorization: Bearer <YOUR_API_KEY>"

3.6 第五步：验证备份

在 Snapshots 区点击刚创建的快照，可查看：

• 快照时间戳
• 总大小 / 新增数据 vs 已存数据
• 处理文件数 / 耗时
• 内嵌文件浏览器浏览内容

可选的恢复测试：点击 Restore，选择 Original location 或 Custom location，用 Restore All 或选择部分文件恢复，并验证目标位置的文件。

默认恢复到原位置。注意不要覆盖当前文件，可指定备用恢复路径。

3.7 备份状态与监控

状态标记：

• Backups 列表中的状态点显示：Active、Paused、Error、Warning、Backup in progress
• 详情页上次运行状态显示：✓ Success、✗ Error、! Warning、⟳ in progress...
• 未完成过运行的备份，详情页无上次运行值

监控方式：

• Backups 列表：显示任务名、源卷/目标仓库、调度、上次与下次备份时间。
• Backup 详情：上次运行时间与状态、下次备份时间、快照历史、快照统计、恢复操作。
• 仓库健康：仓库详情页显示当前状态（healthy、error、unknown、doctor、cancelled）、上次检查时间、压缩统计与快照数。可用 Run doctor 执行维护，或用刷新按钮更新压缩统计。

3.8 常用任务

• 暂停备份：进入备份任务，关闭 Enabled 开关。
• 删除旧快照：进入备份任务，选择快照，点击 Delete Snapshot 并确认（不可逆）。
• 常见故障：
  • 权限不足：sudo chmod -R 755 /path/to/your/data
  • 备份缓慢：检查网络带宽、磁盘 I/O、启用压缩、仓库限速
  • 仓库初始化失败：检查路径可写、云凭据、网络连通
  • 找不到挂载目录：确认 compose.yaml 已挂载、已重启、路径为容器路径

4. 概念：卷（Volumes）

4.1 什么是卷

卷（Volume） 描述了一台服务器上可被挂载的存储位置，它是备份的数据来源。Zerobyte 通过挂载卷来读取需要备份的文件。

4.2 支持的卷后端

4.3 NFS 卷配置示例

{
  "name": "nfs-data",
  "config": {
    "backend": "nfs",
    "server": "192.168.1.20",
    "exportPath": "/volume1/backup",
    "port": "2049",
    "version": "4",
    "readOnly": false
  }
}

4.4 SMB 卷配置示例

{
  "name": "smb-data",
  "config": {
    "backend": "smb",
    "server": "192.168.1.30",
    "share": "backups",
    "username": "backup-user",
    "password": "secret",
    "guest": false,
    "vers": "3.0",
    "mapToContainerUidGid": true
  }
}

4.5 卷相关 API

5. 概念：仓库（Repositories）

5.1 什么是仓库

仓库（Repository） 是 Restic 的加密备份存储目标，即数据最终存放的位置。每个仓库使用独立的加密密钥（仓库密码）。

5.2 支持的仓库后端

5.3 通用仓库配置字段

所有后端共有的配置项：

5.4 S3 仓库配置示例

{
  "name": "s3-primary",
  "config": {
    "backend": "s3",
    "endpoint": "https://s3.us-east-1.amazonaws.com",
    "bucket": "my-company-backup",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

5.5 本地仓库配置示例

{
  "name": "local-disk",
  "config": {
    "backend": "local",
    "path": "/data/repo-local"
  }
}

5.6 仓库相关 API

6. 概念：备份（Backups）

6.1 什么是备份任务

备份（Backup） 将指定的卷数据通过某个仓库加密存储。每个备份任务可配置：

• 数据源（Volume）
• 目标仓库（Repository）
• 调度计划（Cron）
• 保留/清理策略（Retention/Forget）
• 文件包含/排除规则

6.2 备份创建请求体字段

{
  "name": "daily-db-backup",
  "volumeShortId": "vol_abc",
  "repositoryShortId": "repo_xyz",
  "schedule": "0 2 * * *",
  "retention": {
    "keepLast": 14,
    "keepDaily": 7,
    "keepWeekly": 4,
    "keepMonthly": 12
  },
  "paths": ["/"],
  "excludePaths": ["/tmp"]
}

6.3 保留策略（Retention / Forget）

Zerobyte 支持 Restic 的标准保留策略：

• keepLast：保留最近 N 份快照
• keepHourly / keepDaily / keepWeekly / keepMonthly / keepYearly：按时间粒度保留
• 组合使用可达成“每日备份、每周归档、每月归档”的阶梯式保留。

6.4 镜像（Mirror / 异地复制）

可将一个仓库的数据**镜像（复制）**到另一个仓库，实现异地容灾。相关 API：

6.5 备份相关 API

7. 概念：组织（Organizations）

7.1 什么是组织

组织（Organization） 是 Zerobyte 中多用户共享与权限管理的逻辑边界。通过组织可以：

• 将多个用户纳入同一工作空间
• 为成员分配角色（Owner / Admin / Member 等）
• 隔离不同团队/项目的卷、仓库与备份

7.2 组织与成员管理

组织成员可拥有不同的角色，控制其操作权限。相关 API：

7.3 多组织与管理员

管理员可在组织间管理用户归属：

8. 指南：3-2-1 备份策略

8.1 什么是 3-2-1 策略

3-2-1 备份策略 是最经典的容灾黄金法则：

• 3：保存三份数据副本
• 2：使用两种不同的存储介质
• 1：至少一份存放在异地（off-site）

8.2 用 Zerobyte 实现 3-2-1

假设你需要备份服务器上的一个卷：

1. 副本 1（本地）：使用 local 仓库，存放到本机磁盘。
2. 副本 2（异地对象存储）：使用 s3 或 r2 仓库，存放到云端对象存储。
3. 副本 3（另一介质）：使用 rest 或 sftp 仓库，存放到另一台服务器的 REST Server / SSH。

将同一卷分别创建 3 个备份任务，分别指向上述 3 个仓库，并各配一个保留策略。

// 示例：同一卷的三个备份任务
[
  { "name": "backup-local",  "volumeShortId": "vol_abc", "repositoryShortId": "repo_local",  "schedule": "0 1 * * *" },
  { "name": "backup-s3",     "volumeShortId": "vol_abc", "repositoryShortId": "repo_s3",     "schedule": "0 2 * * *" },
  { "name": "backup-rest",   "volumeShortId": "vol_abc", "repositoryShortId": "repo_rest",   "schedule": "0 3 * * *" }
]

8.3 补充建议

• 对云端仓库开启版本化/生命周期规则作为额外保险。
• 定期进行恢复演练（恢复测试），确认副本可用。
• 结合**镜像（Mirror）**功能，可将本地仓库实时复制到异地，减少第三份副本的时延。

9. 指南：数据恢复（Restoring Data）

9.1 恢复方式

Zerobyte 支持从仓库快照恢复数据到卷，或直接下载快照内容。

9.2 通过 Web 界面恢复

1. 进入「备份 / 快照」页面，选择目标快照。
2. 点击「恢复 Restore」。
3. 选择恢复到哪个卷、以及目标路径。
4. 确认执行。

9.3 通过 API 恢复

curl -X POST http://localhost:4096/api/v1/repositories/{shortId}/restore \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "snapshotId": "snap_xxx",
    "targetVolumeShortId": "vol_abc",
    "path": "/",
    "restorePath": "/restored"
  }'

9.4 下载快照内容

• 目录：以 tar 归档方式下载。
• 单文件：以原始文件流下载。

# 下载快照中某路径（目录 → tar）
curl -X GET \
  "http://localhost:4096/api/v1/repositories/{shortId}/snapshots/{snapshotId}/dump?path=/data&kind=dir" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -o restore.tar

# 下载快照中某文件（单文件 → 原始流）
curl -X GET \
  "http://localhost:4096/api/v1/repositories/{shortId}/snapshots/{snapshotId}/dump?path=/data/app.db&kind=file" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -o app.db

9.5 浏览快照文件

curl -X GET \
  "http://localhost:4096/api/v1/repositories/{shortId}/snapshots/{snapshotId}/files?path=/&limit=100" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

10. 指南：备份 Webhook

10.1 什么是备份 Webhook

Zerobyte 可在备份任务成功 / 失败等事件发生时，向外部系统发送 HTTP Webhook 请求，用于实时通知、对接告警平台（如 Slack、钉钉、企业微信、PagerDuty 等）。

10.2 配置方式

1. 在「通知 / Notifications」中新建一个通知目标（Destination）。
2. 选择类型（Webhook / 邮件等），填写目标 URL。
3. 在备份任务中关联该通知目标，选择触发事件（成功、失败、运行中）。

10.3 Webhook 事件负载

Webhook 会在备份状态变化时向配置的 URL 发送 POST 请求，负载中包含任务标识、状态、时间、仓库/卷信息与统计等字段。

11. 指南：性能调优

11.1 影响备份性能的因素

• 仓库后端网络延迟与带宽
• 卷挂载协议（NFS/SMB）
• 数据去重率
• 并发/调度时间窗口
• 加密与压缩开销

11.2 调优建议

1. 带宽限制：通过仓库的 uploadLimit / downloadLimit 控制，避免影响业务网络。
2. 调度错峰：避免多个备份任务同时触发，分散执行时间。
3. 选择合适仓库：本地磁盘最快，S3/R2 次之，Rclone/REST 受网络影响大。
4. 利用快照统计：通过 GET /api/v1/repositories/{shortId}/stats 监控压缩率与去重效果。

{
  "name": "s3-optimized",
  "config": {
    "backend": "s3",
    "endpoint": "https://s3.example.com",
    "bucket": "backup",
    "accessKeyId": "AKIA...",
    "secretAccessKey": "...",
    "uploadLimit": 10240,
    "downloadLimit": 20480
  }
}

11.3 压缩统计字段

GET /api/v1/repositories/{shortId}/stats 返回：

12. 指南：挂载共享与权限（ACL）

12.1 卷挂载与权限

备份前，Zerobyte 需要将卷挂载到备份环境。对于 NFS/SMB 卷：

• NFS：配置挂载版本（3/4/4.1）、只读标志等。
• SMB：配置凭据、SMB 版本、以及 mapToContainerUidGid 将共享文件的所有权映射到容器内用户/组。

12.2 只读挂载

为安全性，可将卷以只读方式挂载，防止备份过程意外修改源数据：

{
  "name": "nfs-ro",
  "config": {
    "backend": "nfs",
    "server": "192.168.1.20",
    "exportPath": "/data",
    "version": "4",
    "readOnly": true
  }
}

12.3 ACL 与权限注意事项

• 确保运行备份的用户具备对卷的读取权限。
• SMB 卷若权限不足，可配置 username / password 提升访问能力。
• 恢复（Restore）到目标卷时，目标路径需可写。
• 生产环境遵循最小权限原则，仅授予备份所需的最小访问范围。

13. 指南：通知（Notifications）

13.1 通知目标类型

Zerobyte 支持将备份事件推送至多种通知目标：

• Webhook：发送到自定义 HTTP 端点。
• 邮件：通过 SMTP 发送（需配置邮件服务器）。

13.2 创建通知目标

curl -X POST http://localhost:4096/api/v1/notifications/destinations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "type": "webhook",
    "name": "alert-channel",
    "url": "https://hooks.slack.com/services/xxx"
  }'

13.3 触发事件

可将通知绑定到以下事件：

• 备份成功
• 备份失败
• 备份运行中 / 完成

配置后，事件发生即自动推送，帮助你第一时间发现备份故障。

14. 指南：恢复密钥与仓库密码

14.1 仓库密码与恢复密钥

每个仓库都有一个加密仓库密码（Repository Password），用于解锁和解密备份数据。若密码丢失，将无法恢复数据。

恢复密钥（Recovery Key） 是仓库密码的加密备份副本，在密码丢失时可用于找回访问能力。

14.2 管理建议

1. 创建仓库时，若未指定 customPassword，Zerobyte 会自动生成强密码。
2. 妥善保存恢复密钥，建议离线（打印/冷存储）备份一份。
3. 定期测试恢复密钥的有效性。

14.3 相关 API

安全警告：恢复密钥与配置导出包含敏感信息，请务必妥善保管，避免泄露。

15. 指南：仓库维护（Repository Maintenance）

15.1 为什么需要维护

Restic 仓库长期运行后会产生冗余数据、索引碎片与陈旧快照，定期维护可：

• 回收未引用的数据块
• 优化快照与索引结构
• 减少存储占用、提升备份/恢复性能

15.2 维护操作

通过仓库的 exec 接口可在仓库上执行 Restic 维护命令（如 prune、check）：

# 对仓库执行 Restic 检查
curl -X POST http://localhost:4096/api/v1/repositories/{shortId}/exec \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "command": ["check"]
  }'

# 执行清理（prune）
curl -X POST http://localhost:4096/api/v1/repositories/{shortId}/exec \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "command": ["prune"]
  }'

15.3 健康检查（Doctor）

使用 doctor 接口对仓库进行自动健康检查：

curl -X POST http://localhost:4096/api/v1/repositories/{shortId}/doctor \
  -H "Authorization: Bearer <YOUR_API_KEY>"

15.4 维护建议

• 在低峰期执行 prune 与 check。
• 结合 forget（保留清理）使用，先清理过期快照再执行 prune 释放空间。
• 建立维护周期（如每月一次）。

16. 指南：SSO 单点登录

16.1 什么是 SSO

Zerobyte 支持通过 OIDC（OpenID Connect） 实现单点登录（Single Sign-On），让用户使用已有的身份提供方（如 Google、GitLab、Keycloak、Okta 等）账号登录。

16.2 SSO 相关概念

• SSO 提供商（Provider）：OIDC 身份提供方配置。
• SSO 设置（Settings）：全局 SSO 行为配置。
• SSO 邀请（Invitation）：通过 SSO 邀请用户加入。
• 自动关联（Auto-linking）：登录时根据邮箱等自动关联本地账号。

16.3 SSO 相关 API

16.4 启用 SSO 的步骤

1. 在身份提供方创建 OIDC 应用，获取 Client ID / Client Secret 与授权端点。
2. 在 Zerobyte 中配置 SSO 提供商。
3. 配置自动关联规则与邀请。
4. 用户即可通过 SSO 登录，无需单独维护本地密码。

17. 指南：资源自动配置（Provisioning）

17.1 什么是资源自动配置

Provisioning（自动配置） 允许管理员通过预设的配置模板快速批量创建卷、仓库与备份，减少重复手工操作，实现基础设施即代码（IaC）式的备份管理。

17.2 典型场景

• 新服务器上线时，自动为默认卷创建统一备份策略。
• 跨多组织批量部署一致的备份规则。
• 通过 API 脚本化地初始化整套备份环境。

17.3 配置导入 / 导出

通过系统级配置导入导出，可实现环境间的备份配置迁移：

# 导出当前完整配置
curl -X GET http://localhost:4096/api/v1/system/config-export \
  -H "Authorization: Bearer <YOUR_API_KEY>"

# 导入配置
curl -X POST http://localhost:4096/api/v1/system/config-import \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '<导出的配置 JSON>'

配置中包含仓库密码等敏感信息，导入导出时注意安全与版本管理。

18. 指南：反向代理（Reverse Proxy）

18.1 为什么需要反向代理

生产环境中，通常使用反向代理实现：

• HTTPS/TLS 加密
• 域名与路径路由
• 负载均衡
• 集中式安全策略

18.2 Nginx 反向代理示例

server {
    listen 443 ssl;
    server_name backup.example.com;

    ssl_certificate     /etc/nginx/ssl/backup.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/backup.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4096;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        # WebSocket 支持（用于界面实时更新）
        proxy_read_timeout 86400;
    }
}

18.3 Caddy 反向代理示例

backup.example.com {
    reverse_proxy localhost:4096
}

18.4 注意事项

• 务必转发真实客户端 IP 与协议（X-Forwarded-* 头），否则界面日志/审计会失真。
• 若使用 WebSocket（如进度实时刷新），需正确设置 Upgrade 头与长连接超时。
• 配置好后验证 TLS 证书与重定向是否正常。

19. 指南：Tailscale Sidecar

19.1 什么是 Tailscale

Tailscale 是基于 WireGuard 的零配置虚拟私有网络（VPN）。通过 Zerobyte 的 Tailscale Sidecar 组件，可将备份服务安全地接入私有网络，或让分布各处的节点通过加密隧道相互访问。

19.2 适用场景

• 备份节点与仓库后端位于不同私有网络。
• 需要在不开放公网端口的前提下实现安全通信。
• 通过 Tailnet 访问 NFS/SMB 卷与 REST Server。

19.3 部署思路

将 Zerobyte 容器与 Tailscale Sidecar 置于同一网络命名空间，使 Zerobyte 能经由 Tailnet 访问卷与仓库：

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:latest
    network_mode: "service:tailscale"
    depends_on:
      - tailscale

  tailscale:
    image: tailscale/tailscale:latest
    environment:
      - TS_AUTHKEY=tskey-xxx
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - ./ts-state:/var/lib/tailscale
    cap_add:
      - NET_ADMIN
      - SYS_MODULE

19.4 注意事项

• 正确配置 Tailscale 认证密钥（TS_AUTHKEY）。
• 确认 Tailnet 中节点之间网络可达。
• 结合防火墙规则，仅开放必要的端口与节点。

20. 指南：Rclone 集成

使用 rclone 连接 40+ 云存储提供商，用作仓库与卷。官方页面：zerobyte.app/docs/guides/rclone

20.1 什么是 Rclone 集成

Rclone 是一个能连接 40+ 云存储提供商（Google Drive、Dropbox、OneDrive、Box、pCloud、Mega 等）的命令行工具。Zerobyte 在两个场景中利用 rclone：

• 仓库（Repositories）：将加密备份存储到任何 rclone 支持的云存储提供商。
• 卷（Volumes）：将云存储挂载为数据源，从而备份云端数据。

20.2 设置 Rclone

在 Zerobyte 使用 rclone 前，需在宿主机上安装并配置 rclone。

安装 rclone

curl https://rclone.org/install.sh | sudo bash

或访问 rclone.org/install 获取各平台安装包。

配置远程（remote）

运行交互式配置向导：

rclone config

按提示添加远程。每个提供商有各自的设置流程，rclone 会引导完成认证、API 密钥或 OAuth。

验证远程

列出所有已配置的远程：

rclone listremotes

测试连接：

rclone lsd myremote:

将 myremote 替换为你配置时选择的名称。

20.3 将 rclone 配置挂载进容器

Zerobyte 需要读取 rclone 配置才能发现并使用你的远程。在 compose.yaml 中以只读卷方式挂载：

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte
  - ~/.config/rclone:/root/.config/rclone:ro

然后重启容器使变更生效：

docker compose down && docker compose up -d

非 root 容器环境（如 TrueNAS）：配置必须挂载到正确的用户主目录。相应地设置 RCLONE_CONFIG_DIR 环境变量：

environment:
  - RCLONE_CONFIG_DIR=/home/appuser/.config/rclone
volumes:
  - ~/.config/rclone:/home/appuser/.config/rclone:ro

20.4 用 Rclone 作为仓库（Repositories）

Rclone 仓库可把加密备份存储到任何 rclone 支持的提供商。

1. 侧边栏进入 Repositories，点击 Create Repository。
2. 在仓库类型下拉框中选择 rclone。
3. 从下拉列表中选择你的远程（Zerobyte 会读取挂载的 rclone 配置中所有已配置的远程）。
4. 输入远程内备份的存储路径（如 backups/zerobyte）。
5. 点击 Create and Initialize，Zerobyte 会在远程上初始化一个新的加密 Restic 仓库。

// 通过 API 创建 rclone 仓库
{
  "name": "rclone-drive",
  "config": {
    "backend": "rclone",
    "remote": "gdrive:",
    "path": "backups/zerobyte"
  }
}

⚠️ 注意：Google Drive、Dropbox 等消费级云服务有 API 限速，不适用于重 I/O 负载。它们适合个人或轻量备份；生产或关键数据请使用真正的对象存储，如 S3、Backblaze B2 或 Cloudflare R2。

20.5 用 Rclone 作为卷（Volumes）

Rclone 卷将云存储作为文件系统挂载进容器，从而备份云端数据。这需要提升容器能力。

确保 FUSE 支持

compose.yaml 必须包含 SYS_ADMIN 与 /dev/fuse：

cap_add:
  - SYS_ADMIN
devices:
  - /dev/fuse:/dev/fuse

⚠️ 缺少这两项，rclone 卷将无法创建。

创建 rclone 卷

1. 侧边栏进入 Volumes，点击 Create Volume。
2. 在卷类型下拉框中选择 rclone。
3. 选择远程与路径：选择远程并指定要挂载的远程内路径（如 / 表示整个远程，或 /photos 表示子目录）。
4. 点击 Create，Zerobyte 将把远程挂载为 FUSE 文件系统，供备份任务使用。

⚠️ Rclone 卷仅支持 Linux。macOS 与 Windows 上的 Docker 不支持容器内 FUSE 挂载。若使用 Docker Desktop（macOS/Windows），rclone 卷将无法工作。

20.6 SFTP 远程与 SSH 密钥

若 rclone 远程使用 key_file 认证的 SFTP，则 rclone 配置中 key_file 指向的是宿主机文件路径，容器内无法访问。有三种解决方案。

方案一（推荐）：挂载 SSH 密钥

将 SSH 密钥挂载进容器，使 rclone 能在预期路径找到：

volumes:
  - ~/.ssh:/root/.ssh:ro

并确保 rclone 配置中的 key_file 路径与容器内路径一致（如 /root/.ssh/id_rsa）。

方案二：将密钥嵌入配置

方案三：使用 SSH agent

20.7 刷新 OAuth 令牌

使用 OAuth 的 rclone 远程（Google Drive、Dropbox、OneDrive、Box 等）将认证令牌存储在 rclone 配置文件中。这些令牌会定期过期，需要刷新。

1. 在宿主机重新认证：

rclone config reconnect myremote:

按提示重新授权远程。

2. 重启容器：

docker compose restart

若以只读卷（:ro）挂载 rclone 配置，宿主机上更新后的令牌在重启后立即可见，无需手动复制文件。

20.8 故障排查

没有可用的远程

创建仓库或卷时，远程下拉框为空：

• 确认 rclone 配置已正确挂载。检查宿主机 ~/.config/rclone/rclone.conf 是否存在。
• 确认 compose.yaml 中的挂载路径与容器内预期位置一致（默认 /root/.config/rclone，或 RCLONE_CONFIG_DIR 设定的路径）。
• 更新卷挂载后重启容器。

创建文件系统失败

通常意味着 rclone 无法与远程认证：

• 对于 OAuth 远程（Google Drive、Dropbox、OneDrive），令牌可能已过期。在宿主机执行 rclone config reconnect myremote: 重新认证并重启容器。
• 对于基于密钥的远程（S3、SFTP），确认 rclone 配置中的凭据正确。
• 在宿主机直接测试远程 rclone lsd myremote:，以判断是 rclone 本身还是 Zerobyte 的问题。

Rclone 卷的 FUSE 挂载错误

创建 rclone 卷时出现与 FUSE 相关的错误：

• 确认 compose.yaml 包含 cap_add: [SYS_ADMIN] 与 devices: [/dev/fuse:/dev/fuse]。
• 确认你在 Linux 主机上运行。macOS/Windows 的 Docker 不支持 FUSE 挂载。
• 检查宿主机 /dev/fuse 是否存在：ls -la /dev/fuse。

20.9 注意事项汇总

• 确保运行环境已正确安装并配置 Rclone。
• 注意各云存储的速率与配额限制。
• 保持 Rclone 远程凭据的安全。
• 消费级云服务适合轻量备份；生产数据请用对象存储。
• rclone 卷仅 Linux 支持。

21. 参考：配置（Configuration）

Zerobyte 通过环境变量与 Docker Compose 设置进行配置。本页覆盖全部可用选项。官方页面：zerobyte.app/docs/configuration

21.1 环境变量（Environment Variables）

必填（Required）

⚠️ 切勿分享或提交 APP_SECRET。若丢失该密钥，数据库中加密存储的凭据（卷与仓库的凭据）将无法恢复。

APP_SECRET_FILE 读取文件内容时会去除首尾空白与换行，并同样要求 32–256 字符。

推荐（Recommended）

可选（Optional）

21.2 使用 APP_SECRET_FILE

若不想把 app secret 直接写进 environment:，可将其挂载为文件，并让 APP_SECRET_FILE 指向该路径：

services:
  zerobyte:
    environment:
      - BASE_URL=https://zerobyte.example.com
      - APP_SECRET_FILE=/run/secrets/app_secret
    secrets:
      - app_secret

secrets:
  app_secret:
    file: ./secrets/app_secret.txt

生成密钥文件：

mkdir -p ./secrets
openssl rand -hex 32 > ./secrets/app_secret.txt

⚠️ 不要同时设置 APP_SECRET。若两者都配置，Zerobyte 将无法启动。

21.3 Docker Compose 设置

卷挂载（Volume Mounts）

Zerobyte 的必备卷挂载：

volumes:
  # 同步容器与宿主机时间（推荐）
  - /etc/localtime:/etc/localtime:ro

  # Zerobyte 数据目录（数据库、加密密钥、本地仓库）
  - /var/lib/zerobyte:/var/lib/zerobyte

⚠️ 不要将 /var/lib/zerobyte 指向网络共享。这会导致权限问题与严重的性能下降。务必使用本地存储。

TrueNAS 用户：/var/lib 为临时路径，系统升级时会重置。请改为挂载专门的 ZFS 数据集：

volumes:
  - /mnt/tank/docker/zerobyte:/var/lib/zerobyte

附加卷挂载（Additional Volume Mounts）

容器能力（Container Capabilities）

Zerobyte 支持两种部署模式：

完整安装（带远程挂载） —— 用于从 Zerobyte 直接挂载 NFS、SMB、WebDAV、SFTP 卷：

cap_add:
  - SYS_ADMIN
devices:
  - /dev/fuse:/dev/fuse

精简安装（仅本地目录） —— 仅需本地目录备份时，无需特殊能力：

# 无需 cap_add 或 devices
ports:
  - "4096:4096"

⚠️ 再次强调：SYS_ADMIN 能力与 /dev/fuse 设备是挂载远程文件系统所必需的。缺失它们，将无法使用 NFS/SMB/WebDAV/SFTP/rclone 卷。详见 第 2 章 安装。

端口配置

默认监听端口 4096：

ports:
  - "4096:4096"

仅绑定 localhost（配合反向代理时推荐）：

ports:
  - "127.0.0.1:4096:4096"

21.4 Cookie 安全性

BASE_URL 决定认证 cookie 的行为：

若 BASE_URL 以 https:// 开头，浏览器将仅通过 HTTPS 连接发送认证 cookie。纯 HTTP 访问可能显示登录页，但认证会失败。

TRUSTED_ORIGINS 仅为 CORS 允许额外来源，不会禁用 Secure cookie，也不会让 BASE_URL 为 HTTPS 时的 HTTP 访问生效。

21.5 密钥引用（Secret References）

在资源自动配置（Provisioning）卷或仓库时，敏感字段支持密钥引用：

这让你把凭据保存在部署配置中，而无需直接写进 provisioning 文件。

界面中的标准卷/仓库表单会存储你输入的值并加密落盘；env:// 与 file:// 引用仅在 provisioning 期间解析。

Docker Secrets 示例

services:
  zerobyte:
    environment:
      - S3_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
    secrets:
      - s3_secret_key
    volumes:
      - /var/lib/zerobyte:/var/lib/zerobyte

secrets:
  s3_secret_key:
    file: ./secrets/s3_secret_key.txt

在 provisioning 文件中引用：

• Access Key：env://S3_ACCESS_KEY
• Secret Key：file://s3_secret_key

21.6 更新 Zerobyte

docker compose pull
docker compose up -d
docker compose logs -f zerobyte

更新前务必查看 release notes，尤其是 v0.x.x 版本可能包含破坏性变更。

21.7 系统级 API

21.8 任务管理

22. 参考：CLI 命令行工具

说明：Zerobyte 以 Web 界面 + REST API 为主要管理方式；底层备份引擎为 Restic。以下列出与运维相关的命令行使用方式。

22.1 底层 Restic 命令

由于仓库基于 Restic，可直接使用 restic CLI 对仓库进行高级操作（需仓库密码）：

# 初始化/查看仓库
restic -r s3:s3.example.com/bucket snapshots

# 列出快照
restic -r s3:s3.example.com/bucket snapshots --latest 3

# 校验仓库
restic -r s3:s3.example.com/bucket check

# 清理（prune）
restic -r s3:s3.example.com/bucket forget --prune --keep-daily 7 --keep-weekly 4

22.2 Rclone 集成命令

使用 Rclone 后端时，可用 rclone 命令行管理远程存储：

# 查看远程
rclone lsd gdrive:

# 查看仓库目录
rclone ls gdrive:/backup/zerobyte

22.3 推荐组合

在自动化场景中，优先使用 REST API（见 第 24 章）与调度器管理备份；仅在深度排查或特殊维护时使用 Restic/Rclone CLI。

23. 参考：故障排查（Troubleshooting）

23.1 常见问题

备份失败

• 原因排查：查看备份任务的事件日志（成功/失败状态）。
• 卷挂载失败：检查 NFS/SMB 服务器可达性、权限、挂载版本。
• 仓库连接失败：检查凭据、端点、网络、TLS 证书。

恢复失败

• 确认快照存在且未过期清理。
• 确认目标卷可写、路径正确。
• 检查仓库密码/恢复密钥是否有效。

界面无法打开

• 检查容器是否运行：docker ps
• 检查端口映射与防火墙。
• 若配置反向代理，检查 X-Forwarded-* 头与 TLS 配置。

23.2 健康检查工具

• 卷健康检查：POST /api/v1/volumes/{shortId}/health-check
• 仓库健康检查（Doctor）：POST /api/v1/repositories/{shortId}/doctor

curl -X POST http://localhost:4096/api/v1/volumes/{shortId}/health-check \
  -H "Authorization: Bearer <YOUR_API_KEY>"

curl -X POST http://localhost:4096/api/v1/repositories/{shortId}/doctor \
  -H "Authorization: Bearer <YOUR_API_KEY>"

23.3 审计与日志

• 通过界面查看备份/恢复的任务历史与事件。
• 通过 GET /api/v1/tasks 查询后台任务状态。
• 容器日志：docker logs -f zerobyte

23.4 升级与备份配置

• 升级前导出配置（config-export）并备份数据目录。
• 妥善保存恢复密钥与仓库密码。
• 升级后验证卷挂载与仓库连接。

24. REST API 参考

基于官方 OpenAPI 3.1 规范（api-docs.zerobyte.app）。Base URL 为 http://<主机>:4096。所有业务接口均需身份认证（Authorization 头携带 API Key / 会话令牌）。

24.1 认证方式

Zerobyte 使用 API Key 进行接口认证。通过 GET /api/v1/auth/api-keys 与 POST /api/v1/auth/api-keys 管理当前用户的 API Key。

认证头：

Authorization: Bearer <YOUR_API_KEY>

管理 API Key：

24.2 认证状态

24.3 卷 API（Volumes）

创建卷请求体

{
  "name": "nfs-volume",
  "config": {
    "backend": "nfs",
    "server": "192.168.1.10",
    "exportPath": "/data",
    "version": "4",
    "readOnly": false
  }
}

列出卷响应（示例字段）

[
  {
    "id": 1,
    "shortId": "vol_abc",
    "name": "nfs-volume",
    "config": {
      "backend": "nfs",
      "server": "192.168.1.10",
      "exportPath": "/data",
      "version": "4",
      "readOnly": false
    }
  }
]

24.4 仓库 API（Repositories）

仓库后端配置变体

S3 / R2：

{
  "name": "s3-repo",
  "config": {
    "backend": "s3",
    "endpoint": "https://s3.example.com",
    "bucket": "backup",
    "accessKeyId": "AKIA...",
    "secretAccessKey": "...",
    "isExistingRepository": false,
    "insecureTls": false,
    "uploadLimit": 0,
    "downloadLimit": 0
  }
}

Local：

{
  "name": "local-repo",
  "config": {
    "backend": "local",
    "path": "/data/repo"
  }
}

GCS：

{
  "name": "gcs-repo",
  "config": {
    "backend": "gcs",
    "bucket": "my-backup-bucket",
    "projectId": "my-project",
    "credentialsJson": "{...}"
  }
}

Azure：

{
  "name": "azure-repo",
  "config": {
    "backend": "azure",
    "container": "backup",
    "accountName": "mystorage",
    "accountKey": "..."
  }
}

Rclone：

{
  "name": "rclone-repo",
  "config": {
    "backend": "rclone",
    "remote": "gdrive:",
    "path": "/backup"
  }
}

REST：

{
  "name": "rest-repo",
  "config": {
    "backend": "rest",
    "url": "https://rest.example.com:8000",
    "username": "user",
    "password": "pass",
    "path": "/"
  }
}

SFTP：

{
  "name": "sftp-repo",
  "config": {
    "backend": "sftp",
    "host": "backup.example.com",
    "port": 22,
    "user": "backup",
    "path": "/data/repo",
    "privateKey": "-----BEGIN ...",
    "skipHostKeyCheck": false
  }
}

快照字段

GET /api/v1/repositories/{shortId}/snapshots 返回的快照对象包含：

仓库统计字段

GET /api/v1/repositories/{shortId}/stats 返回：

{
  "total_size": 0,
  "total_uncompressed_size": 0,
  "compression_ratio": 0,
  "compression_progress": 0,
  "compression_space_saving": 0,
  "snapshots_count": 0
}

快照下载

GET /api/v1/repositories/{shortId}/snapshots/{snapshotId}/dump

查询参数：

快照文件列表

GET /api/v1/repositories/{shortId}/snapshots/{snapshotId}/files

查询参数：path、offset、limit

24.5 备份 API（Backups）

24.6 组织与成员 API

24.7 SSO API

24.8 通知 API

24.9 系统 API

24.10 任务 API

24.11 认证 API 汇总

24.12 完整接口清单（68 个端点）

按资源分组汇总：

端点数为官方 OpenAPI 规范所列。由于上游 API 持续演进，以官方 api-docs.zerobyte.app 为准。

附录 A：快速参考——常用 curl 示例

# 列出所有卷
curl -H "Authorization: Bearer <KEY>" http://localhost:4096/api/v1/volumes

# 创建 NFS 卷
curl -X POST -H "Authorization: Bearer <KEY>" -H "Content-Type: application/json" \
  -d '{"name":"v1","config":{"backend":"nfs","server":"192.168.1.10","exportPath":"/data","version":"4"}}' \
  http://localhost:4096/api/v1/volumes

# 创建 S3 仓库
curl -X POST -H "Authorization: Bearer <KEY>" -H "Content-Type: application/json" \
  -d '{"name":"r1","config":{"backend":"s3","endpoint":"https://s3.example.com","bucket":"b","accessKeyId":"AK","secretAccessKey":"SK"}}' \
  http://localhost:4096/api/v1/repositories

# 立即运行备份
curl -X POST -H "Authorization: Bearer <KEY>" http://localhost:4096/api/v1/backups/{shortId}/run

# 下载快照目录为 tar
curl -X GET -H "Authorization: Bearer <KEY>" \
  "http://localhost:4096/api/v1/repositories/{shortId}/snapshots/{snapId}/dump?path=/&kind=dir" -o backup.tar

附录 B：术语表

文档信息：本中文文档根据 Zerobyte 官方文档 与 官方 API 规范 整理编写。接口与配置可能随版本演进，请以官方最新文档为准。