refactor: retire the images tarball backup

Images and attachments are backed up off-site, one object per file, so the
tar+zstd of /images goes: its service and restore, both tasks, the trigger and
restore routes, the Keep last setting, the screen's Images section, and the
tests. Migration 0122 drops backup_run.tar_path and
import_settings.backup_images_keep_last_n and deletes any images runs.

The local database dump stays for an install with no off-site destination,
and the Backups card now says plainly that images and attachments are backed
up only off-site.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

backend/app/api/system_backup.py

@@ -1,5 +1,5 @@
-"""FC-3h: /api/system/backup — create/list/restore/delete/tag for
-DB + image backups.
+"""/api/system/backup: database dumps, the off-site destination and its media
+backup, restores, test restores, and the run history.
 
 Read endpoints are public on FC (operator-facing internal API; same
 posture as /api/system/activity). Write endpoints take a typed
@@ -20,13 +20,12 @@ system_backup_bp = Blueprint(
     "system_backup", __name__, url_prefix="/api/system/backup",
 )
 
-_KINDS = frozenset({"db", "images", "media", "restore", "reconcile", "test"})
+_KINDS = frozenset({"db", "media", "restore", "reconcile", "test"})
 _TAG_MAX_LEN = 64
 _BACKUP_SETTINGS_FIELDS = (
     "backup_db_nightly_enabled",
     "backup_db_nightly_hour_utc",
     "backup_db_keep_last_n",
-    "backup_images_keep_last_n",
 )
 
 
@@ -44,7 +43,6 @@ def _row_to_dict(r: BackupRun) -> dict:
             if r.finished_at and r.started_at else None
         ),
         "sql_path": r.sql_path,
-        "tar_path": r.tar_path,
         "size_bytes": r.size_bytes,
         "error": r.error,
         "restored_from_id": r.restored_from_id,
@@ -81,10 +79,6 @@ def _validate_backup_settings_patch(body: dict):
         v = body["backup_db_keep_last_n"]
         if not isinstance(v, int) or isinstance(v, bool) or not (1 <= v <= 365):
             return _bad("invalid_value", detail="backup_db_keep_last_n must be 1..365")
-    if "backup_images_keep_last_n" in body:
-        v = body["backup_images_keep_last_n"]
-        if not isinstance(v, int) or isinstance(v, bool) or not (1 <= v <= 100):
-            return _bad("invalid_value", detail="backup_images_keep_last_n must be 1..100")
     return None
 
 
@@ -99,17 +93,6 @@ async def trigger_db_backup():
     return jsonify({"status": "dispatched"}), 202
 
 
-@system_backup_bp.route("/images", methods=["POST"])
-async def trigger_images_backup():
-    body = await request.get_json(silent=True) or {}
-    tag = _validate_tag(body.get("tag"))
-    if isinstance(tag, tuple):
-        return tag
-    from ..tasks.backup import backup_images_task
-    backup_images_task.delay(tag=tag, triggered_by="manual")
-    return jsonify({"status": "dispatched"}), 202
-
-
 @system_backup_bp.route("/media", methods=["POST"])
 async def trigger_media_backup():
     """Send the images and attachments not yet in the off-site bucket. Refused
@@ -348,17 +331,17 @@ async def trigger_restore(run_id: int):
         row = await session.get(BackupRun, run_id)
         if row is None:
             return _bad("not_found", status=404)
-        if row.status != "ok":
-            return _bad(
-                "not_restorable",
-                detail=f"source backup status={row.status!r}; only 'ok' rows are restorable",
-            )
         if (row.manifest or {}).get("offsite"):
             return _bad(
                 "not_restorable",
                 detail=("this dump is kept in the off-site bucket, not on this server, "
                         "so it can't be restored from here"),
             )
+        if row.kind != "db" or row.status != "ok" or not row.sql_path:
+            return _bad(
+                "not_restorable",
+                detail="only a finished database dump kept on this server can be restored here",
+            )
         expected = f"restore-{row.kind}-{row.id}"
         if supplied != expected:
             return _bad(
@@ -366,15 +349,10 @@ async def trigger_restore(run_id: int):
                 detail=f"confirm must equal {expected!r}",
                 expected=expected,
             )
-        kind = row.kind
 
-    if kind == "db":
-        from ..tasks.backup import restore_db_task
-        restore_db_task.delay(source_backup_run_id=run_id)
-    else:  # 'images' (the only other value _KINDS allows via the trigger path)
-        from ..tasks.backup import restore_images_task
-        restore_images_task.delay(source_backup_run_id=run_id)
-    return jsonify({"status": "dispatched", "kind": kind}), 202
+    from ..tasks.backup import restore_db_task
+    restore_db_task.delay(source_backup_run_id=run_id)
+    return jsonify({"status": "dispatched", "kind": "db"}), 202
 
 
 @system_backup_bp.route("/runs/<int:run_id>/test", methods=["POST"])
@@ -414,7 +392,7 @@ async def delete_run(run_id: int):
             )
         from ..services import backup_service
         backup_service.unlink_artifact_files(
-            sql_path=row.sql_path, tar_path=row.tar_path,
+            sql_path=row.sql_path,
             manifest_path=(row.manifest or {}).get("manifest_path"),
         )
         await session.delete(row)
@@ -430,7 +408,6 @@ async def get_settings():
         "backup_db_nightly_enabled": row.backup_db_nightly_enabled,
         "backup_db_nightly_hour_utc": row.backup_db_nightly_hour_utc,
         "backup_db_keep_last_n": row.backup_db_keep_last_n,
-        "backup_images_keep_last_n": row.backup_images_keep_last_n,
     })
 
 

backend/app/models/backup_run.py

@@ -1,7 +1,8 @@
 """FC-3h: backup_run — operator-facing artifact record for a backup run.
 
