配置详解

了解所有可配置参数，按需调整备份行为

配置方式

Ginkgo Backup 提供三种配置方式：图形界面（推荐大多数用户）、CLI（ginkgo init 命令）、HTTP API（自动化场景）。所有配置都存储在 SQLite 数据库中，可随时修改。

备份源配置

创建或更新备份源时可配置的字段。通过 API 创建时使用 JSON 请求体。

字段	类型	默认值	说明
`path`	string	—	备份源路径（必填）
`name`	string	目录名	显示名称
`group`	string	—	分组标签，便于组织多个源
`enabled`	bool	true	是否启用（暂停时为 false）
`schedule`	string	manual	调度策略：manual / hourly / daily / weekly / monthly
`schedule_config`	string (JSON)	—	调度详细配置，如 {"hour":2,"minute":30}
`retention`	string	smart	保留策略：keep_all / smart / custom
`retention_custom`	string	—	自定义保留规则（retention=custom 时生效）
`excludes`	[]string	[]	排除模式列表（glob 语法，逗号分隔）
`enable_ai`	bool	false	是否启用 AI 智能备注
`watch_mode`	string	auto	监控模式：auto（自动选择）/ poll（轮询）/ disabled
`compression_type`	string	zstd	压缩算法（固定 zstd，不可更改）
`compression_level`	int	1	压缩级别（固定 1，不可更改）
`chunk_concurrency`	int	0（自动）	分块并发数，0 表示按 CPU 自动选择
`repo_paths`	[]string	—	仓库路径列表（支持多目标，实现 3-2-1）

调度策略详解

schedule_config 字段根据 schedule 类型不同，使用不同的 JSON 结构：

schedule	schedule_config	说明
`manual`	`—`	不自动备份，仅手动触发
`hourly`	`{"interval_minutes": 60}`	按固定间隔执行（默认 60 分钟）
`daily`	`{"hour": 2, "minute": 30}`	每天指定时间执行
`weekly`	`{"day": "monday", "hour": 3}`	每周指定星期和时间执行
`monthly`	`{"date": 1, "hour": 2}`	每月指定日期和时间执行

保留策略详解

Ginkgo 使用 GFS（祖父-父亲-儿子）保留策略，自动管理历史版本数量：

retention	说明
`keep_all`	保留所有快照，永不删除（占用空间最大）
`smart`	智能 GFS（推荐）：24 小时 + 30 天 + 12 周 + 12 月 + 3 年
`custom`	自定义 GFS 桶大小，通过 retention_custom 配置

排除模式

excludes 字段使用 glob 语法，逗号分隔。也可在源目录创建 .ginkgo-backupignore 文件（语法同 .gitignore）。

pattern	matches
`/Cache/`	任意深度的 Cache 目录
`*/.tmp`	所有 .tmp 临时文件
`/logs/`	任意深度的 logs 目录
`node_modules/**`	源根目录下的 node_modules
`!/important/`	反向模式：重新包含 important 目录

压缩

Ginkgo 固定使用 zstd（级别 1）压缩所有备份数据，不可更改：

algorithm	level	说明
`zstd`	1	固定算法与级别，所有备份源统一应用

文件监控模式

watch_mode 控制如何检测文件变化以触发实时备份：

watch_mode	说明
`auto`	自动选择：优先用系统原生文件事件，不可用时回退到轮询
`poll`	强制轮询模式：定期扫描目录，兼容性最好但耗电稍高
`disabled`	禁用实时监控，仅按 schedule 定时备份

仓库配置

创建仓库时可配置的字段：

字段	类型	默认值	说明
`path`	string	—	仓库路径（本地路径或 cloud://backendID/path）
`display_name`	string	—	显示名称
`type`	string	local	类型：local / s3 / webdav
`encrypted`	bool	false	是否启用加密
`password`	string	—	加密密码（encrypted=true 时必填）
`compression`	string	zstd	压缩算法

全局设置

通过 /api/v1/settings 端点读写应用级设置：

Shell

# 查看当前设置
curl http://127.0.0.1:9275/api/v1/settings \
  -H "Authorization: Bearer $TOKEN"

# 更新设置
curl -X PUT http://127.0.0.1:9275/api/v1/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language": "zh", "theme": "dark"}'

快照置顶

置顶的快照不会被保留策略和 GC 删除，适合保护关键时间点：

curl

# 置顶快照
curl -X POST http://127.0.0.1:9275/api/v1/pins/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": 123}'

# 取消置顶
curl -X POST http://127.0.0.1:9275/api/v1/pins/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": 123}'