Backup & Restore
Follow separate backup and maintenance restore flows; check expected outcomes and expand complete actions.
Open Manager → Cluster → Backups. No wukongim.toml change is needed.
Create a verified backup
Test storage, complete the task, then verify the archive.
Restore during maintenance
Confirm the archive, restore, then test before traffic.
Permissions: backup cluster.backup:w; restore explicit cluster.restore:w. Archives are unencrypted; enable storage-side encryption.
Backup exercise
Keep automatic backup off until verification succeeds.
| Action | Expected result |
|---|---|
| Save settings → Test storage | Settings saved; storage Verified |
| Back up now | 256/256 Hash Slots; recent task Succeeded |
| Verify → Hold | Archive healthy; Archive verification succeeded |
Every node must share the backup directory
Every node's data_dir/backup-repository must point to the same shared storage. Without shared storage, choose OSS, COS, or S3.
Example settings and complete backup actions
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: Every /readyz returns 200, no other admin task runs, and the archive is freshly verified. Per-node free space: current data + twice the archive's logical size + 1 GiB.
Check the cluster, archive time, and size; confirm with the current administrator password and RESTORE <archive ID>. Keep nodes running; make no other changes.
Before traffic: The task succeeds, every /readyz returns 200, and history, sign-in, send/receive, reconnect, webhooks, and plugins pass.
Same cluster only
Restore only to the archive's original cluster, never into a new cluster or as a v2 → v3 migration.
On failure: Preserve task/errors; do not repeat restore. See Troubleshooting.
Complete restore actions and permission requirements
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.