-One row per backup attempt (kind='db', 'images', or 'media' for the off-site
-upload of images and attachments, which spans many task chunks). Lifecycle
+One row per run: kind 'db' (a database dump), 'media' (the off-site upload of
+images and attachments, which spans many task chunks), 'restore', 'reconcile'
+(the weekly bucket check) or 'test' (a test restore). Lifecycle
 tracking (started_at/finished_at/duration_ms/exception text) lives
 in task_run from FC-3i — this row records artifact metadata: file
 paths, sizes, tag (retention protection), and restore lineage via
@@ -55,7 +56,6 @@ class BackupRun(Base):
         DateTime(timezone=True), nullable=True, index=True,
     )
     sql_path: Mapped[str | None] = mapped_column(Text, nullable=True)
-    tar_path: Mapped[str | None] = mapped_column(Text, nullable=True)
     size_bytes: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
     error: Mapped[str | None] = mapped_column(Text, nullable=True)
     manifest: Mapped[dict] = mapped_column(

backend/app/models/import_settings.py

@@ -97,10 +97,6 @@ class ImportSettings(Base):
         Integer, nullable=False, default=14,
         server_default="14",
     )
-    backup_images_keep_last_n: Mapped[int] = mapped_column(
-        Integer, nullable=False, default=3,
-        server_default="3",
-    )
     # Off-site backup destination: an S3 bucket (services/backup_destination).
     # The secret key is stored sealed with the credential key, never in clear.
     backup_s3_endpoint: Mapped[str | None] = mapped_column(Text, nullable=True)

backend/app/services/backup_service.py

