备份与还原 - MiCat-S/Mi302 GitHub Wiki

Mi302 每天自动备份数据库和配置文件。这一页说明备份了什么、放在哪里、怎么手动备份和下载，以及怎么还原。

备份了什么

每次备份生成两个文件，文件名里的时间相同：

文件	内容
`mi302-年月日-时分秒.db`	数据库 `library.db` 的完整副本
`mi302-年月日-时分秒.yaml`	配置文件 `config.yaml` 的副本

例如 mi302-20260927-031500.db 和 mi302-20260927-031500.yaml。

数据库里有：

用户账号、密码哈希，以及播放器的登录状态。
观看记录、播放进度、收藏。
115 登录状态：cookie 和 115 开放平台的 token。
在管理页面上创建的 API 密钥。
115 同步的对照表和进度。
媒体信息、演职人员和他们的中文名、学到的片头片尾。
媒体库的条目，以及服务器 ID（播放器靠它认出这台服务器）。

不在备份里的：

上传的媒体库封面（data/images/）。
日志（data/logs/）。
媒体文件夹里的东西：strm、nfo、海报、字幕、X-mediainfo.json。strm 可以用全量同步重新生成，刮削出来的 nfo 和海报要自己另外备份。

放在哪里

备份放在数据目录（server.data_dir）下的 backups：

安装方式	位置
一键安装（Linux）	`/opt/mi302/config/data/backups`
一键安装（macOS）	`~/Mi302/config/data/backups`
手动用 Python	启动 Mi302 的目录下的 `data/backups`

实际位置显示在“设定”→“备份”卡片上。

自动备份

Mi302 启动后先检查一次，之后每小时检查一次，距离上次备份满 24 小时就备份一份。所以第一次启动后马上就有第一份。
备份时不必停止 Mi302。它用 SQLite 的在线备份，还没写回主文件的数据也包含在内。
备份出来的数据库如果缺少必要的数据表，就不保存，免得用坏掉的备份把旧的好备份挤掉。
自动备份失败时，日志里会记“自动备份失败”和原因。

保留几份

“设定”→“备份”的“保留几份”（server.backup_keep）默认 7，可以填 0 到 90，改完点页面下方的“储存设定”。

每次备份完，只留最新的几份，较旧的 .db 和 .yaml 一起删掉。改小之后，多出来的在下一次备份时删除。
填 0 就不自动备份。仍然可以手动备份，手动的备份留最新 7 份。

手动备份与下载

在“设定”→“备份”卡片：

点“立即备份”马上备份一份，完成后显示“已备份：”和文件名。
下面的列表列出每份备份的时间、文件名、大小，有配置文件的标“含设定档”。
点下载图标下载数据库；点“yaml”下载同一时间的配置文件。

只有管理员登录后才能备份和下载，API 密钥不行。也可以直接从上面的目录复制文件。

还原

停止 Mi302。
把 data 目录里的 library.db 换成要还原的 .db，并删掉 library.db-wal、library.db-shm。
需要的话，把同一时间的 .yaml 换成 config.yaml。
启动 Mi302。

Linux 上用一键安装的例子（把文件名换成你要还原的那份）：

mi302 stop
cd /opt/mi302/config
mkdir -p data/before-restore
mv data/library.db* data/before-restore/     # 当前的数据库先移到旁边，顺便移走 -wal、-shm
cp data/backups/mi302-20260927-031500.db data/library.db
cp data/backups/mi302-20260927-031500.yaml config.yaml   # 要连配置一起还原时才做
mi302 start

macOS 用一键安装的，把 /opt/mi302/config 换成 ~/Mi302/config。
手动用 Python 的，先停掉 Mi302（在运行它的终端按 Ctrl+C，或 sudo systemctl stop mi302），data 和 config.yaml 在你启动 Mi302 的目录里。
这些文件属于运行 Mi302 的账号。请用那个账号操作；用 sudo 复制的话，之后要把所有者改回来，例如 sudo chown 账号 data/library.db config.yaml，否则 Mi302 写不进去。
数据库、备份和配置文件只有运行 Mi302 的账号能读（权限 600）：里面有 115 的登录状态和密码。别的账号要读，自己用 sudo。

还原之后：

账号、密码、观看记录和 115 登录都回到备份时的状态，备份之后的观看记录会丢失。
如果备份里的 115 登录已经失效（例如被同类型的其他登录踢掉），重新扫码登录。
115 同步从备份时的进度继续：下一次增量同步读那之后的生活事件；间隔太久、事件已经超出 115 保留的范围时，自动改跑全量。
还原配置文件的话，媒体库、同步任务和其他设置也回到备份时的样子。

安全

备份里有敏感数据，请当作密码保管，不要发给别人或放到公开的地方：

.db 里有 115 的登录 cookie，拿到的人可以使用你的 115 账号。另外还有密码哈希、播放器的登录 token 和 API 密钥。
.yaml 是配置文件的副本，可能有明文：users 下的密码、MoviePilot 的密码和 API 令牌、p115.cookies、api_keys。