Skip to content

Backup & Import

Versioned JSON backup, scheduled backups, and imports from Aidoku and Suwayomi/Mihon.

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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close