# Docker 数据持久化、备份与恢复

**简体中文** · [English](./DOCKER_DATA_AND_BACKUP.en.md)

> 文档更新：2026-10-20

ScrapeFun 容器可以随时重建，业务数据必须保存在宿主机。当前唯一推荐的 Compose 写法是把整个数据根目录挂载到 `/app/data`：

```yaml
services:
  app:
    volumes:
      - ${SCRAPEFUN_DATA_DIR:-./scrapefun-data}:/app/data
```

不要分别挂载 `db`、`images`、`config`、`custom-scrapers` 等子目录。分目录配置只能保护当时列出的内容，新版本增加 `user-avatars`、模型、缓存或其他运行目录后，未挂载的数据会留在容器可写层，并在容器重建时丢失。

## 数据目录

默认宿主机目录是一键部署目录旁的 `~/scrapefun-data`；NAS 手动 Compose 通常使用项目目录下的 `./scrapefun-data`。实际路径以 `.updater.env` 的 `SCRAPEFUN_DATA_DIR` 或 Compose 配置为准。

部署配置与业务数据应一起保留。密钥、存储密码和备份文件不要上传公开 Issue；离机备份应限制访问或加密。

主要内容包括：

| 子目录 | 内容 | 应用内备份 |
| --- | --- | --- |
| `db` | SQLite 数据库、设置、用户、媒体库、进度和任务 | 包含 |
| `images` | 海报、背景图、生成封面和阅读背景 | 标准备份可省略可重建远程图片 |
| `user-avatars` | 用户头像 | 包含 |
| `config` | 系统刮削器运行时配置 | 包含 |
| `custom-scrapers` | 旧版兼容的自定义刮削器文件 | 存在时包含 |
| `local-subtitles` | 本地字幕 | 包含 |
| `artwork-sources`、`file-artwork`、`storage-credentials` | 图片来源、文件封面、存储凭据 | 包含 |
| `video-proxy-cache`、`transcode-cache` | 视频代理和转码缓存 | 不包含，可重建 |
| `comic-cache`、`image-cache`、`image-upscale-cache` | 漫画和图片缓存 | 不包含，可重建 |
| `media-probe-v2`、`temp`、`logs`、`cache` | 探测、临时文件和日志 | 不包含，可重建 |

## 从旧分目录挂载迁移

先检查当前容器：

```bash
docker inspect scrapefun \
  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
```

如果看到多条 `/app/data/db`、`/app/data/images` 等挂载，不要直接编辑 Compose 后重建。最新版一键脚本会默认停止，并要求显式执行迁移：

```bash
curl -fsSL https://raw.githubusercontent.com/HaoweiLi97/ScrapeFun/main/scripts/one-click-compose-deploy.sh \
  | bash -s -- ~/scrapefun --migrate-data-root
```

命令沿用现有渠道；自定义部署请替换 `~/scrapefun`。迁移脚本不会自动导出应用备份，执行前必须自行导出并保留。

迁移流程：

1. 执行脚本前，自行暂停写入任务并导出应用内备份。
2. 停止 app，但先不要删除旧容器。
3. 将旧容器 `/app/data` 中未挂载的其他目录复制到统一宿主机数据根目录。
4. 确认数据库、图片、配置、头像、字幕和其他目录都在同一个根目录。
5. 把 Compose 改为单个根挂载，再重建 app。
6. 复制完成后安装器会重建 app；完成后验证登录、媒体库、图片、刮削器和播放，并保留事先导出的备份。

无法判断哪些文件只存在于旧容器时，不要继续重建；先保留旧容器并寻求支持。

## 应用内备份（推荐）

在设置页的备份与恢复中导出 ZIP。当前 `snapshot-v5` 包含一致性数据库快照、逐文件大小和 SHA-256、图片来源、文件封面、头像、本地字幕、存储凭据及刮削器文件。

标准备份默认省略已有可靠重建来源的远程图片，恢复后按来源重建；完整应用备份保留这些图片。两者均排除可再生成缓存、临时文件和日志，完整应用备份不等于宿主机完整备份。

仍支持 `snapshot-v4`、`snapshot-v3`、`snapshot-v2` 和 `backup.json`。旧版本未必能导入 v5，恢复前核对格式兼容性。备份可能含存储密码，应限制访问或加密并保留离机副本。应用 ZIP 不包含宿主机 `server.env` 等部署配置，须单独备份。

