Operations

Check readiness, alerts, and backups first; choose a task, then follow the five-step change flow.

Start with three outcomes: nodes can accept traffic, someone responds to alerts, and data has a verified backup.

Do these three things first

Check /readyz on every node, then verify product messaging and recovery.
Alert on readiness, errors, queues, and disk; assign a responder.
Configure backups in Manager, test storage, and confirm at least one complete, verified backup.

What do you need to do?

Check service health

Verify readiness, product behavior, and monitoring separately.

Troubleshoot a problem

Choose a symptom and narrow the problem using evidence.

Use Manager

Back up or restore data

Verify backups and restore during maintenance.

Add or remove nodes

Inspect migration tasks and safely drain old nodes.

Upgrade WuKongIM

Check compatibility and rollback before upgrading.

v2 → v3 Offline Migration

Migrate cold backups, verify data, then cut over clients.

Single-node clusters follow the same procedures

A single-node cluster still follows Manager, Controller, and Slot procedures. Do not bypass them by editing data manually. The 256 physical hash slots remain fixed when nodes change.

Use these five steps for every change

What each step does and when to continue

Record the current state: Save versions, configuration, node state, /readyz, and key metrics. Continue when: You know what normal looked like before the change.
Prepare a way back: Record the rollback method, owner, and stop conditions. Continue when: Everyone knows who stops the change and how.
Make a small change: Change one thing at a time; advance one node or a small task batch. Continue when: The current step has finished.
Test the product: Test sign-in or reconnect, message send and receive, and history. Continue when: Product checks pass and nodes are ready again.
Save the result: Keep task results, errors, metrics, and the final node list. Continue when: Someone can later see exactly what happened.

Stop if any of these happen

/readyz returns 503, or readiness repeatedly changes between success and failure.
Manager shows missing, stale, or conflicting node, Controller, Slot, Channel, or task state.
A previous scaling, restore, or upgrade task has not finished.
A production change has no rollback method, or no backup has passed verification.
The release notes do not explicitly say whether the current and target versions may run together.

Stop and preserve the current evidence, then follow Troubleshooting. See Server Tools when you need a command-line tool.