备份与恢复

Sena Repo 的服务端数据可以通过 senacli 导出和恢复，用于换机、重装或迁移。

导出与恢复（senacli）

senacli backup / senacli restore 用于在换机、重装前导出服务端数据。默认导出成单个 zip：

sena-backup-<时间戳>.zip
├── backup.json           # 结构化数据
└── media/
    ├── covers/           # 封面（文件名为内容哈希）
    ├── backgrounds/      # 横版背景
    └── avatars/          # 用户头像

图片按内容哈希命名，因此不同游戏即使原本同名也不会互相覆盖或串图；相同图片只会在 zip 里存一份。

backup.json 包含五块：

区块	内容
`steam_patch`	补丁匹配规则（AppID、游戏名、标签、类型、`patch_dir`、`target_dir`、清单确认状态、锁定状态）、补丁类型关键词与补丁库目录（含来源与分析模式）
`library`	文件源（OpenList 地址、账号、密码、启用状态）、目录库（含来源与批量刮削开关）、平台分类（名称、顺序与匹配规则）、会社、游戏（含别名、封面/背景、NSFW、VNDB/Steam/Bangumi/Hikarinagi/NextMoe ID、简介等）、版本（含平台、解压密码、校验值、来源）、标签与关联、忽略列表
`accounts`	用户（用户名、角色、状态、密码哈希与 salt、头像，以及 NextMoe 绑定字段与是否设置过本地密码）
`settings`	扫描设置、刮削设置（启用的源、NextMoe 模式、各站 token / NextMoe API Key、代理）与自定义分类正则
`media`	zip 里包含的图片清单（内容哈希、原文件名、大小）

备份内部用 src-1、root-2、game-3 这类备份内标识描述关联，恢复时再解析成本机 ID，不依赖两台机器的数据库 ID 是否一致。

不含游戏文件本体、补丁文件本体、用户登录态（user_sessions）与部署配置（安装路径、端口、/etc/sena-repo/sena-repo.env）；config.yaml 里只恢复 custom_regex，其余键保持目标机器的配置。

备份文件里有密码哈希、解压密码、OpenList 密码与各站 token（导出时解密、导入时按目标机器的密钥重新加密），请当作敏感文件保管。

只接受当前格式

备份格式带版本号，当前为 v5。旧版本的备份（包括更早的仅补丁规则 JSON）不再兼容，恢复时会直接提示格式不支持；请在旧服务端用当前版本的 senacli backup 重新导出。

bash

# 备份到数据目录下的 backups/sena-backup/
senacli backup

# 换目录，或指定文件名
senacli backup /path/to/backup-dir
senacli backup -o /path/to/backup.zip

# 只要 JSON，不带图片和头像
senacli backup --json-only

# 只备份一部分（all 默认：游戏库 + 补丁）
senacli backup --scope library     # 仅游戏库、文件源、设置与账号
senacli backup --scope patch       # 仅补丁规则、关键词、补丁库目录与它们依赖的文件源

# 恢复（会依次询问恢复范围、已存在条目怎么处理、已有图片怎么处理）
senacli restore sena-backup-20260915-153000.zip

# 全部按默认值（全部恢复 / 合并更新 / 保留本机图片），脚本化用
senacli restore sena-backup-20260915-153000.zip -y

恢复时的三个选择：

恢复范围：全部 / 仅补丁规则 / 仅游戏库、账号与设置（备份里两块都有时才问）
已存在的条目：合并更新，或清空重建
已有图片：保留本机已有的封面/背景，或换成备份里的

自动备份

服务端进程里有一个后台任务负责定时备份，不需要系统 cron 或 systemd timer，Docker 部署同样可用。

频率：每 N 小时、每天、每周（可多选星期几）、每月（几号）
时间点：每天 / 每周 / 每月可以配多个时间，例如 03:00 和 15:00
执行窗口（可选）：只在 02:00–06:00 这类时段内执行，算出的时间落在窗口外就顺延到窗口开始
补跑：服务器在预定时间关机时，下次启动补跑一次，然后按原计划继续
时间都按服务器本地时区

保留策略按档位计算，同一时间段只留最新一份：

档位	含义	默认
最近	最近 N 份全部保留	7
每天	每天保留 1 份，共 N 天	14
每周	每周保留 1 份，共 N 周	8
每月	每月保留 1 份，共 N 月	12

填 0 关闭该档。清理只针对 auto-sena-backup-*，手动导出的 sena-backup-* 和上传的 uploaded-* 永远不会被自动删除。

会跳过的几种情况：

