2.0 KiB
Lumi Recovery Mode
Failed updates should leave an administrator with a recovery path. Lumi writes a recovery marker before update files are applied and keeps snapshots available for manual revert. If an update throws after replacement begins, Lumi first attempts to restore the new snapshot automatically. Failed automatic restoration keeps the backup and records both errors for safe-mode recovery.
Recovery Marker
The marker lives at data/recovery/update-marker.json and records:
- target kind and id
- from/to versions
- source branch
- update method
- rollback safety
- snapshot id when available
- status and timestamps
Statuses include pending, applying, verifying, completed, failed, and
stale. A completed marker is cleared after a successful normal startup. If
Lumi starts and finds an incomplete marker, it marks it stale so the admin UI and
safe-mode UI can show the last attempted update.
Manual Safe Mode
Safe mode can be started with any of these triggers:
LUMI_SAFE_MODE=1 npm run run
node run.js --safe-mode
Creating data/recovery/safe-mode.flag also makes the wrapper start
safe-mode.js instead of the full bot. Safe mode loads only the minimum services
needed for recovery: config/database, auth/session, static recovery UI,
snapshots/revert, plugin disable, and restart controls. Optional plugins,
platform clients, AI runtime, scheduled jobs, and non-essential integrations are
not loaded.
Admin Recovery UI
The normal Admin > Updates page shows a recovery banner when a marker is present. The standalone safe-mode page shows the last attempted target, versions, method, source branch, snapshot id, timestamp, and error.
Admins can:
- revert a safe snapshot,
- disable a problematic plugin,
- clear a stale marker after verifying startup,
- retry normal startup.
Manual major-version rollback remains blocked unless the snapshot is explicitly marked rollback safe. The automatic rollback attempted for the same failed update is allowed because it restores the immediately preceding state.