## Docker 宿主机完整备份

灾难恢复应同时备份数据目录与部署配置。以下工具要求一键部署的 `docker-compose.remote.yml` 和 `.updater.env`，NAS 手动 Compose 不能直接套用，应按面板流程备份。运维工具安装在一键部署目录：

```bash
cd ~/scrapefun
./operations/backup-docker.sh --deploy-dir "$PWD" --output-dir /srv/backups/scrapefun
```

工具自动读取 `.updater.env`、停止并恢复 app、验证 SQLite、归档数据和配置、生成 manifest/SHA-256，并保留 7 日、4 周、6 月恢复点。缓存默认排除；添加 `--include-caches` 才会包含。符号链接或特殊文件会在归档前被拒绝，避免生成不安全或不完整的备份。

可选的加密和异机复验：

```bash
./operations/backup-docker.sh \
  --deploy-dir "$PWD" \
  --output-dir /srv/backups/scrapefun \
  --age-recipient age1你的公钥 \
  --rclone-remote minio:scrapefun/backups
```

`server.env` 和 `.updater.env` 可能包含密钥。age 私钥必须存放在数据目录和备份之外；只有远端副本重新下载并通过 SHA-256 复验，才算异机备份成功。

使用 `install-docker-backup-timer.sh` 安装 systemd 定时任务时，通知地址保存在仅 root 可读的 `/etc/scrapefun-backup.env`，不会出现在 `ExecStart` 命令行中。

## 从应用备份恢复

1. 先导出当前实例备份作为回退点。
2. 确认没有扫描、刮削、整理、转码或升级任务。
3. 在 `设置 → 通用 → 备份与恢复` 中选择“导入”。
4. 上传 ScrapeFun 导出的 ZIP，等待恢复成功并自动重启。
5. 恢复后检查登录、用户、媒体库、图片、刮削器、WebDAV/AList、播放与阅读进度。

恢复会先校验归档和 SQLite，再写入暂存位置，并在重启时统一提交；失败时会回滚。每次成功恢复还会保留恢复前数据库，默认保留最近 3 份，但这些本地副本不能代替离机备份。

## 从完整数据目录恢复

使用恢复工具，不要直接覆盖当前目录：

```bash
cd ~/scrapefun
./operations/restore-docker.sh \
  --deploy-dir "$PWD" \
  --backup /srv/backups/scrapefun/scrapefun-docker-backup-YYYYMMDDTHHMMSSZ.tar.gz
```

工具会校验内外归档、预检空间、在新目录解压、检查 SQLite、保留当前数据为 `.pre-restore-*`，并在启动后验证 readiness。加密归档需添加 `--age-identity /安全路径/identity.txt`。恢复验证完成并重新生成备份后，才删除旧目录。

定期运行隔离恢复演练：

```bash
./operations/drill-docker-backup.sh --backup /srv/backups/scrapefun/备份文件.tar.gz
```

## 恢复后检查

下列命令对应一键部署的 `docker-compose.remote.yml` / `.updater.env`。NAS 手动示例使用 `docker compose --env-file .env --env-file .updater.env ps` 和 `docker compose --env-file .env --env-file .updater.env logs --tail=200 app`；访问端口按实际配置替换。

```bash
docker compose --env-file .updater.env -f docker-compose.remote.yml ps
docker compose --env-file .updater.env -f docker-compose.remote.yml logs --tail=200 app
curl -fsS http://127.0.0.1:8096/health/live
curl -fsS http://127.0.0.1:8096/health/ready
```

`/health/ready` 会检查启动、数据库、数据目录权限和恢复事务；仍应实际检查登录、媒体库、海报/头像、本地字幕、刮削器注册、WebDAV/AList 和一次播放。

## 避免误删

- 不要执行 `docker compose down -v`。
- 不要删除或清空 `scrapefun-data`。
- 不要把新备份直接解压覆盖正在使用的数据目录。
- 不要只备份 SQLite 数据库；数据库和文件资源必须来自同一时间点。
- NAS 删除 Compose 项目前，先确认面板不会同时删除绑定目录。
- 更新或重建后，确认仍是同一个宿主机目录挂载到 `/app/data`。

[文档中心](./docs/README.md) · [Docker 运维](./DOCKER_GUIDE.md) · [支持](./SUPPORT.md) · [许可与协议](./legal/README.md)