Backup & restore

What to back upCopy Anchor Link

Objects in channels are named by content hash; which image belongs to which short link, user and token lives only in the metadata database. Lose the metadata database and the images in your channels can no longer be matched up. Lose the master key and the instance refuses to start, and channel credentials and encrypted channel data can no longer be decrypted.

<data dir>/variants/ is the variant cache; it is regenerated on demand and needs no backup. Do not copy imgyoung.db while the service is running: the database runs in WAL mode and recent writes may still be in imgyoung.db-wal. For a consistent copy, download a snapshot from the admin console, or stop the service first.

Automatic metadata snapshotsCopy Anchor Link

• How: each round, SQLite's VACUUM INTO writes one consistent snapshot to <data dir>/backup-snapshot.tmp (needs free space of roughly the database size), which is deleted once it has been written to the channels.
• Where: the same snapshot is written to every healthy channel that is not being deleted, under the object key _imgyoung/backup/imgyoung-<UTC time>.db (e.g. imgyoung-20261015-083000.123.db) in the channel's path; on the built-in local channel that is <data dir>/blobs/_imgyoung/backup/.
• Encryption: snapshots written to an encrypted channel are encrypted along with everything else on it.
• When: every Backup interval (backup_interval_hours, 24 hours by default), counted from process start; changing the interval restarts the countdown from the moment of the change. Scheduled backups and Back up now run one at a time; if both happen at once, one waits for the other.
• At startup: if any healthy channel lacks a snapshot from within the last interval, a backup runs immediately; otherwise it is skipped. The first start after adding a channel therefore fills it in, and frequent restarts do not push the rotated history out with same-day snapshots.
• Retention: after a successful write, each channel keeps only its own newest Backups to keep (backup_keep, 7 by default) snapshots; older ones are deleted.
• Failure: a channel that fails does not stop the others from being written, but if any channel was not written the round counts as failed and opens a backup_failed alert; the channels that were written keep the snapshot. No healthy channel, or failing to take the snapshot, also counts as failure. The alert resolves after the next success; see Monitoring & alerts.
• When a channel is deleted: Delete and purge deletes the snapshots on the channel too; Remove only leaves every remote object, snapshots included, where it is.

Managing snapshots in the admin consoleCopy Anchor Link

Settings → Backups & export → Metadata snapshots lists the union of the snapshots on all healthy channels, newest first; Stored on lists the channels holding each snapshot, in priority order.

• Back up now: take a snapshot immediately and write it to every healthy channel, pruning each channel beyond the retention count. If some channels were not written, the request fails with an error naming them and why, like 备份失败:快照 imgyoung-20261016-083000.123.db 有 1/3 个渠道未写成: 渠道 "r2-main": 上传快照: …; the channels that were written keep the snapshot. With no healthy channel it returns 没有健康渠道可存放快照.
• Download: reads the snapshot from the healthy channels holding it in priority order, moving on to the next one if a read fails. The downloaded file is a complete SQLite database.
• Restore: reads the same way; see the next section.

Snapshots on unhealthy channels or channels being deleted are not listed and are not used for downloads or restores. If listing any healthy channel fails, the whole list fails (500). With no healthy channel every action returns 503: 没有健康渠道,无法列举快照 for the list, 没有健康渠道,无法读取快照 for downloads and restores, and 没有健康渠道可存放快照 for Back up now. If no healthy channel has the requested snapshot, downloads and restores return 404 快照不存在; if some channels fail to read it and none succeeds, they return 500.

Restoring from a snapshotCopy Anchor Link

A live SQLite file cannot be replaced safely, so a restore happens in two steps: stage the snapshot, then swap it in on the next start, before the database is opened.

The kept imgyoung.db.pre-restore-* files are never deleted automatically; remove them once you are satisfied with the restore.

A restore takes the metadata back to snapshot time, so anything that happened afterwards no longer matches the objects in your channels:

