All state portability flows through one versioned JSON document and two import paths for migrating from other readers. Every import is transactional and reports what it skipped and why.
Full backup (export / import)
GET /api/v1/backups/document downloads the built-in admin’s portable reader
state — library membership and manga metadata, categories, reading progress,
app settings and source settings — as one JSON document with a version field
(currently 1; unknown versions are rejected with 400).
POST /api/v1/backups/document imports it into the same owner state, optionally
limited with ?sections=library,categories,progress,settings,sourceSettings.
Import
upserts by natural key (source key + manga key, chapter key, category
name) inside a single transaction, so a failed or invalid backup leaves
the database untouched; entries whose source is not installed are skipped
and reported in the response warnings. Category update and automatic-download
exclusions use the backup-only includeInUpdate and includeInDownload fields
(2 for excluded categories, 0 for all others). Legacy includeInDownload: 1
marks include-only categories, which an exclusion list cannot represent. A
category restore containing any such entry forces auto_download_new_chapters
to false, even when the target or backup enables it; review and reconfigure
category exclusions and automatic downloads before re-enabling them. The raw
library.excluded_update_categories and library.excluded_download_categories
settings are omitted from exports and ignored on import. Instance state only the
server writes, such as library.last_scheduled_run_at and backup.last_run, lives
in the server_state table, so exports never carry it; an older backup that still
names those keys has them ignored on import. Category restoration maps names to
target-local category ids and merges
those ids into the existing exclusion settings without writing the retired
category columns. The settings
page of the web UI has
download and restore buttons.
Admin authentication is instance-local. Plaintext API keys, their SHA-256 fingerprints, and login-session token hashes are neither exported nor restored. Importing a backup leaves the target’s existing keys and sessions untouched, so a restore cannot resurrect credentials revoked on the source. After restoring to a new instance, authenticate with that instance’s admin password and create new API keys as needed.
Scheduled backups
The server can also write backups on its own schedule, so a corrupted
database or a bad change between manual exports stays recoverable. It is
configured through the setting table (the web UI’s settings page exposes
all of it under “自动备份”), and each value can be pinned by an env
override for headless deployments:
| Setting key | Env override | Default | Purpose |
|---|---|---|---|
backup.enabled |
SUMIDOKU_BACKUP_ENABLED |
false |
master switch |
backup.interval_hours |
SUMIDOKU_BACKUP_INTERVAL_HOURS |
24 |
hours between runs (minimum 1) |
backup.retention_count |
SUMIDOKU_BACKUP_RETENTION_COUNT |
10 |
how many newest files to keep |
backup.dir |
SUMIDOKU_BACKUP_DIR |
<config>/backups |
destination directory |
When enabled, a background task writes
sumidoku-backup-<yyyymmdd-HHMMSS>.json (UTC) every interval — a
server-side full export built as the built-in admin, the same document an
admin’s GET /api/v1/backups/document serves — stamps backup.last_run, and
deletes files beyond the retention count, oldest first; the newest file is
never deleted, even with backup.retention_count = 0. At startup, if more
than one interval elapsed since backup.last_run (or no backup was ever
taken), one backup runs immediately, so downtime does not leave a gap.
backup.last_run lives in server_state, so no settings write can change it
and saving an unrelated setting cannot replay an older timestamp.
GET /api/v1/backups/files lists the files (name, size, creation time, newest
first); POST /api/v1/backups/files/restore with {"name": "<file>"} restores
one through the same validated import path as the upload endpoint, and the
settings page lists them with a restore action.
Importing from Aidoku
POST /api/v1/backups/import/aidoku imports an Aidoku app backup (.aib, a
binary plist) into the library: library manga, reading progress (chapter
read state and last page read), categories with membership, and tracker
bindings. Aidoku and Sumidoku share the same source ecosystem, so entries
match on source key and manga/chapter key; entries whose source is not
installed are skipped and reported with a reason in the response skipped
list, never half-imported silently. Tracker bindings come from the backup’s
trackItems rows, keyed by tracker id: anilist, myanimelist (this
server’s mal), bangumi and mangabaka map onto local providers, and a
tracker without one (Shikimori, Komga, Kavita, Suwayomi) is skipped with
tracker not supported instead of being guessed at. A binding’s track id is
the tracker’s own entry id, its offset is carried across, and its track mode
follows the manga’s Aidoku chapter display mode in the backup’s settings dump
(chapter → chapter, volume → volume, default → auto). The import is additive
— existing library entries, categories and tracker bindings keep their
current state, and progress merges by taking the larger last-page-read,
OR-ing the read flag and keeping the newer read timestamp.
POST /api/v1/backups/import/aidoku?dryRun=true runs the same transaction
and rolls it back, returning the would-import report (per-section counts
plus the skipped list) without writing anything. The web UI’s settings page
has an “从 Aidoku 导入” button under the backup section that walks upload →
dry-run preview → confirm. Aidoku settings and source configs are out of
scope.
Importing from Suwayomi/Mihon
POST /api/v1/backups/import/suwayomi imports a Suwayomi-Server or
Mihon/Tachiyomi backup (.tachibk, .proto.gz — both are gzip around one
protobuf Backup message; raw proto and zip containers are sniffed too)
into the library: library manga (favorite entries), chapter read history
(read state, last page read and the history timeline; chapters present
only in history are kept), categories with membership, and tracker
bindings. The merge is additive, same as the Aidoku import.
Backups reference Mihon extension sources by id and name, not Aidoku
source keys, so every backup source group is resolved first: it
auto-matches only when exactly one installed source has the same
normalized name — multiple hits are never guessed — and the response
sources list reports each group’s state and manga count. Unmatched
groups need an explicit ?sourceMapping={"<mihonSourceId>": "<aidokuSourceKey>"} or they skip wholesale into the skipped list.
?dryRun=true previews the same transaction without writing. The web UI’s
settings page has a “从 Suwayomi 导入” button under the backup section
that walks upload → grouped preview → per-source mapping → confirm.
One caveat: a backup’s manga url is the Mihon source’s internal key,
which does not always match the corresponding Aidoku source’s manga key;
such entries import with their progress but a later source refresh may not
resolve them. Tracker bindings restore from each manga’s nested tracking
entries: the syncId maps onto a local provider (1 MAL, 2 AniList,
5 Bangumi, 11 MangaBaka — Mihon only), the remote entry id is
mediaIdInt when set (what Suwayomi-Server writes) and mediaId
otherwise, and a tracker without a local provider (Kitsu, Shikimori,
Komga, MangaUpdates, Kavita, Suwayomi, Hikka, Comick) or an entry never
synced upstream is skipped with a stated reason. The format carries
neither a track mode nor a chapter offset, so restored bindings start as
auto/0, and an existing binding for the same manga and provider always
wins. Extension settings, saved searches and server preferences are out
of scope.