106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# Lumi Updates
|
|
|
|
Lumi updates are managed from **Admin > Updates**. The page separates Core and
|
|
Plugins into expandable sections and uses repository metadata to choose a safe
|
|
target before any files are changed.
|
|
|
|
## Version Policy
|
|
|
|
Core and plugin versions use `major.minor.patch`.
|
|
|
|
- Patch: fixes only.
|
|
- Minor: non-breaking features or design changes.
|
|
- Major: potentially incompatible changes.
|
|
|
|
The UI tracks three values separately: current version, latest available
|
|
version, and safe target version. Same-major updates can target the latest
|
|
version. Major crossings are blocked unless metadata exposes a compatibility
|
|
bridge, usually `X.0.0`, or another version marked with
|
|
`migration_kind: "compatibility_bridge"` and compatible with the current
|
|
install.
|
|
|
|
If the latest version is unsafe, the UI shows the safe target as the actionable
|
|
version and lists why the absolute latest is not selected.
|
|
|
|
Updates to or from an unversioned install or target remain available so an admin
|
|
can recover directly from the repository. They are treated as manual repo
|
|
updates: the action button stays enabled, but the UI shows warnings and the
|
|
confirmation modal states that version ordering, changelog range, and rollback
|
|
safety cannot be verified from metadata.
|
|
|
|
## Metadata
|
|
|
|
The updater looks for these files on the source branch:
|
|
|
|
- `update-manifest.json` or `lumi.manifest.json`
|
|
- `CHANGELOG.md` or `changelog.json`
|
|
- `plugins/<plugin_id>/plugin.json`
|
|
- `plugins/<plugin_id>/CHANGELOG.md` or `changelog.json`
|
|
|
|
Useful metadata fields include `version`, `channel`, `compatible_from`,
|
|
`migration_kind`, `migration_notes`, `rollback_safe`, `requirements`, `size`,
|
|
and changelog entries. Missing changelog data is shown as a warning.
|
|
|
|
Stable checks read `main` by default. The newest `experimental-*` branch is used
|
|
only when explicitly selected on the updates page.
|
|
|
|
## Snapshots And Revert
|
|
|
|
Before a core, plugin, repo, or ZIP update, Lumi creates a snapshot under
|
|
`data/snapshots/` and records metadata in the snapshot index:
|
|
|
|
- target kind/id
|
|
- from/to versions
|
|
- source branch
|
|
- update method
|
|
- rollback safety
|
|
- recovery marker id
|
|
- major-crossing flag
|
|
|
|
Manual revert is available for core and individual plugins. Revert actions are
|
|
limited to the previous-version snapshot for that target. Major-version rollback
|
|
is blocked unless the snapshot or manifest explicitly marks rollback as safe.
|
|
|
|
If a repository or ZIP update fails after file replacement begins, Lumi
|
|
automatically attempts to restore the snapshot. The failed recovery marker and
|
|
backup are retained when automatic restore cannot finish, so safe mode can show
|
|
the actionable error instead of silently deleting the recovery copy.
|
|
|
|
## Preserved Local Data
|
|
|
|
Core updates, ZIP updates, plugin updates, and restores leave these local areas
|
|
in place:
|
|
|
|
- `data/`, including the database, feedback files, AI models/runtimes, tool
|
|
settings, caches, and local exports;
|
|
- plugin-owned `data/` directories;
|
|
- `knowledge/community/` and `knowledge/corrections/`;
|
|
- files under generated knowledge folders unless they explicitly declare both
|
|
`generated: true` and `editable: false`;
|
|
- local configuration, storage, uploads, logs, secrets, environment files, and
|
|
the plugin directory during core-only updates.
|
|
|
|
Full core updates remove stale replaceable code before copying the new version.
|
|
Plugin code is prepared in a staging directory and swapped only after the new
|
|
files are ready; plugin data is moved into the replacement as part of that
|
|
transaction.
|
|
|
|
## ZIP Fallback
|
|
|
|
Core and plugin ZIP updates remain available, but they are hidden under
|
|
**Manual ZIP updates**. ZIP updates create snapshots and recovery
|
|
markers. They may bypass repo metadata and compatibility checks unless the ZIP
|
|
contains valid manifest data, so use them as a manual fallback.
|
|
|
|
## Progress Events
|
|
|
|
Admin update actions publish Server-Sent Events through
|
|
`GET /admin/updates/events`. Event names include `update:checking`,
|
|
`update:metadata`, `update:snapshot`, `update:recovery_marker`,
|
|
`update:download`, `update:apply`, `update:verify`, `update:complete`,
|
|
`update:failed`, and `update:revert`.
|
|
|
|
Core update success returns a five-second in-page notice before refresh/restart.
|
|
Plugin update success updates progress for the affected plugin action without a
|
|
whole-page refresh.
|