CLI 命令参考
18 个命令覆盖从初始化到灾难恢复的完整流程，所有命令均可脚本化
快速理解
Ginkgo CLI 通过本地 HTTP API（默认 127.0.0.1:9275）与后台守护进程通信。所有命令都可独立运行，也可串联进自动化脚本。Token 在首次启动时自动生成并保存到 ~/.ginkgo-backup/config.json。
全局参数
所有命令共享以下参数，可通过命令行或环境变量设置：
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--token | GINKGO_TOKEN | — | API 认证 Token（首次启动自动生成） |
--port | GINKGO_PORT | 9275 | API 服务端口 |
--host | — | 127.0.0.1 | API 服务地址 |
--tls | GINKGO_TLS=1 | 自动 | 使用 HTTPS 连接（未设置时自动检测；TLS 启用的服务器必填） |
首次配置
Shell
# 保存 Token 到配置文件（之后无需每次指定）
ginkgo config save --token <token> --port 9275
# 查看当前配置
ginkgo config show命令分组
初始化与状态
ginkgo init [path]初始化备份源flags: --schedule (manual/hourly/daily/weekly，默认 daily)
ginkgo sources列出所有备份源ginkgo status系统状态概览（运行中的任务、磁盘、健康）ginkgo version查看版本信息ginkgo config save保存 Token/端口到配置文件flags: --token, --port
ginkgo config show查看当前配置备份与进度
ginkgo backup --source <id>触发备份（异步，fire-and-forget）flags: --source (0 = 全部), --message, --wait
ginkgo checkpoint --source <id>触发备份并阻塞等待完成（适合脚本）flags: --source (0 = 全部), --message, --timeout (默认 600s)
ginkgo progress查看当前备份进度（文件数、字节数、阶段）暂存区（即时保护）
ginkgo staging push --source <id>推送变更文件到 COW 暂存区（fire-and-forget）flags: --source (必填), --paths, --files, --message
ginkgo staging push-ai --source <id>推送文件并标记为 AI 生成（强制 note_source=ai）flags: --source (必填), --paths, --files, --message
快照与历史
ginkgo snapshots --source <id>列出快照flags: --source, --limit (默认 20)
ginkgo history <file_path>查看文件版本历史flags: --source (必填)；file_path 为位置参数
ginkgo diff --source <id>对比最近两个快照的差异flags: --source (必填)
恢复与导出
ginkgo restore <file_path>从快照恢复文件flags: --source, --snapshot (均必填), --dest；file_path 为位置参数
ginkgo export --source <id>导出快照为 zip/tar 归档flags: --source (必填), --snapshot, --output (必填), --format (zip/tar，默认 zip)
校验与挂载
ginkgo verify --source <id>验证备份完整性（默认快速校验）flags: --source (必填), --deep, --repair, --repo
ginkgo mount --source <id>挂载快照为本地磁盘flags: --source (必填), --mount-point (必填), --snapshot (默认最新)
保留策略
ginkgo retention --source <id>对源应用 GFS 保留策略flags: --source (必填), --policy (keep_all/smart/custom，默认 smart), --custom, --dry-run
AI 备注
ginkgo generate-note --source <id>基于最新快照数据生成 AI 智能备注flags: --source (必填)
典型工作流
首次设置 + 每日备份
Shell
# 1. 初始化备份源（每日备份）
ginkgo init /home/user/documents --schedule daily
# 2. 触发首次备份并等待完成
ginkgo backup --source 1 --wait
# 3. 查看快照
ginkgo snapshots --source 1恢复误删文件
Shell
# 1. 查看文件版本历史
ginkgo history /docs/report.pdf --source 1
# 2. 恢复到指定快照
ginkgo restore /docs/report.pdf \
--source 1 \
--snapshot 1715001600000 \
--dest /tmp/restoreAI 编程安全循环
Shell
# 1. 重构前创建检查点（阻塞直到完成）
ginkgo checkpoint --source 1 --message "pre refactor: auth 模块"
# 2. AI 执行重构（外部操作）
# 3. 即时保护变更文件
ginkgo staging push --source 1 --paths "src/auth.go,src/session.go" --message "feat: 重写 auth"
# 4. 对比上一个快照
ginkgo diff --source 1服务器/NAS Headless 部署
Shell
# 1. 构建无界面服务
go build -o ginkgo-server ./cmd/ginkgo-server
# 2. 后台启动（headless 模式自动开启 TLS）
./ginkgo-server --tls-auto &
# 3. 保存日志中的 Token
ginkgo config save --token <token-from-log> --port 9275
# 4. 初始化多个备份源
ginkgo init /data/projects --schedule daily
ginkgo init /data/photos --schedule weekly