Documentation
¶
Overview ¶
Package backup 做 pt-tools 数据的备份与恢复(媒体中心方案 M0)。
一份备份是一个 tar.gz:manifest.json、torrents.db(VACUUM INTO 取的一致快照,服务运行中也能做)、 secret.key(选了带上密钥时)。恢复分两段:网页或命令行先校验,通过后放进 <数据目录>/restore-pending/; 下次启动、打开数据库以前换上,换完用当前生效的密钥复验,任何一步失败都把原来的文件放回去、按原来的数据启动。
Index ¶
- Constants
- Variables
- func CancelPending(dataDir string) error
- func Delete(dir, name string) error
- func IsBackupName(name string) bool
- func Prune(dir string, keepScheduled int) ([]string, error)
- func Resolve(dir, name string) (string, error)
- type ActiveKey
- type ApplyResult
- type Info
- type Key
- type KeyAction
- type Manifest
- type Options
- type Pending
- type Plan
- type Reason
Constants ¶
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" )
默认值与范围(设置页与定时任务共用)。
const FormatVersion = 1
FormatVersion 是备份文件格式的版本,manifest 里记着;比它新的备份不认。
const PendingDir = "restore-pending"
PendingDir 是待恢复的文件放在数据目录下的哪个子目录。
Variables ¶
var ErrInvalid = errors.New("备份文件不能用")
ErrInvalid 是备份文件本身有问题(不是 pt-tools 的备份、内容被改过、数据库损坏、版本太新……)。
var ErrKeyMismatch = errors.New("密钥对不上")
ErrKeyMismatch 是按密钥规则不能恢复:恢复以后生效的密钥解不开备份里保存的 Cookie 与通知凭证。
var ErrNotFound = errors.New("备份不存在")
ErrNotFound 是备份目录里没有这份备份(或者文件名不是这里起的)。
Functions ¶
func CancelPending ¶
CancelPending 取消还没生效的恢复(删掉 restore-pending)。
func IsBackupName ¶
IsBackupName 报告 name 是不是这里起的备份文件名(只有文件名,不含目录)。
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 ¶
ApplyPending 在启动时、打开数据库与启动检查以前换上待恢复的文件(只在 Web 服务进程里调用)。envKey 为真表示 这个进程用的是环境变量 PT_TOOLS_SECRET_KEY 的密钥:这时不动 secret.key 文件。
要不要换密钥:待恢复里有备份的密钥、没有用环境变量、现有的 secret.key 和它不同(包括没有、读不出、启动时新生成的)时换。
- 记下内存里的密钥状态;把现有的数据库(-wal、-shm,要换密钥时还有 secret.key)挪进 <dataDir>/backups/pre-restore-<时间>/;
- 放入待恢复的文件;换了密钥文件时重新读取密钥,没换时不碰密钥状态;
- 只读打开换上的数据库,用当前生效的密钥解开每个加密列的密文各一条;
- 通过后删掉 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(坏文件也列出来,让人能删掉)。
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 ¶
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 ¶
ReadPending 读已经放好的待恢复;没有时返回 nil。半成品(没有 ready)也当作没有。