Backup & Restore
Follow one example to back up and restore data in Manager.
Open Manager → Cluster → Backups. No wukongim.toml change is needed.
Backup exercise
Leave Enable automatic backup off and enter these example values:
| Setting | Example value |
|---|---|
| Backup frequency | Every day at 01:00 |
| Time zone | Asia/Shanghai |
| Storage | Shared file storage |
| Archives to keep | 7 |
| Workers per node | 1 |
| Timeout | 12 hours |
Every node must share the backup directory
data_dir/backup-repository on every node must point to the same shared storage. Without shared storage, select OSS, COS, or S3.
- Select Save settings and wait for Backup settings saved.
- Select Test storage and wait for Storage verification: Verified.
- Select Back up now and wait for
256/256 Hash Slotsunder Current task. - Confirm Succeeded under Recent tasks.
- Select Verify next to the archive, then select Hold after verification succeeds.
Done when: the archive is healthy and the page says Archive verification succeeded. Enable and save Automatic backup when you want scheduled runs.
Restore exercise
Restore replaces current data
Messages and changes after the archive's completion time will be lost, and clients will disconnect. Use a maintenance window.
Before starting, confirm that every /readyz returns 200, no other administrative task is running, the archive has just passed verification, and each node has free space for current data + twice the archive's logical size + 1 GiB.
- Select Restore next to the target archive.
- Check the cluster, archive time, and size shown on the page.
- Enter the current administrator password.
- Enter
RESTORE <archive ID>as shown, then select Start restore. - Wait for the task to finish. Do not stop nodes or perform another change.
- Sign in to Manager again, confirm Recent tasks: Succeeded, and check that every
/readyzreturns 200. - Check history, then test sign-in, message send and receive, reconnect, webhooks, and plugins. Restore traffic only after every check passes.
You cannot restore into another cluster
An archive restores only to the same cluster that created it. It is not a new-cluster import or v2-to-v3 migration tool.
On failure, preserve the task and error details instead of repeatedly starting restore. Backup requires cluster.backup:w; restore requires explicit cluster.restore:w. WuKongIM does not encrypt archive contents, so enable storage-side encryption.