Module files 

备份命名、签名、元信息、配对归档与自动轮转。

Constants

BACKUP_DIR 🔒

与 uploads/ 同级且被 Git 忽略的备份目录。

BACKUP_SIGNATURE 🔒

导入与恢复共同要求的备份签名。

FILENAME_RE 🔒

文件名白名单禁止目录分隔符与 shell 元字符。

Functions

backup_partition_free_space 🔒

查询 backups/ 所在文件系统的可用空间（取最长挂载点前缀的磁盘）。 预检用途：探测失败返回 None，降级为跳过预检（写入失败仍会清理并报错）。

backup_path 🔒

构造 backups/ 下的安全路径（额外防御：校验规范化后仍在 BACKUP_DIR 内）。

backup_stamp 🔒

备份文件名戳：YYYYmmdd_HHMMSS_mmm_<6 位十六进制随机>。 毫秒 + 随机后缀让同一时刻（含多实例共享 backups/）的两次备份不会撞名； 各段定宽，字典序仍即时间序（自动轮转依赖这一点）。

create_new_backup_file 🔒

独占新建备份产物：目标已存在时报错而不是截断，杜绝两个任务写同一文件。

delete_backup_files 🔒

has_valid_signature 🔒

校验备份文件首行是否含本系统签名头。 提取为纯函数:把首行(或全文)作为参数传入,便于单测。

is_valid_backup_filename 🔒

校验备份文件名是否符合白名单（仅字母数字下划线点连字符）。 返回 true 表示安全可用。提取为纯函数便于单测覆盖路径穿越边界。

list_backup_files 🔒

parse_backup_mode 🔒

从备份文件全文提取 -- mode: <value> 行的值（如 “pg_dump”/“sql-fallback”）。 提取为纯函数:把文件内容作为参数传入,便于单测。 缺失或格式不符返回 “unknown”。

read_first_line 🔒

仅读取文件首行（用于签名校验，避免把整个备份文件读入内存）。

read_first_lines 🔒

读取文件前 n 行（用于解析 -- mode: 等头部元信息，避免整文件读入内存）。 不足 n 行时返回实际读到的行；任一行读取失败则整体返回该错误。

rotate_auto_backups 🔒

执行自动备份轮转：删除超龄自动备份的 .sql 与配对 tar.gz。 单个删除失败只记日志，不中断其余。

rotate_auto_backups_in 🔒

select_expired_auto_backups 🔒

从自动备份 SQL 文件名列表挑出超出保留份数、应删除的最旧者。 文件名内嵌定宽时间戳，字典序即时间序。纯函数便于单测。

uploads_archive_name 🔒

SQL 文件名 → 配对 uploads 打包文件名（X.sql → X_uploads.tar.gz）。