How to migrate, back up, and restore data

Stop Dashboard before backing up, then use the commands for your deployment to start it after restoration. The current installation script has no separate “Stop Dashboard” or “Start Dashboard” menu entries.

“Restart and Update Dashboard” pulls an image or downloads the latest binary; it is not a restart-only operation. Do not use it instead of the stop/start commands below. Do not use “Uninstall Dashboard” either: it removes the Dashboard directory.

1. Identify your deployment and backup scope

The current script supports Docker and standalone installations. Its default Dashboard directory is /opt/nezha/dashboard:

• Docker: Uses docker-compose.yaml in that directory, with service name dashboard and ./data mounted at /dashboard/data inside the container.
• Standalone: Runs the app binary in that directory as the nezha-dashboard service, managed by systemd or OpenRC.
• Core data: data/ contains configuration in config.yaml, the default database sqlite.db, and other runtime data. Back up the whole directory, not just the main database file.

The instructions below use the script defaults. If you customized the database location, configuration path, or tsdb.data_path, or use external mounts or symbolic links, back up the actual data separately. Reverse-proxy configuration, certificates, and systemd/OpenRC service files are outside the Dashboard directory and also need separate copies.

Separate migration from upgrades

This guide covers migration and recovery between compatible V2 deployments. Prefer restoring with the same Dashboard version as the source, then upgrading separately. The installation script downloads the latest release; it is not a fixed-version recovery tool. For older product generations, consult their migration instructions rather than overwriting data directly.

2. Stop Dashboard on the source server

Run only the command group matching your deployment. Stop Dashboard, not the Agents on individual servers. Monitoring and alerting will be temporarily unavailable during migration.

Docker

sudo docker compose -f /opt/nezha/dashboard/docker-compose.yaml stop -t 60 dashboard
sudo docker compose -f /opt/nezha/dashboard/docker-compose.yaml ps -a

Confirm the service has stopped. If you use the standalone Compose command, replace docker compose with docker-compose throughout these examples.

Standalone: systemd

sudo systemctl stop nezha-dashboard
sudo systemctl is-active nezha-dashboard

The expected output is inactive; a nonzero exit status from this check is normal when the service is stopped.

Standalone: OpenRC

sudo rc-service nezha-dashboard stop
sudo rc-service nezha-dashboard status

Confirm the service is stopped. Investigate failed stops or abnormal exits in logs before proceeding; an archive copied from a running data directory is not necessarily a consistent backup.

3. Create and store a backup

Run this example on the source server. Choose a new filename for each subsequent backup so you do not overwrite an earlier archive.

sudo install -d -m 700 /root/nezha-backup
sudo tar -czpf /root/nezha-backup/dashboard-backup.tar.gz -C /opt/nezha dashboard
sudo tar -tzf /root/nezha-backup/dashboard-backup.tar.gz > /dev/null
sudo sha256sum /root/nezha-backup/dashboard-backup.tar.gz

Confirm the commands succeed. Store the archive and checksum on another machine or backup storage. Use a protected transfer method and compare checksums after copying. Backups contain configuration, database contents, and credentials; keep them out of public download directories.

• Backup only: Start the original Dashboard using section 5 once the backup is complete.
• Server migration: Keep the old Dashboard stopped while restoring on the target, so two instances do not run tasks and send notifications at the same time.

4. Restore on the target server

1. Prepare the runtime. Set up Docker/Compose, or a standalone binary and service files suitable for the target CPU architecture. You can follow Install Dashboard in an empty directory to establish a deployment, but confirm version compatibility and stop the new instance before restoring. Copying the directory alone does not register a standalone service; do not reuse an app binary built for a different CPU architecture.
2. Preserve existing target data. If the target already has data, stop it, make a separate backup, and move its current data/ to an unused backup location. Do not merge two database directories.
3. Extract into a temporary directory. Inspect the archive, then restore its entire dashboard/data/ as /opt/nezha/dashboard/data/ on the target, preserving permissions and ownership. Retain the binary and service files appropriate for the target. For Docker, review the image version, ports, and mounts instead of blindly overwriting the target configuration.
4. Check external dependencies. Restore separately backed-up TSDB or other external data. Check the service user's read/write permissions, configuration paths, reverse proxy, certificates, and firewall. If the address or port changes, update DNS and Agent connection settings as well.

Start directly after restoring

Do not select “Install Dashboard” or “Modify Dashboard Configuration” after restoring data: the current script regenerates and overwrites data/config.yaml, and rewrites the Compose file for Docker deployments. Start the service with the commands below instead.

5. Start and verify

Select the commands for your deployment. The Docker commands below start an existing container without pulling a new image. If the target has only a Compose file and no container yet, verify its image version and mounts, then create the container with sudo docker compose -f /opt/nezha/dashboard/docker-compose.yaml up -d dashboard.

Docker

sudo docker compose -f /opt/nezha/dashboard/docker-compose.yaml start dashboard
sudo docker compose -f /opt/nezha/dashboard/docker-compose.yaml logs --tail 100 dashboard

Standalone: systemd

sudo systemctl start nezha-dashboard
sudo systemctl status nezha-dashboard --no-pager

If you manually added or changed the systemd service file, run sudo systemctl daemon-reload before starting it.

Standalone: OpenRC

sudo rc-service nezha-dashboard start
sudo rc-service nezha-dashboard status

After restoration, check that:

• Your original account works and the server inventory, settings, alerts, and tasks remain present.
• Agents reconnect and server state and monitoring data continue to update.
• Online history and any enabled TSDB history match the backup point.
• Logs show no database, permission, or configuration-reading errors, and domain and reverse-proxy access work.

Keep the old server and backup until verification is complete. To roll back, stop the new Dashboard before switching back to the original deployment and connection address. Do not open a database migrated by a newer release directly with an older binary.

Script references

Paths, service names, and menu behavior are based on the official English installation script, Compose template, systemd unit, and OpenRC service.