Restore a full backup from Settings
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s

Settings → Data → Import gets "Restore a full backup" in place of the V1
import row. The zip from "Download backup" is uploaded and replaces the
database, every setting and the uploaded files on the running server:

- the staged database is upgraded to this schema (newer backups are refused),
  saved keys are re-encrypted for this server's key, interrupted jobs are
  marked, and the restoring session is carried over;
- a pre-restore snapshot is written, running generations stop, and the file
  is swapped under the open DB handle (DB.replaceWith); uploads and media are
  copied into place and background work restarts.

The /api/import/v1 endpoint stays for the V1 cutover (docs/MIGRATION.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Elijah 2026-11-16 12:33:42 -07:00
parent e0bc7b580e
commit 7125dec3e0
13 changed files with 521 additions and 72 deletions

View file

@ -94,6 +94,29 @@ cannot read an included file fails rather than silently substituting an empty fi
Avoid changing or deleting source files while making a full ZIP; filesystem content is not
transactional with SQLite.
## Restoring a full backup in the app
Settings → Data → **Restore a full backup** uploads a ZIP from "Download backup" and replaces
everything on the running server: content, progress, uploads, AI models and all settings. No
restart is needed. Steps (`server/services/restore.ts`):
- The ZIP is unpacked into a staging folder inside the data folder. Only `study.db`,
`secret.key`, `manifest.json`, `uploads/*` and `media/*` are accepted.
- The staged database is upgraded to this version's schema. A backup from a newer version is
refused.
- Saved API keys are re-encrypted from the backup's `secret.key` to this server's key, so a
backup from another install keeps its AI connections. Keys sealed with an `APP_SECRET` this
server does not have are reported as unreadable and must be entered again.
- A `pre-restore-*` snapshot of the current database is written, running generations stop, and
the database file is swapped under the open handle.
- Files from the backup are copied over the uploads and media folders. Files already there are
left in place.
- The person restoring stays signed in. Later sign-ins use the backup's password.
The upload is the raw ZIP body (up to 20 GB). A proxy may cap uploads well below that (Cloudflare's
free plan allows 100 MB per request). For a larger backup, restore through the server's own
address on the local network, or use the manual drill below.
## Restore drill
1. Download a full ZIP and verify it opens. Stop the V2 container before restoring.