diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b7a5edd..06b97387 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,9 @@
 ### Changed
 - _(none yet)_
 
+### Docs
+- **Server migration:** added manual / out-of-order migration troubleshooting (native install + `rust2go`, `TestNatRequest` without registration) in `docs/troubleshooting/SERVER_MIGRATION.md`.
+
 ---
 
 ## [3.3.126] — 2026-07-07
diff --git a/docs/troubleshooting/SERVER_MIGRATION.md b/docs/troubleshooting/SERVER_MIGRATION.md
index 685eca63..351a899e 100644
--- a/docs/troubleshooting/SERVER_MIGRATION.md
+++ b/docs/troubleshooting/SERVER_MIGRATION.md
@@ -57,8 +57,121 @@ Checklist:
 | `managed` | Peers already in the DB re-register freely; unknown IDs need approval. |
 | `locked` | Only peers with a valid device token can register. |
 
-## Related
+## Manual / out-of-order migration (native install + rust2go)
 
+Some operators install BetterDesk on a **new path** (for example `/opt/betterdesk` via `install.sh --native`), then copy keys and run `rust2go` from the old RustDesk tree (`/opt/rustdesk`). That works, but the order differs from the built-in installer path that auto-detects an existing RustDesk server directory.
+
+### Symptom
+
+- The web console loads and you can log in.
+- Clients do **not** appear online / do not register after reboot.
+- Server logs show `TestNatRequest` from client IPs, but **no** `RegisterPeer`, `RegisterPk`, or `New peer registered`.
+- A test with a **new IP or hostname** works — the server itself is healthy; existing client configs are the likely gap.
+
+`TestNatRequest` only proves partial network reachability. Full registration needs UDP `RegisterPeer` on port **21116**, then `RegisterPk`, and (for the console) HTTP heartbeats to **21114**.
+
+### Safe checklist (no data loss)
+
+**Before any change**, back up the server data directory:
+
+```bash
+sudo cp -a /opt/betterdesk "/opt/betterdesk-backup-$(date +%F)"
+# If the old RustDesk tree still exists:
+sudo cp -a /opt/rustdesk "/opt/rustdesk-backup-$(date +%F)" 2>/dev/null || true
+```
+
+Do **not** regenerate or delete `id_ed25519` / `db_v2.sqlite3` unless you intend to reconfigure every client.
+
+#### 1. Verify the server public key
+
+Clients must use the **same** public key as the running server:
+
+```bash
+cat /opt/betterdesk/id_ed25519.pub
+```
+
+Compare with:
+
+- **Dashboard → RustDesk Client Configuration → Key**
+- **RustDesk → Settings → Network → ID/Relay Server → Key** on one affected client
+
+If they differ, the fresh install may have generated new keys before you copied the old ones. Restore the original `id_ed25519` and `id_ed25519.pub` from your backup, fix permissions (`600` / `644`), and restart `betterdesk-server`. See [KEY_TROUBLESHOOTING.md](KEY_TROUBLESHOOTING.md).
+
+#### 2. Verify the migrated device database
+
+Confirm `rust2go` imported peers into the Go database:
+
+```bash
+sqlite3 /opt/betterdesk/db_v2.sqlite3 "SELECT COUNT(*) FROM peers;"
+sqlite3 /opt/betterdesk/db_v2.sqlite3 "SELECT id, hostname FROM peers LIMIT 5;"
+```
+
+If the count is `0` or expected devices are missing, re-run migration against the correct source DB:
+
+```bash
+./migrate -mode rust2go -src /opt/rustdesk/db_v2.sqlite3 -dst /opt/betterdesk/db_v2.sqlite3
+sudo systemctl restart betterdesk-server
+```
+
+#### 3. Check enrollment mode
+
+In **Settings → Enrollment mode**:
+
+| Mode | Effect after migration |
+|------|------------------------|
+| `open` | Any valid client can register. |
+| `managed` | Peers **already in the DB** re-register freely; unknown IDs wait in **Pending devices**. |
+| `locked` | Only peers with a pre-bound device token can register. |
+
+For a quick test on **one** machine, you can temporarily set `open`, restart the server, and retry. Revert to your preferred policy after confirming registration works.
+
+#### 4. Check firewall / ports from a client
+
+Clients need outbound access to the server:
+
+| Port | Protocol | Purpose |
+|------|----------|---------|
+| **21116** | **UDP** + TCP | Signal / `RegisterPeer` (online status) |
+| **21114** | TCP | API / heartbeat (`http://host:21114`) |
+| **21117** | TCP | Relay sessions |
+
+`TestNatRequest` can succeed over TCP while UDP **21116** is blocked — registration will still fail.
+
+#### 5. Refresh client config (reboot alone may not be enough)
+
+When you tested with a **new** hostname, you likely applied a fresh server config (correct key + API URL). Clients still pointing at the old hostname may keep stale settings.
+
+On **one** test client, re-apply settings from the dashboard (**Copy deploy string**) or set manually:
+
+- **ID Server** — your public hostname or IP
+- **Relay Server** — same (or leave empty)
+- **API Server** — `http://<host>:21114` (not the web panel on `:5000`)
+- **Key** — contents of `id_ed25519.pub`
+
+This does **not** change the device ID — it only refreshes server endpoints and the key.
+
+See [RUSTDESK_CLIENT_DEPLOYMENT.md](../setup/RUSTDESK_CLIENT_DEPLOYMENT.md) for deploy-string details.
+
+#### 6. Watch registration logs
+
+```bash
+journalctl -u betterdesk-server -f | grep -E 'RegisterPeer|RegisterPk|New peer|Enrollment|Rejected'
+```
+
+After refreshing config on one client, you should see `RegisterPeer` / `New peer registered` within ~30 seconds.
+
+### Recommended migration order (for future cutovers)
+
+1. **Backup** old RustDesk keys + `db_v2.sqlite3`.
+2. Install BetterDesk (prefer auto-detection of `/opt/rustdesk`, or use `betterdesk.sh` → **Database migration** → `rust2go`).
+3. **Verify on a temporary IP/hostname** — one client registers, console shows it online.
+4. Stop the old RustDesk server; move the production IP/DNS to BetterDesk.
+5. **Refresh client server config** (deploy string or GPO/RMM) — reboot alone is often insufficient after a key or API URL mismatch.
+
+### Related
+
+- [KEY_TROUBLESHOOTING.md](KEY_TROUBLESHOOTING.md) — key mismatch diagnosis and recovery
+- [RUSTDESK_CLIENT_DEPLOYMENT.md](../setup/RUSTDESK_CLIENT_DEPLOYMENT.md) — mass client config
 - Go signal handler: `betterdesk-server/signal/handler.go` (UDP `RegisterPeer`)
 - HTTP heartbeat (DB only): `betterdesk-server/api/client_api_handlers.go`
 - Panel mapping: `web-nodejs/services/betterdeskApi.js` (`online: !!peer.live_online`)