backup

package
v1.0.0-rc.58 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package backup 做 pt-tools 数据的备份与恢复(媒体中心方案 M0)。

一份备份是一个 tar.gz:manifest.json、torrents.db(VACUUM INTO 取的一致快照,服务运行中也能做)、 secret.key(选了带上密钥时)。恢复分两段:网页或命令行先校验,通过后放进 <数据目录>/restore-pending/; 下次启动、打开数据库以前换上,换完用当前生效的密钥复验,任何一步失败都把原来的文件放回去、按原来的数据启动。

Index

Constants

View Source
const (
	DefaultTime    = "04:30"
	DefaultKeep    = 7
	MinKeep        = 1
	MaxKeep        = 60
	PreUpgradeKeep = 3
	DefaultDirName = "backups"
	MaxUploadSize  = 2 << 30
	SecretFromFile = "file"
	SecretFromEnv  = "env"

	// UnknownAppVersion 是 manifest 里不知道数据库是哪个版本写的:从不记版本号的旧版本升上来时,升级前备份记它。
	UnknownAppVersion = "unknown"
)

默认值与范围(设置页与定时任务共用)。

View Source
const FormatVersion = 1

FormatVersion 是备份文件格式的版本,manifest 里记着;比它新的备份不认。

View Source
const PendingDir = "restore-pending"

PendingDir 是待恢复的文件放在数据目录下的哪个子目录。

Variables

View Source
var ErrInvalid = errors.New("备份文件不能用")

ErrInvalid 是备份文件本身有问题(不是 pt-tools 的备份、内容被改过、数据库损坏、版本太新……)。

View Source
var ErrKeyMismatch = errors.New("密钥对不上")

ErrKeyMismatch 是按密钥规则不能恢复:恢复以后生效的密钥解不开备份里加密保存的凭证(Cookie、通知凭证、API Key 等)。

View Source
var ErrNotFound = errors.New("备份不存在")

ErrNotFound 是备份目录里没有这份备份(或者文件名不是这里起的)。

Functions

func CancelPending

func CancelPending(dataDir string) error

CancelPending 取消还没生效的恢复(删掉 restore-pending)。

func Delete

func Delete(dir, name string) error

Delete 删掉备份目录里的一份备份。

func IsBackupName

func IsBackupName(name string) bool

IsBackupName 报告 name 是不是这里起的备份文件名(只有文件名,不含目录)。

func Prune

func Prune(dir string, keepScheduled int) ([]string, error)

Prune 按保留规则删旧备份:定时备份留最新 keepScheduled 份,升级前备份留最新 PreUpgradeKeep 份,手动与命令行的不删。 读不出 manifest 的文件不动。返回删掉的文件名。

func Resolve

func Resolve(dir, name string) (string, error)

Resolve 把界面传来的文件名换成备份目录里的路径:只认这里起的名字,不认路径。

Types

type ActiveKey

type ActiveKey struct {
	// FromEnv 为真表示密钥来自环境变量:恢复以后仍用它,不动 secret.key 文件
	FromEnv bool
	// Key 是当前生效的密钥;读不出(文件坏了)时为空
	Key []byte
}

ActiveKey 是校验恢复时「当前生效的密钥」:设了环境变量 PT_TOOLS_SECRET_KEY 时是它,否则是现在的 secret.key。

type ApplyResult

type ApplyResult struct {
	// Name 是待恢复的备份名;没有待恢复时为空
	Name string
	// Applied 为真表示换上了
	Applied bool
	// Err 是没换上的原因:文件已经放回原位,按原来的数据继续启动
	Err error
	// PreRestoreDir 是换下来的原文件放在哪
	PreRestoreDir string
}

ApplyResult 是启动时恢复的结果。

func ApplyPending

func ApplyPending(dataDir string, envKey bool, now time.Time) (ApplyResult, error)

ApplyPending 在启动时、打开数据库与启动检查以前换上待恢复的文件(只在 Web 服务进程里调用)。envKey 为真表示 这个进程用的是环境变量 PT_TOOLS_SECRET_KEY 的密钥:这时不动 secret.key 文件。

要不要换密钥:待恢复里有备份的密钥、没有用环境变量、现有的 secret.key 和它不同(包括没有、读不出、启动时新生成的)时换。

  1. 记下内存里的密钥状态;把现有的数据库(-wal、-shm,要换密钥时还有 secret.key)挪进 <dataDir>/backups/pre-restore-<时间>/;
  2. 放入待恢复的文件;换了密钥文件时重新读取密钥,没换时不碰密钥状态;
  3. 只读打开换上的数据库,用当前生效的密钥解开每个加密列的密文各一条;
  4. 通过后删掉 restore-pending。

第 1–3 步任何一步失败:原文件挪回原位,换过密钥的原样还原密钥状态,删掉 restore-pending,结果里写明原因,按原来的数据继续启动。 挪回也失败时返回错误:调用方必须停止启动,不在这种状态下打开任何一份数据库。

