Documentation
¶
Overview ¶
Package statebackup 是控制面状态热备（T2.22，备份基线与信任闭环）： SQLite 一致性快照（VACUUM INTO）→ 回读校验（integrity_check + 关键表 行数抽查 + schema 版本）→ sha256 落 manifest → state_backups 台账（与 审计同事务）。触发三类：每次部署成功后（引擎成功路径挂钩，异步不阻塞 部署主链）+ 每日定时（本包守护循环）+ 手动（daemon RPC → CLI）。
诚实契约（architecture §4.2 横切硬指标 + state-model §2.7）：
- verify 任何一步失败 → 台账 verify_status=failed + 审计 backup.failed (result=error) + 系统状态 backup 组件不健康——「绿色成功但实际没备份」 的路径结构性不存在（负面测试钉死）；
- 备份产物布局 <dir>/<ULID>/fleetly.db + manifest.json；主密钥 （fleetly.key）绝不进备份目录——manifest 只记密钥文件的 sha256 指纹 （恢复时人工核对，docs/runbooks/backup-restore.md），构造期显式拒绝 密钥落在备份目录内的配置；
- 保留策略：keep 份上限，超限删最旧（台账删行 + 审计 backup.pruned + 目录清除——台账只描述真实存在的备份，不保留幽灵行）。
Index ¶
- Constants
- type Config
- type Manager
- func (m *Manager) CheckHealth() error
- func (m *Manager) Dir() string
- func (m *Manager) Keep() int
- func (m *Manager) RunDaily(ctx context.Context) (state.StateBackup, error)
- func (m *Manager) RunPostDeploy(rec state.DeployRecord)
- func (m *Manager) RunPreUpgrade(ctx context.Context) (state.StateBackup, error)
- func (m *Manager) Start(ctx context.Context) error
- func (m *Manager) Stop(_ context.Context) error
- func (m *Manager) Trigger(ctx context.Context, kind string) (state.StateBackup, error)
- type Manifest
Constants ¶
const ( DefaultInterval = 24 * time.Hour DefaultTriggerTimeout = 5 * time.Minute )
DefaultInterval / DefaultTriggerTimeout 是每日备份周期与单次备份预算 （快照+校验+落账；VACUUM INTO 对 v0.1 规模的库是亚秒级，预算是防御上限）。
const DefaultKeep = 7
DefaultKeep 是保留份数缺省值（config backup.keep 非正值回落——保留策略 是契约默认，不允许被误配成 0 而静默关闭）。
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Dir 是备份根目录（backup.dir；空 = 装配点回落 <state 库同目录>/backups）。
Dir string
// Keep 是保留份数上限（backup.keep；非正值回落 DefaultKeep）。
Keep int
// Interval 是每日备份周期（测试注入点；零值回落 DefaultInterval）。
Interval time.Duration
// TriggerTimeout 是单次备份的预算上限（零值回落 DefaultTriggerTimeout）。
TriggerTimeout time.Duration
}
Config 是备份核心配置（config 键 backup.*；缺省值经 Normalize 回落—— 单一事实源在本包；dir 缺省依赖 state 库路径，由装配点给出后传入）。
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager 是状态备份管理器：触发入口（daily/pre_upgrade/post_deploy/manual） + 每日守护循环 + 健康上报（system status backup 组件）+ 保留期清理。 零框架依赖——lynx.Service 装配壳在 cmd/fleetlyd。
func NewManager ¶
func NewManager(cfg Config, dir, keyPath, version string, st *state.Store, log *slog.Logger) (*Manager, error)
NewManager 构造备份管理器。dir 由装配点回落缺省（state 库同目录 backups）； keyPath 只用于指纹与分离性守卫。密钥文件与备份目录重叠是配置错误： 构造期即拒绝（fail-fast——「密钥绝不进备份目录」是硬约束，不静默降级）。
func (*Manager) CheckHealth ¶
CheckHealth 是 system status backup 组件的检查器（红色告警的第三面）： 无任何备份记录 / 最近一次 verify 失败 → 不健康（错误原文可行动）。
func (*Manager) RunPostDeploy ¶
func (m *Manager) RunPostDeploy(rec state.DeployRecord)
RunPostDeploy 是引擎成功路径的挂钩形态（engine.PostDeployHook 签名）： 异步执行（部署主链不等备份），带独立预算；失败只落台账/审计 + 日志， 永不 panic 打穿引擎 tick。
func (*Manager) RunPreUpgrade ¶
RunPreUpgrade 执行升级前热备快照（upgrade.sh 编排步骤 ②；失败必须阻断 升级——调用方拿 error 决定，脚本侧 verify_status 也二次核对）。
func (*Manager) Start ¶
Start 非阻塞启动每日备份循环（启动即备份一拍——新装平台在首启即有 verified 备份，系统状态 backup 组件不长期红着；此后每 Interval 一拍）。
type Manifest ¶
type Manifest struct {
ID string `json:"id"`
Kind string `json:"kind"`
CreatedAt string `json:"created_at"`
PlatformVersion string `json:"platform_version"`
SchemaVersion int64 `json:"schema_version"`
Database string `json:"database"`
SizeBytes int64 `json:"size_bytes"`
SHA256 string `json:"sha256"`
VerifyStatus string `json:"verify_status"`
KeyFingerprint string `json:"key_fingerprint"`
Tables map[string]int64 `json:"tables,omitempty"`
Error string `json:"error,omitempty"`
}
Manifest 是备份目录内 manifest.json 的形态（备份集的元数据事实；恢复 流程第一步即核对：sha256 与快照一致 + key_fingerprint 与现役主密钥文件 的 sha256sum 一致，不一致拒绝半恢复——state-model §2.7 恢复顺序②）。 主密钥本体绝不入备份目录，manifest 只携带指纹。
Source Files