Module backup 

备份/恢复（双模式 + 任务进度）。 备份与恢复（读写，最高风险）。

备份：探测 pg_dump 可用性——可用则子进程生成完整、角色无关的 .sql （--clean --if-exists --no-owner --no-privileges），不可用则回退纯 SQL（仅数据）。 备份文件含签名头。每次备份按设置附带 uploads 素材打包（_uploads.tar.gz， 排除可重建的 .cache/），与 .sql 成对展示/下载/删除。

来源标记：手动备份文件名前缀 backup_，定时任务自动备份前缀 auto_； 自动备份按 backup_retention_count 轮转（只删自动，手动永不自动删）。

恢复：仅接受本系统生成的备份（签名校验）+ 二次确认 + 路径穿越防护； 旧备份的 pg_dump 属主语句会在 COPY 感知的预处理阶段移除，再由 psql --single-transaction -v ON_ERROR_STOP=1 原子重放，失败时完整回滚； 仅恢复数据库——uploads 需从配对 tar.gz 手动还原；成功后全量失效缓存。 长耗时操作走后台任务 + 进度轮询（见 crate::api::database::tasks）。

导入：POST /api/database/backups/import（纯 Axum 路由，multipart 流式落盘） 把本机备份回灌进 backups/。两步式——导入只入库，恢复仍走上述管线。 导入时即强制签名校验（外来 SQL 拒收不留盘）；保留原始文件名、同名冲突拒绝； .tmp 落盘 + 原子 rename，半截文件永不出现在列表。上限 BACKUP_IMPORT_MAX_MB （默认 512MB），路由层 DefaultBodyLimit + 流式计数双保险。

兼容性提示：--clean --if-exists 是后加的备份参数。本修复之前生成的备份 文件不含 DROP，对其执行恢复会在第一条「relation already exists」处中止并报 失败（行为正确，但无法恢复数据）——需重新创建备份才能恢复。

Structs

BackupInfo

备份文件元信息（列表展示用）。

BackupRunOutcome 🔒

一次备份运行的结果（调度任务据此落库 last_run）。

PreparedRestoreSql 🔒

Enums

BackupOrigin 🔒

备份来源：决定文件名前缀与是否参与自动轮转。

Constants

BACKUP_DIR 🔒

备份目录（项目根，与 uploads/ 平级，gitignored）。

BACKUP_SIGNATURE 🔒

备份文件签名头（恢复时校验，拒绝非本系统文件）。

DEFAULT_IMPORT_MAX_MB 🔒

导入单文件上限默认值（MB），env BACKUP_IMPORT_MAX_MB 覆盖。

FILENAME_RE 🔒

文件名白名单正则：仅字母数字下划线点连字符（防路径穿越）。

MULTIPART_FRAME_SLACK 🔒

multipart 框架开销宽限（boundary/头部），加在路由 body limit 上， 避免恰好等于上限的文件被框架字节误杀（流式计数只计载荷字节，才是权威）。

Functions

backup_partition_free_space 🔒

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

backup_path 🔒

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

create_backup

发起备份，立即返回 task_id，后台任务执行。

create_uploads_tarball 🔒

把 uploads 目录打成 tar.gz（排除可重建的 .cache/ 与 VCS 占位 .gitkeep）。 阻塞 IO + CPU（gzip），调用方须放 spawn_blocking。 uploads_dir 显式传入（而非写死相对路径）便于测试注入临时目录。

delete_backup

删除备份文件（连同配对的 uploads 打包；配对缺失不视为错误）。

download_backup

Axum 处理器：下载备份文件（admin 鉴权 + 路径白名单）。 仅 server 构建：纯 Axum 路由（在 main.rs 注册），无 WASM 消费者。

has_valid_signature 🔒

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

import_backup

Axum 处理器：导入备份（multipart 流式落盘，admin 鉴权 + 签名校验 + 同名拒绝）。

import_max_bytes 🔒

导入单文件上限（字节）：env BACKUP_IMPORT_MAX_MB（MB 为单位），默认 512MB。 main.rs 路由 DefaultBodyLimit 与 handler 流式计数共用此值。

is_legacy_pg_dump_owner_statement 🔒

is_valid_backup_filename 🔒

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

list_backups

列出 backups/ 目录下的备份文件元信息。

parse_backup_mode 🔒

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

pg_dump_command 🔒

pg_dump 模式：子进程生成完整备份（含 schema），前置签名头。

psql_restore_command 🔒

read_first_line 🔒

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

read_first_lines 🔒

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

restore_backup

发起恢复：校验签名 + 路径穿越防护 + 二次确认，立即返回 task_id。

rotate_auto_backups 🔒

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

run_auto_backup 🔒

定时任务入口：注册任务后执行自动备份，返回结果供调度器落库 last_run。

run_backup 🔒

后台执行备份：pg_dump 优先，不可用回退纯 SQL；成功后按设置打包 uploads， 自动备份再做轮转。Ok/Err 均已同步进任务进度表（供前端轮询），返回值供 调度器落库 last_run。

run_pg_dump_backup 🔒

run_restore 🔒

run_sql_fallback_backup 🔒

纯 SQL 回退：仅备份数据（不含 schema），按表计数精确进度。

sanitize_import_filename 🔒

校验并清洗导入文件名：剥离路径分量（旧浏览器可能带 C:\fakepath\ 前缀）， 要求 .sql 后缀 + 非隐藏文件 + 备份文件名白名单。纯函数便于单测。

select_expired_auto_backups 🔒

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

sql_line_without_eol 🔒

后台执行恢复：探测 psql，可用则原子恢复，不可用则报告。

uploads_archive_name 🔒

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

write_owner_neutral_restore_sql 🔒