feat(storage): improve admin panel

example.env

@@ -353,8 +353,73 @@ DATABASE_URL=postgres://postgres:postgres@localhost:5432/oxicloud
 #OXICLOUD_PLUGIN_LOG_QUEUE_CAPACITY=1024
 
 # -----------------------------------------------------------------------------
-# STORAGE BACKEND
+# STORAGE ENTRIES (multi-entry, recommended)
 # -----------------------------------------------------------------------------
+#
+# Declare one or more NAMED storage backends. The one the app runs on is
+# picked from the DB (`admin_settings.storage.active_backend_name`) — the
+# admin panel's storage tab flips it, and cross-backend migration is a
+# recoverable-run job that copies blobs between two entries. See
+# `docs/plan/storage-multi-entry.md` for the full model.
+#
+# Rules:
+#   * `OXICLOUD_STORAGE_ENTRIES` is a comma-separated allowlist of names.
+#     Names must match `[a-z0-9_-]{1,32}` and be unique. Order is
+#     preserved (the first entry is the fallback when no active pointer
+#     is set in the DB yet — e.g. fresh install).
+#   * For each name `N`, the parser reads
+#     `OXICLOUD_STORAGE_<N>_BACKEND` (local | s3 | azure) plus the
+#     backend-specific fields below. A missing required field aborts
+#     boot with the exact var name in the error message.
+#   * Presence of `OXICLOUD_STORAGE_<N>_ENCRYPTION_KEY` implies AES-256
+#     encryption is enabled on that entry (no separate enable flag).
+#     Bad base64 / wrong length aborts boot with the entry name.
+#   * SETTING `_ENTRIES` alongside the legacy flat vars below (e.g.
+#     `OXICLOUD_STORAGE_BACKEND` + `OXICLOUD_S3_BUCKET`) is a FAIL-FAST
+#     boot error — pick one mode. Migrate any leftover flat vars into
+#     per-entry `_STORAGE_<NAME>_*` form.
+#
+# Example: local disk today, S3 target for a planned migration.
+#
+#OXICLOUD_STORAGE_ENTRIES=local_main,s3_prod
+#
+#OXICLOUD_STORAGE_local_main_BACKEND=local
+#OXICLOUD_STORAGE_local_main_ROOT_DIR=/srv/oxicloud
+#
+#OXICLOUD_STORAGE_s3_prod_BACKEND=s3
+#OXICLOUD_STORAGE_s3_prod_S3_BUCKET=my-oxicloud-bucket
+#OXICLOUD_STORAGE_s3_prod_S3_REGION=us-east-1
+#OXICLOUD_STORAGE_s3_prod_S3_ENDPOINT_URL=https://s3.example.com
+#OXICLOUD_STORAGE_s3_prod_S3_ACCESS_KEY=
+#OXICLOUD_STORAGE_s3_prod_S3_SECRET_KEY=
+#OXICLOUD_STORAGE_s3_prod_S3_FORCE_PATH_STYLE=false
+#OXICLOUD_STORAGE_s3_prod_ENCRYPTION_KEY=  # generate: openssl rand -base64 32
+# Cipher declaration — future-proofing. Today only `aes-256-gcm` is
+# accepted (and it's the default when `_ENCRYPTION_KEY` is set), so
+# this line can be omitted. Explicit here as documentation.
+#OXICLOUD_STORAGE_s3_prod_ENCRYPTION_CIPHER=aes-256-gcm
+#
+# Repair flag: if you rename an entry in .env while the DB still points
+# at the old name, boot aborts with an actionable error pointing at:
+#
+#   oxicloud --select-storage <name>
+#
+# which verifies the entry exists in `_ENTRIES` and updates the DB
+# pointer without booting the server. See §Fallback in the plan doc.
+
+# -----------------------------------------------------------------------------
+# STORAGE BACKEND — DEPRECATED (single-backend flat vars)
+# -----------------------------------------------------------------------------
+#
+# ⚠️ DEPRECATED. Use the STORAGE ENTRIES section above for new deployments.
+# These flat variables still work when `OXICLOUD_STORAGE_ENTRIES` is UNSET —
+# the parser then synthesises a single entry named `default` from them AND
+# emits a boot-time deprecation warning
+# (`storage.legacy_flat_vars_deprecated`) so operators see it in logs.
+# Removal target: not yet fixed. Migrate at your convenience by moving
+# each `OXICLOUD_STORAGE_BACKEND` / `OXICLOUD_S3_*` / `OXICLOUD_AZURE_*` /
+# `OXICLOUD_STORAGE_ENCRYPTION_*` into `OXICLOUD_STORAGE_<NAME>_*` under
+# an entry declared in `OXICLOUD_STORAGE_ENTRIES`.
 
 # Blob storage backend: local (default), s3, or azure
 #OXICLOUD_STORAGE_BACKEND=local
@@ -400,9 +465,15 @@ DATABASE_URL=postgres://postgres:postgres@localhost:5432/oxicloud
 # Cache directory (default: {STORAGE_PATH}/.blob-cache)
 #OXICLOUD_STORAGE_CACHE_PATH=
 
-# --- Client-Side Encryption ---
+# --- Client-Side Encryption --- DEPRECATED (per-entry key is the new home)
 # AES-256-GCM encryption applied to blobs before writing to any backend.
 # WARNING: losing the key means losing all data. Back it up securely.
+#
+# ⚠️ DEPRECATED. Prefer per-entry `OXICLOUD_STORAGE_<NAME>_ENCRYPTION_KEY`
+# under an entry declared in `OXICLOUD_STORAGE_ENTRIES` (see the top
+# multi-entry section). The flat vars below still work in
+# zero-entries mode and get folded into the synthesised `default`
+# entry, alongside a deprecation warning at boot.
 
 # Enable at-rest blob encryption (default: false)
 #OXICLOUD_STORAGE_ENCRYPTION_ENABLED=false