• images uploaded after the snapshot are unknown to the metadata. Their objects predate the reset binding times, so reconciliation GC only counts them (foreign) and never deletes them; they stay on the channels but can no longer be reached through ImgYoung;
• images deleted after the snapshot are back in the metadata, but their objects are gone; they fail to load and show up as Replication failed alerts, so delete them in the admin console;
• everything else — channels, users and tokens created, runtime settings and hotlink rules changed — goes back to snapshot time.

Disaster recovery after losing the hostCopy Anchor Link

Prerequisites: a backup of the master.key of the instance the snapshot came from, and a snapshot file from one of these:

• a snapshot you downloaded;
• any unencrypted channel: use the provider's console or rclone to download the newest imgyoung-*.db under _imgyoung/backup/ in the channel's path;
• an encrypted channel: read it through the crypt remote of the rclone config file you exported beforehand; see Channel encryption.

mkdir -p data
cp imgyoung-master.key data/master.key && chmod 600 data/master.key
cp imgyoung-20261015-083000.123.db data/imgyoung.db.restore

Images that existed only on the local channel are gone with the old host. Images with replicas on other channels load as usual, and the missing local replicas are detected by reconciliation GC and copied back from the other channels.

If a snapshot is on an unencrypted channel, you can also skip fetching the file by hand: start a fresh instance, add the channel holding the snapshots in the admin console with its original parameters, and restore from Metadata snapshots; the list covers every healthy channel, so no priority changes are needed. The fresh instance must use the original master key from its very first start (put master.key in place or set IMGYOUNG_MASTER_KEY beforehand); otherwise, when it restarts after the restore, the key does not match the snapshot and the process refuses to start. If it has already started with a generated key, stop it, put the original master.key in place, delete the fresh imgyoung.db (and its -wal and -shm) from the data directory, start it again, and only then add the channel. A newly added channel is bound at the moment it is added, and every object already in the bucket predates that, so reconciliation GC only counts those objects and never deletes them; nothing is lost while you wait.

Metadata exportCopy Anchor Link

Settings → Backups & export → Data export → Export JSON downloads imgyoung-export.json (each export writes a data.export audit entry). Contents:

The export is readable and self-contained: even without running ImgYoung you can use it to match the objects in your channels back to images. It is not a restore format; restores use snapshots. Runtime settings, hotlink rules, audit logs and alerts are not included.

Reconciliation GCCopy Anchor Link

Every 24 hours (the first run 24 hours after process start), the replication subsystem reconciles each healthy channel in both directions. System objects under the _imgyoung/ prefix (including snapshots) are left alone.

Orphan detection is bounded by the channel's binding time: the moment the channel record started pointing at its current storage location. ImgYoung only writes objects to that location after it.

• Orphans are deleted, so pay-per-use channels do not bill you for ownerless objects. An object is an orphan only if all of the following hold:
  • its key has ImgYoung's object key format <short ID>_<first 8 hex digits of SHA-256>;
  • the metadata database has no replica record of it on that channel, in any state;
  • it was last modified no earlier than the channel's binding time;
  • it was last modified more than 48 hours ago; the grace period covers the normal window between writing to a channel and recording it in the database.
• Deep check leftovers: the deep health check writes a temporary .imgyoung-probe-* object and deletes it right away; one is left behind only when that deletion fails. They are deleted once past the 48-hour grace period regardless of when they were written (leftovers from a connection test predate the channel record), and are not counted in the object count or usage.
• Foreign objects have no record in the database but either a key in another format or a modification time before the binding time — files written to the same path by other programs, the objects already in an old bucket attached by a fresh instance during disaster recovery, or objects written after a snapshot that was later restored. They are counted, never deleted.
• Phantoms: replicas the metadata database records as completed but that are missing from the channel. They are reset to pending and queued to be copied from another channel.

Each channel's reconciliation logs a 渠道对账完成 line with the fields objects (object count), bytes, foreign (foreign objects), orphans_deleted (deep check leftovers included) and phantoms_requeued.

Separately, replica reconciliation runs every 10 minutes (without listing channel objects): failed replicas on channels that are healthy again are reset to pending, and unfinished replicas are queued again.