type Info

type Info struct {
	Name     string   `json:"name"`
	Path     string   `json:"-"`
	Size     int64    `json:"size"`
	Manifest Manifest `json:"manifest"`
	Err      string   `json:"error,omitempty"`
}

Info 是备份目录里的一份备份。Err 非空表示读不出它的 manifest(坏文件也列出来,让人能删掉)。

func Create

func Create(ctx context.Context, db *gorm.DB, opts Options) (Info, error)

Create 做一份备份:先用 VACUUM INTO 取一份一致的快照(运行中也能做,期间别的数据库操作稍等),再打成 tar.gz。 先写 .part,Sync 后改名,中途失败不留半个文件。

func List

func List(dir string) ([]Info, error)

List 列出备份目录里的备份,最新的在前。目录不存在时返回空。

type Key

type Key struct {
	Bytes  []byte
	Source string
}

Key 是要放进备份的密钥与它的来源(SecretFromFile 或 SecretFromEnv)。

type KeyAction

type KeyAction string

KeyAction 是恢复以后用哪把密钥。

const (
	// KeyKeepEnv:仍用环境变量里的密钥
	KeyKeepEnv KeyAction = "keep-env"
	// KeyUseBackup:secret.key 换成备份里的
	KeyUseBackup KeyAction = "use-backup"
	// KeyKeepFile:secret.key 不动
	KeyKeepFile KeyAction = "keep-file"
)

type Manifest

type Manifest struct {
	Format        int       `json:"format"`
	AppVersion    string    `json:"app_version"`
	SchemaVersion int       `json:"schema_version"`
	CreatedAt     time.Time `json:"created_at"`
	Reason        Reason    `json:"reason"`
	DBSHA256      string    `json:"db_sha256"`
	DBSize        int64     `json:"db_size"`
	HasSecret     bool      `json:"has_secret"`
	// SecretSource 是密钥从哪来的:file(secret.key)或 env(PT_TOOLS_SECRET_KEY);不带密钥时为空
	SecretSource string `json:"secret_source,omitempty"`
}

Manifest 是备份里的说明:格式版本、做备份的程序版本与数据库版本、时间、原因、数据库的 SHA-256 与大小、带没带密钥与密钥来源。

func ReadManifest

func ReadManifest(path string) (Manifest, error)

ReadManifest 只读备份里的 manifest(它是第一个文件,不用解开整个包)。

type Options

type Options struct {
	// Dir 是备份目录:按时间与原因起名放在这里
	Dir string
	// Output 非空时写到这个文件(命令行 --output);是已有的目录时在里面起名;文件已经存在时报错,不覆盖
	Output        string
	Reason        Reason
	IncludeSecret bool
	// AppVersion 是这份数据所属的程序版本(升级前备份写上一个版本)
	AppVersion string
	// Key 在带上密钥时调用
	Key func() (Key, error)
	// Now 为空时用 time.Now
	Now func() time.Time
}

Options 是做一份备份的参数。

type Pending

type Pending struct {
	Plan
	// HasKey 为真表示待恢复里放了备份里的密钥(备份带了密钥、暂存时没用环境变量)。启动时现有的 secret.key 和它不同就换上它:
	// 暂存时两把一样、之后原来的 secret.key 丢了(启动时新生成了一把)的情况也能用备份里的密钥启动。
	HasKey   bool      `json:"has_key"`
	StagedAt time.Time `json:"staged_at"`
}

Pending 是已经放好、下次启动生效的恢复。

func ReadPending

func ReadPending(dataDir string) (*Pending, error)

ReadPending 读已经放好的待恢复;没有时返回 nil。半成品(没有 ready)也当作没有。

func Stage

func Stage(src, name, dataDir string, active ActiveKey, now time.Time) (Pending, error)

Stage 校验一份备份,通过后把数据库(要换密钥时还有密钥)放进 <dataDir>/restore-pending/,下次启动时生效。 已有的待恢复被替换。name 是给人看的备份名(上传的文件没有备份目录里的名字)。

type Plan

type Plan struct {
	Name     string    `json:"name"`
	Manifest Manifest  `json:"manifest"`
	Key      KeyAction `json:"key_action"`
	// NoCipher 为真表示备份数据库里没有任何密文,不需要密钥
	NoCipher bool `json:"no_cipher"`
}

Plan 是校验通过的一份备份的恢复方案。

func Verify

func Verify(src, workDir string, active ActiveKey) (Plan, error)

Verify 校验一份备份并给出恢复方案,不改任何东西。workDir 放临时解开的文件,用完删掉。

type Reason

type Reason string

Reason 是做这份备份的原因。

const (
	ReasonScheduled  Reason = "scheduled"
	ReasonPreUpgrade Reason = "pre-upgrade"
	ReasonManual     Reason = "manual"
	ReasonCLI        Reason = "cli"
)

func (Reason) Label

func (r Reason) Label() string

Label 是给人看的原因。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL