Upgrades

The current application reference is:

lobehub/lobehub:2.2.15@sha256:9186fbb2a1cd593eada518560695e1f14f0fa570ed987ba1bf1b3008456422ca

Every upgrade replaces that complete reference with a newly verified tag and manifest digest. Never leave a tag without @sha256: and never silently select a different release.

Required sequence

1. Record the current application reference as the rollback image.
2. Take both authoritative backups using backups-restore:
   • PostgreSQL custom-format dump
   • RustFS bucket mirror under the same timestamp
3. Verify the dump with pg_restore --list and inspect the mirrored object tree.
4. Edit only the Lobe image reference in docker-compose.yml to the approved new tag and digest.
5. Validate without rendering interpolation:

cd ~/dev/lobe
sudo -n docker compose config --quiet

6. Reconcile the stack:

sudo -n docker compose up -d
sudo -n docker compose ps -a

7. Wait for PostgreSQL, Redis, RustFS, and Lobe health and confirm rustfs-init exits 0.
8. Run every check in verification, including OIDC, the exact LiteLLM model set, unlisted-model rejection, streaming, and object access.
9. Retain the prior application reference and the matched pre-upgrade backup pair until rollback is no longer required.

Migration behavior

LobeHub performs its database migration during application startup. docker compose up -d is therefore both an image rollout and a potential schema transition. A healthy container alone does not prove that auth, models, streaming, or object persistence remain correct.

Rollback decision

• application-only rollback:
  • restore the prior complete image reference in docker-compose.yml
  • validate with sudo -n docker compose config --quiet
  • run sudo -n docker compose up -d
  • repeat verification
• database rollback:
  • required when the new application migrated data incompatibly with the prior image
  • restore the matched pre-upgrade custom-format dump as documented in backups-restore
  • restore the paired RustFS mirror if object state changed
• never:
  • delete PostgreSQL or RustFS volumes to force a rollback
  • combine an old application image with an unmatched database dump
  • call volume existence a backup
  • replace the scoped LiteLLM key with the gateway master key to bypass a post-upgrade model error

Upgrade evidence

A complete upgrade record consists of:

• old and new full application references
• paired backup timestamp
• successful pg_restore --list
• inspected RustFS mirror tree
• successful quiet Compose validation
• healthy status shape and rustfs-init exit 0
• OIDC login result
• exact model aliases fast, oss-120b, free
• 403 for an unlisted model
• successful streamed response and persisted attachment
• certificate and public-route checks