维护与备份
备份范围
| 方式 | 包含 | 不包含 / 恢复边界 |
|---|---|---|
| 网页 JSON | 订阅、规则、番剧配置、元数据绑定与历史条目摘要 | 不含账户凭据、下载器任务或媒体；恢复只合并订阅与番剧配置，不恢复历史条目 |
| OPML | RSS 订阅信息 | 不是应用完整备份，不能恢复任务、媒体或全部番剧设置 |
| 数据目录备份 | SQLite、封面、内置下载器配置/源文件/会话及更新运行资料 | 不含另行挂载的媒体或外部下载器数据 |
| 完整部署备份 | 数据目录、所有媒体、外部下载器数据及部署配置 | 需停止相关写入并保持目录/版本一致，不由网页一键完成 |
JSON 中的资源地址和路径可能含令牌或私人信息，分享前检查；完整数据库、下载器配置和环境文件还可能包含凭据，备份应私密保存。
完整备份与恢复
- 记录版本、Compose 配置、环境参数、目录映射和飞牛目录授权。
- 正常停止 Auto-Anime，等待内置下载器退出；外部下载器另行安排一致性备份。不要仅复制运行中的 SQLite 主文件而忽略 WAL。
- 复制实际数据目录以及所有媒体位置。通用 Compose 默认
docker-data/，飞牛 Compose 默认data/与media/，Windows 默认程序同级data/。FPK 使用飞牛管理的应用数据与共享媒体目录。 - 恢复时先停止目标实例，恢复到正确挂载位置、检查属主/ACL，再用匹配版本启动。
- 核对账户、订阅、暂停任务、源文件映射和媒体。一个数据库不得同时由新旧实例使用。
非 root 飞牛数据目录含 runtime/ 私有运行副本。完整备份保留它；不要在运行中删除它或下载器会话。网页恢复不是换机器后的完整任务恢复。
版本更新
发布程序启动后检查版本，之后每 6 小时复查，也可在设置手动检查。一键更新下载当前平台程序、校验并暂存，再按平台应用；内置 BT 下载器随主程序更新。它不会替换 Docker 镜像或 FPK 生命周期模板。
| 环境 | 行为与建议 |
|---|---|
| 可写程序目录的 Linux 发布程序 | 替换主程序并就地重启；容器本身不重建 |
| 普通 Docker 发布镜像 | 暂存放在数据库同级；可写时立即应用。持久化暂存可在旧镜像重建后由启动引导重新采用，但仍建议更新镜像 |
| 非 root 飞牛容器 | 在 /data/runtime/<镜像程序摘要> 使用可写私有副本，同镜像重启保留该副本；换镜像建立新运行目录 |
| 程序目录只读 | 只能暂存；重启并不会使只读目录变为可写，应调整权限或更新镜像 |
| Windows | 暂存，下次启动引导应用；正常退出后再启动，界面按实际结果提示 |
源码 / 默认本地镜像 dev | 不支持自动替换，更新源码并重新构建 |
暂存文件位于数据库同级的 auto-anime.update 及校验文件；程序也会检查可用暂存位置。它不是镜像更新、数据库回滚或完整安装器。
当暂存位置与程序目录不同，启动引导采用后仍保留更新包及校验记录，供旧镜像重建后再次使用；程序文件哈希已与更新包一致时不会重复替换或重启。同目录采用会移动暂存包，不保留独立副本。
Docker 推荐升级流程：停止并备份，拉取新镜像，保留原挂载重建，再检查日志和版本。
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100只重启不拉取镜像。固定版本标签的部署须主动修改镜像标签。FPK 安装/升级还需要同版本公开镜像，应用模板更新应通过对应 FPK 完成；Windows 下载器升级应正常退出后更新完整桌面包，保留数据目录。
不存在已验证的“一键回滚”。数据库迁移和密码哈希升级可能使旧程序不兼容，回退应恢复升级前完整备份，而不是只换旧 exe 或旧镜像。
故障排查
| 现象 | 检查顺序 |
|---|---|
| 重建后出现首次设置 | /data 是否仍指向原目录、DB_PATH 是否变化；不要先初始化新库 |
| 修改环境变量无效 | 是否重建容器；对应值是否已保存在数据库 |
| 已提交但未保存 | 下载器实际状态、磁力元数据/校验、源目录映射、归档权限与空间 |
| 已保存但找不到媒体 | 数据库显示的归档路径、容器路径对应的 NAS 挂载，不要先删容器 |
| 下载器恢复中 | 查看日志与健康状态，保留私有会话；旧任务加载有等待期 |
| 暂停任务重启后未继续 | 正常行为，需手动继续；默认模式切换不会迁移任务 |
| 版本检查失败 / Release 404 | 仓库和网络是否可用，私有仓库是否配置合适令牌 |
| 镜像拉取失败 | NAS 到 GHCR 的连接、包公开状态、版本与架构；网页代理不作用于 Docker |
| 登录 429 | 等待失败限流解除，检查反向代理是否使用户共享来源 |
| 播放无法解码 | 使用支持该编码的媒体服务器，内置播放器不转码 |
归档有持久化提交记录，文件完成但数据库提交失败时会恢复提交，不能据此手动删除目标文件。发现媒体存在但提交标记不完整时保留文件并检查，不把它当成成功归档。
删除订阅或条目默认保留媒体。番剧管理中明确删除媒体是独立操作，执行前核对路径与备份。关闭保留源文件也只处理满足安全条件的后续清理，不是批量磁盘回收工具。
部署安全与验证边界
完成账户初始化，在可信网络使用；公开健康接口和安装配置页不代表管理 API 无需认证。反向代理、公网访问和 TLS 应由部署者单独配置并验证。
目录检测、单元测试、模拟下载、CI QEMU 启动和历史实机记录各有适用边界。它们不能证明全部 NAS、ARM 硬件、文件系统、共享断连、长路径和正式图形升级均兼容。问题报告可包含版本、部署方式及脱敏错误，不上传真实凭据、数据库或媒体。
本页同步自仓库 docs/MAINTENANCE.md