@@ -1,14 +1,11 @@
 """FC-3h: first-class backup/restore service for FC.
 
-Two independent backup kinds:
-  - 'db'     — pg_dump only; fast; nightly via Beat (settings-gated)
-  - 'images' — tar+zstd of /images; slow; manual trigger only
-
-With an off-site destination set up, a database dump streams straight to that
-bucket instead (backup_db_offsite). Otherwise files live under
-<images_root>/_backups/. Each local backup writes:
-  fc_<kind>_<ts>.{sql|tar.zst}        — the artifact
-  fc_<kind>_<ts>.json                 — manifest (kind/tag/triggered_by)
+The database dump (pg_dump), nightly via Beat when the setting is on. With an
+off-site destination set up, the dump streams straight to that bucket
+(backup_db_offsite), and images and attachments go there too (backup_media).
+Without one, the dump is written under <images_root>/_backups/:
+  fc_db_<ts>.dump                     — the dump (custom format)
+  fc_db_<ts>.json                     — manifest (tag, trigger, row counts)
 
 Service functions are sync (subprocess-bound). Celery tasks in
 backend.app.tasks.backup wrap each one with task_run-tracked
@@ -31,25 +28,6 @@ log = logging.getLogger(__name__)
 
 _BACKUPS_DIRNAME = "_backups"
 
-# Excluded from the images tarball, and each for its own reason (#4233, #4234):
-#
-#   _backups    — the archive would otherwise contain every previous archive.
-#                 This is not hypothetical: the 2026-05-23/24 runs, taken before
-#                 this exclude existed, grew 43G -> 107G -> ... -> 2123G as each
-#                 swallowed its predecessors, and cost 4.3T of the images
-#                 filesystem until they were reclaimed on 2026-09-21.
-#   _quarantine — holds files deliberately pulled OUT of the library.
-#   secrets     — `credential_key.b64`, the key that decrypts the stored
-#                 Patreon/SubscribeStar session credentials.
-#   cookies     — those session cookies themselves.
-#
-# The last two are the ones worth stating plainly: an images tarball is a media
-# archive, and a media archive that carries the key to the operator's accounts
-# is a credential leak wearing a backup's name. Encryption at rest buys nothing
-# when the key rides along in the same file. A restore therefore does NOT
-# re-establish credentials — you sign in again, which is the correct outcome.
-_IMAGES_EXCLUDED_DIRNAMES = ("_backups", "_quarantine", "secrets", "cookies")
-
 # Subprocess-level guardrails BEYOND the Celery soft_time_limit. The Celery
 # soft limit signals the Python process; subprocess.Popen in a blocking syscall
 # ignores that signal, so these bound the worst case directly. Each sits just
@@ -58,9 +36,7 @@ _IMAGES_EXCLUDED_DIRNAMES = ("_backups", "_quarantine", "secrets", "cookies")
 # matters because an NFS D-state hang defeats even Celery's SIGKILL (the failure
 # that wedged the maintenance lane for hours, #739).
 #   backup_db_task:     soft=1800s / hard=2100s  → 1700s
-#   backup_images_task: soft=21600s / hard=23400s → 21000s
 _DB_SUBPROCESS_TIMEOUT_S = 1700            # ~28 min, under the 30-min DB soft limit
-_IMAGES_SUBPROCESS_TIMEOUT_S = 21000       # ~5.8 hr, under the 6-hr images soft limit
 # Grace after SIGKILL to reap the child. If it can't be reaped in this window
 # (an uninterruptible NFS D-state — the failure mode that wedged the
 # concurrency-1 maintenance lane for hours, operator-flagged 2026-06-07), we
@@ -259,7 +235,6 @@ def backup_db(
         "kind": "db",
         "ts": ts,
         "sql_path": str(sql_path),
-        "tar_path": None,
         "manifest_path": str(manifest_path),
         "size_bytes": _file_size_or_none(sql_path),
         "counts": counts,
@@ -348,42 +323,6 @@ def _stream_dump(db_url: str, target, ts: str, limit_mbps: int | None, snapshot:
     }
 
 
-def backup_images(
-    *, images_root: Path,
-    tag: str | None = None, triggered_by: str = "manual",
-) -> dict:
-    """Run tar --zstd over images_root; write .tar.zst + manifest."""
-    ts = _now_ts()
-    out_dir = _backups_dir(images_root)
-    tar_path = out_dir / f"fc_images_{ts}.tar.zst"
-    # No local-temp here (the archive is hundreds of GB — it can't stage in
-    # /tmp), but bounded-kill still applies so a tar wedged on NFS fails fast
-    # rather than holding the lane for hours.
-    _run_bounded(
-        [
-            "tar", "--zstd", "-cf", str(tar_path),
-            "-C", str(images_root.parent), images_root.name,
-            *(
-                f"--exclude={images_root.name}/{name}"
-                for name in _IMAGES_EXCLUDED_DIRNAMES
-            ),
-        ],
-        _IMAGES_SUBPROCESS_TIMEOUT_S,
-    )
-    manifest_path = _write_manifest(
-        out_dir, kind="images", ts=ts, tag=tag, triggered_by=triggered_by,
-        artifact_path=tar_path,
-    )
-    return {
-        "kind": "images",
-        "ts": ts,
-        "sql_path": None,
-        "tar_path": str(tar_path),
-        "manifest_path": str(manifest_path),
-        "size_bytes": _file_size_or_none(tar_path),
-    }
-
-
 class RestoreFailed(Exception):
     """psql or pg_restore exited with an error; the message is its last line."""
 
@@ -483,24 +422,9 @@ def restore_db(*, db_url: str, sql_path: Path) -> None:
                             else f"pg_restore exited with {proc.returncode}")
 
 
-def restore_images(*, images_root: Path, tar_path: Path) -> None:
-    """Untar over images_root.parent. Additive — files NOT in the
-    tarball are NOT removed. Caller wipes first if a clean restore
-    is needed."""
-    subprocess.run(
-        [
-            "tar", "--zstd", "-xf", str(tar_path),
-            "-C", str(images_root.parent),
-        ],
-        capture_output=True, check=True,
-        timeout=_IMAGES_SUBPROCESS_TIMEOUT_S,
-    )
-
-
 def unlink_artifact_files(
     *,
     sql_path: str | None,
-    tar_path: str | None,
     manifest_path: str | None,
 ) -> dict:
     """Best-effort unlink of all on-disk files for a BackupRun row.
