diff --git a/README.md b/README.md
index b0dea751..ceebd858 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,55 @@
 - **Tests and CI are real.** GitHub Actions run backend tests, frontend typecheck/build, and the
   desktop matrix (Windows/macOS/Linux) on every PR.
 
+## Migrating from upstream Cloudreve
+
+This fork is a drop-in replacement: same 4.19.x schema baseline, same `/cloudreve/data` volume
+layout, same `CR_CONF_*` env vars, same port 5212. Existing accounts, files, shares, and settings
+carry over — schema migrations run automatically on first boot. Back up your data volume and
+database first, as with any upgrade.
+
+**Docker Compose** — one command (backs up your compose file, swaps the image, restarts):
+
+```bash
+curl -sSL https://raw.githubusercontent.com/Dvorinka/cloudreve/master/migrate.sh | sh -s -- /path/to/compose/dir
+```
+
+Or edit `docker-compose.yml` by hand — only the image changes, everything else stays identical to
+the [upstream compose setup](https://github.com/cloudreve/docker-compose):
+
+```diff
+ services:
+   cloudreve:
+-    image: cloudreve/cloudreve:v4
++    image: ghcr.io/dvorinka/cloudreve:latest
+```
+
+```bash
+docker compose pull && docker compose up -d
+```
+
+**Plain docker** — same flags, new image:
+
+```bash
+docker stop cloudreve && docker rm cloudreve
+docker run -d --name cloudreve --restart unless-stopped \
+  -p 5212:5212 -v backend_data:/cloudreve/data \
+  ghcr.io/dvorinka/cloudreve:latest
+```
+
+**Binary** — stop the service, drop in the binary from
+[Releases](https://github.com/Dvorinka/cloudreve/releases), start. Your `data/` directory
+(SQLite, uploads, `conf.ini`) is untouched.
+
+Notes:
+
+- Tags: `latest` / `slim` track the newest release; pin `ghcr.io/dvorinka/cloudreve:v4.19.2` for
+  reproducibility. Slim drops aria2, LibreOffice, ffmpeg, and font/media tooling.
+- `CR_LICENSE_KEY` has no effect — Pro-class features are reimplemented as free features; the key
+  is simply ignored.
+- Migration is supported from upstream ≤ 4.19.x. If you run a newer upstream than our latest
+  release, wait for the next tag rather than downgrading the schema.
+
 ## Repository layout
 
 ```
diff --git a/docker-compose.yml b/docker-compose.yml
index d9f7f73d..ae936ee8 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,6 +1,6 @@
 services:
   cloudreve:
-    image: cloudreve/cloudreve:latest
+    image: ghcr.io/dvorinka/cloudreve:latest
     container_name: cloudreve-backend
     depends_on:
       - postgresql
diff --git a/migrate.sh b/migrate.sh
new file mode 100755
index 00000000..7d1fdb8a
--- /dev/null
+++ b/migrate.sh
@@ -0,0 +1,39 @@
+#!/bin/sh
+# migrate.sh — switch an existing upstream Cloudreve docker-compose deployment
+# to this fork. All data (volumes, database, env config) is preserved; only the
+# container image changes. Usage: sh migrate.sh [compose-project-dir]
+
+set -eu
+
+DIR="${1:-.}"
+IMAGE="ghcr.io/dvorinka/cloudreve:latest"
+
+for f in docker-compose.yml docker-compose.yaml compose.yml compose.yaml; do
+    if [ -f "$DIR/$f" ]; then COMPOSE_FILE="$DIR/$f"; break; fi
+done
+
+if [ -z "${COMPOSE_FILE:-}" ]; then
+    echo "No compose file found in $DIR" >&2
+    exit 1
+fi
+
+if ! grep -q "cloudreve/cloudreve" "$COMPOSE_FILE"; then
+    echo "No upstream 'cloudreve/cloudreve' image found in $COMPOSE_FILE — nothing to migrate." >&2
+    exit 1
+fi
+
+cp "$COMPOSE_FILE" "$COMPOSE_FILE.bak"
+sed -i "s|image: *cloudreve/cloudreve:[^ ]*|image: $IMAGE|" "$COMPOSE_FILE"
+echo "Updated $COMPOSE_FILE (backup: $COMPOSE_FILE.bak)"
+
+cd "$DIR"
+if docker compose version >/dev/null 2>&1; then
+    docker compose pull && docker compose up -d
+elif command -v docker-compose >/dev/null 2>&1; then
+    docker-compose pull && docker-compose up -d
+else
+    echo "docker compose not found — install it, then run: docker compose pull && docker compose up -d" >&2
+    exit 1
+fi
+
+echo "Migration complete. Cloudreve is on port 5212; existing accounts, files, and settings carry over."