Operations
Start with daily checks, then monitor, back up, scale, and upgrade WuKongIM safely.
If this is your first time operating WuKongIM, do not start by learning every metric and cluster term. Focus on three outcomes: the service can accept traffic, someone will notice failures, and your data can actually be restored.
A one-node deployment is still a cluster
Even one node is a single-node cluster. Do not bypass Manager, Controller, or Slot behavior by editing data manually. WuKongIM always uses 256 physical hash slots; adding or removing nodes does not change that number.
Do these three things first
- Request
/readyzon every node. HTTP 200 means that the node can currently accept product traffic. - Alert on readiness failures, rising errors, queue backlogs, and low disk space. Assign a person to respond.
- Create a backup plan in Manager, run Test storage, and confirm that at least one backup is complete and verified.
Then choose the page that matches your task.
What do you need to do?
Use Manager
Sign in, inspect nodes and tasks, and perform administrative actions safely.
Check service health
Understand /healthz, /readyz, metrics, and alerts.
Add or remove nodes
Move work to a new node or safely drain an old one.
Back up or restore data
Create a verified backup and restore it during maintenance.
Upgrade WuKongIM
Check version compatibility before choosing a rolling or stopped upgrade.
v2 → v3 Offline Migration
Use wkcli migrate to migrate cold backups, verify data, and cut over clients.
Troubleshoot a problem
Start from the symptom and narrow the problem with low-cost checks.
Use these five steps for every change
| Step | What to do | Continue when |
|---|---|---|
| 1. Record the current state | Save versions, configuration, node state, /readyz, and key metrics | You know what normal looked like before the change |
| 2. Prepare a way back | Record the rollback method, owner, and stop conditions | Everyone knows who stops the change and how |
| 3. Make a small change | Change one thing at a time; advance one node or a small task batch | The current step has finished |
| 4. Test the product | Test sign-in or reconnect, message send and receive, and history | Product checks pass and nodes are ready again |
| 5. Save the result | Keep task results, errors, metrics, and the final node list | Someone can later see exactly what happened |
Stop if any of these happen
/readyzreturns 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.