@@ -509,7 +433,6 @@ def unlink_artifact_files(
     deleted: dict = {}
     for label, p in (
         ("sql", sql_path),
-        ("tar", tar_path),
         ("manifest", manifest_path),
     ):
         if not p:

backend/app/tasks/backup.py

@@ -125,55 +125,6 @@ def backup_db_task(self, *, tag: str | None = None,
     return {"backup_run_id": run_id}
 
 
-@celery.task(
-    name="backend.app.tasks.backup.backup_images_task",
-    bind=True,
-    autoretry_for=(OperationalError, DBAPIError),
-    retry_backoff=30, retry_backoff_max=300, max_retries=1,
-    soft_time_limit=21600, time_limit=23400,
-)
-def backup_images_task(self, *, tag: str | None = None,
-                       triggered_by: str = "manual") -> dict:
-    """Create one images backup. Same shape as backup_db_task; uses
-    tar_path instead of sql_path."""
-    SessionLocal = _sync_session_factory()
-    now = datetime.now(UTC)
-    with SessionLocal() as session:
-        row = BackupRun(
-            kind="images", status="running", tag=tag,
-            triggered_by=triggered_by, started_at=now, manifest={},
-        )
-        session.add(row)
-        session.commit()
-        session.refresh(row)
-        run_id = row.id
-
-    try:
-        result = backup_service.backup_images(
-            images_root=IMAGES_ROOT,
-            tag=tag, triggered_by=triggered_by,
-        )
-    except (SoftTimeLimitExceeded, Exception) as exc:
-        with SessionLocal() as session:
-            row = session.get(BackupRun, run_id)
-            if row is not None:
-                _mark_failed(session, row, exc)
-        raise
-
-    with SessionLocal() as session:
-        row = session.get(BackupRun, run_id)
-        row.status = "ok"
-        row.finished_at = datetime.now(UTC)
-        row.tar_path = result["tar_path"]
-        row.size_bytes = result["size_bytes"]
-        row.manifest = {
-            "manifest_path": result["manifest_path"],
-            "ts": result["ts"],
-        }
-        session.commit()
-    return {"backup_run_id": run_id}
-
-
 @celery.task(
     name="backend.app.tasks.backup.restore_db_task",
     bind=True,
@@ -225,52 +176,6 @@ def restore_db_task(self, *, source_backup_run_id: int) -> dict:
     return {"backup_run_id": marker_id}
 
 
-@celery.task(
-    name="backend.app.tasks.backup.restore_images_task",
-    bind=True, max_retries=0,
-    soft_time_limit=21600, time_limit=23400,
-)
-def restore_images_task(self, *, source_backup_run_id: int) -> dict:
-    """Mirrors restore_db_task; uses backup_service.restore_images."""
-    SessionLocal = _sync_session_factory()
-    now = datetime.now(UTC)
-    with SessionLocal() as session:
-        src = session.get(BackupRun, source_backup_run_id)
-        if src is None or src.kind != "images" or not src.tar_path:
-            raise ValueError(
-                f"BackupRun id={source_backup_run_id} is not a valid images backup"
-            )
-        marker = BackupRun(
-            kind="images", status="restoring",
-            triggered_by="restore", started_at=now,
-            restored_from_id=src.id,
-            manifest={"source_tar_path": src.tar_path},
-        )
-        session.add(marker)
-        session.commit()
-        session.refresh(marker)
-        marker_id = marker.id
-        tar_path = src.tar_path
-
-    try:
-        backup_service.restore_images(
-            images_root=IMAGES_ROOT, tar_path=Path(tar_path),
-        )
-    except (SoftTimeLimitExceeded, Exception) as exc:
-        with SessionLocal() as session:
-            row = session.get(BackupRun, marker_id)
-            if row is not None:
-                _mark_failed(session, row, exc)
-        raise
-
-    with SessionLocal() as session:
-        row = session.get(BackupRun, marker_id)
-        row.status = "restored"
-        row.finished_at = datetime.now(UTC)
-        session.commit()
-    return {"backup_run_id": marker_id}
-
-
 @celery.task(
     name="backend.app.tasks.backup.prune_backups",
     soft_time_limit=300, time_limit=600,
@@ -278,27 +183,23 @@ def restore_images_task(self, *, source_backup_run_id: int) -> dict:
 def prune_backups() -> dict:
     """Daily Beat. Per-kind retention from ImportSettings.
 
-    Returns {"db_deleted": N, "images_deleted": M, "media_deleted": L,
-    "restore_deleted": R, "reconcile_deleted": C, "test_deleted": T,
+    Returns {"db_deleted": N, "media_deleted": L, "restore_deleted": R, "reconcile_deleted": C, "test_deleted": T,
     "files_unlinked": K}. Media, restore, reconcile and test runs leave no
     files here; only their history is trimmed, to the latest MEDIA_RUNS_KEPT,
     RESTORE_RUNS_KEPT, RECONCILE_RUNS_KEPT and TEST_RUNS_KEPT.
     Tagged rows (tag IS NOT NULL) are never pruned.
     Status='running' / 'restoring' rows are never pruned — the
     recover_stalled_backup_runs sweep flips truly-stuck ones to
-    'error' first. (Earlier docstring claimed the FC-3i TaskRun sweep
-    handled those, but TaskRun cleanup never touched BackupRun rows.
-    Audit 2026-06-02 added the dedicated sweep.)
+    'error' first.
     """
     SessionLocal = _sync_session_factory()
-    counts = {"db_deleted": 0, "images_deleted": 0, "media_deleted": 0,
+    counts = {"db_deleted": 0, "media_deleted": 0,
               "restore_deleted": 0, "reconcile_deleted": 0, "test_deleted": 0,
               "files_unlinked": 0}
     with SessionLocal() as session:
         s = ImportSettings.load_sync(session)
         for kind, keep in (
             ("db", s.backup_db_keep_last_n),
-            ("images", s.backup_images_keep_last_n),
             ("media", MEDIA_RUNS_KEPT),
             ("restore", RESTORE_RUNS_KEPT),
             ("reconcile", RECONCILE_RUNS_KEPT),
@@ -315,7 +216,6 @@ def prune_backups() -> dict:
             for row in candidates:
                 result = backup_service.unlink_artifact_files(
                     sql_path=row.sql_path,
-                    tar_path=row.tar_path,
                     manifest_path=(row.manifest or {}).get("manifest_path"),
                 )
                 counts["files_unlinked"] += sum(

backend/app/tasks/maintenance.py

@@ -168,11 +168,6 @@ QUEUE_STUCK_THRESHOLD_MINUTES: dict[str, int] = {
 }
 TASK_STUCK_THRESHOLD_MINUTES: dict[str, int] = {
     "backend.app.tasks.import_file.import_archive_file": 40,
-    # Backup images runs hours, not minutes (6.5h hard limit). The
-    # task-name override beats the queue's 75-min default so a
-    # legitimately-running backup isn't flagged.
-    "backend.app.tasks.backup.backup_images_task": 420,
-    "backend.app.tasks.backup.restore_images_task": 420,
     # One media-backup chunk stops starting files after 45 min but may finish
     # a large file in flight, up to its 6.5 h hard limit.
     "backend.app.tasks.backup.backup_media_task": 420,
@@ -849,7 +844,8 @@ def recover_stalled_backup_runs() -> int:
         result = session.execute(
             update(BackupRun)
             .where(BackupRun.status.in_(["running", "restoring"]))
-            # db backups/restores are fast (40-min window); images run hours (7h).
+            # db backups/restores are fast (40-min window); a test restore and the
+            # weekly bucket check get 7 h.
             # A media run or an off-site restore spans many chunks and hours on
             # purpose, so its window runs from its last progress, not its start.
             .where(