数据没有变化：比对行数、最新更新时间与数据文件 mtime，一致就不生成新包（可在界面关闭）
正在恢复或扫描：拿不到恢复锁时本轮跳过，5 分钟后重试
磁盘余量不足：低于设定值时跳过并记录，按 15 分钟起、最长 6 小时的指数退避重试
失败不会删除任何旧备份，只有成功后才执行清理

计划、上次结果和下次时间保存在 <data>/backup_settings.json。配置接口是 /api/settings/backup，仅服主可用；默认关闭，装上不会自己占磁盘。

恢复行为

写入顺序固定为 文件源 → 分类与目录库 → 游戏 → 版本与标签 → 补丁目录与规则 → 账号，这样后一步总能找到前一步建立的关联。

手动／元数据条目（entry_source 为 manual / metadata）不依赖实体目录库，按原样恢复，不会被跳过
OpenList 关联：目录库、版本和补丁规则都按备份里的文件源重新绑定，source_id 与 patch_id 会按目标机器的实际 ID 重写，换机后仍然可用
补丁库目录按「来源类型 + 文件源 + 路径」匹配，不同文件源下的相同路径会保留为两个目录
补丁规则：索引里找不到对应文件的规则会按备份内容补建，不会再因为存在一个空索引就整批丢失；锁定状态一并恢复
平台分类：恢复名称、顺序与匹配规则；「清空重建」会先移除自定义分类再按备份重建，保留系统分类「未分类」
图片：按内容哈希落盘，合并时「保留本机」只影响同一个游戏已有的封面/背景，不会覆盖或复用其他游戏的图片；备份里没有头像的账号会保留本机头像
会社：即使没有任何游戏引用也会恢复，不会因为游戏被跳过而丢失
服主保护：合并时当前服主永远不会被降级或停用，备份里的另一位服主会作为管理员恢复；恢复提交前会校验最终仍有唯一、启用且有登录方式的服主，否则取消本次恢复
扫描/刮削设置恢复后会立即生效；senacli 写完后，运行中的服务端会在下一次读取设置或启动刮削任务时自动重新加载

内容	合并更新	清空重建
游戏、版本、标签	按路径/名称匹配，保留本机额外条目	按备份重建所选范围
锁定元数据的游戏	保持原样	保持原样
平台分类	恢复同名分类的规则与顺序，保留额外分类	重建分类与规则
目录库	恢复批量刮削开关等配置	按备份重建
文件源	同名源保留本机地址与密码，缺失的创建；多个同名源按地址区分	按备份覆盖
服主	保留当前服主	使用备份中的服主
备份中缺失的区块	不修改对应数据	不把「缺失」当成「清空」

失败回滚

恢复前会：

完整校验备份结构与交叉引用，再动任何数据
取得跨进程恢复锁，避免与扫描、刮削或另一个恢复同时写数据
用 SQLite Backup API 给数据库拍快照，并把补丁索引、关键词、设置文件、config.yaml 复制到 backups/sena-backup/
写一份 restore-in-progress.json 日志

结构化数据在同一个数据库事务里提交；图片、补丁索引和设置文件随后写入。任何一步失败都会删除本次新增的图片、还原被替换的文件，并把数据库回滚到快照状态。若进程在中途被强制结束，日志会保留，下次恢复或启动时会提示安全快照的位置。

从备份重建服务端

新装一台服务端后，有两种方式导入备份：

客户端向导：连接到未初始化的服务端时，向导第一页选「导入备份」，直接上传 zip。服务端只在还没有服主时接受这种导入（POST /api/setup/import），导入完成后用备份里的账号登录。
senacli：把 zip 放到服务端（或挂载目录）后执行 senacli restore <zip>，先 senacli restore <zip> -y 也可以用默认选项一把过。这条路同样适用于已完成初始化的服务端。

上传的 zip 会保留在 <data>/backups/ 下，名字形如 uploaded-<时间戳>-<随机>.zip。

已初始化的服务端还可以在客户端「设置 → 服务端 → 备份与恢复」里导出、下载和恢复备份，走的是同一套逻辑（/api/backup/*）：查看列表与删除备份管理员即可，导出、下载与恢复仅服主可用。导出会在 <data>/backups/sena-backup/ 生成 zip 并列在页面里；导入时可选恢复范围、合并或清空重建、已有图片保留或替换。恢复完成后会显示各项实际写入与跳过的数量；如果账号数据被替换导致当前登录态失效，客户端会提示并引导重新登录。

备份与恢复 ​

导出与恢复（senacli） ​

只接受当前格式 ​

自动备份 ​

恢复行为 ​

失败回滚 ​

从备份重建服务端 ​