Common Configurations
The 10 most-used WuKongIM settings, with their purpose, default behavior, and key constraints.
This page keeps only the 10 settings most often consulted for startup, client access, and daily operations. Each setting can be provided through TOML or an environment variable; when both are present, the environment variable overrides the file value. See the Configuration Reference for every field and its exact semantics.
Every deployment is a cluster
A one-node deployment is a single-node cluster. Every scenario requires node.id, node.data_dir, and cluster.listen_addr; configuration changes usually require a node restart.
10 most-used settings
| Setting (TOML / environment) | Purpose | Defaults and cautions |
|---|---|---|
node.idWK_NODE_ID | Identifies this node as the stable identity used by messages and cluster state. | Required at startup, non-zero, and unique within the cluster; do not change it after data exists. |
node.data_dirWK_NODE_DATA_DIR | Stores this node's durable Controller, Slot, Channel, and related data. | Required at startup; the directory must be writable and should reside on persistent, backed-up storage. |
cluster.listen_addrWK_CLUSTER_LISTEN_ADDR | Listens for Cluster RPC between nodes. | Required at startup; it may bind 0.0.0.0, but the address given to peers must be reachable and must not be a wildcard. |
cluster.nodesWK_CLUSTER_NODES | Defines the static Controller voter list, with each entry containing a node id and cluster addr. | When cluster.seeds is also unset, omission or an empty list falls back to an implicit single-node cluster; it cannot be combined with non-empty cluster.seeds. The environment value must be JSON and replaces the whole list. |
cluster.slot_replica_nWK_CLUSTER_SLOT_REPLICA_N | Sets the voter replicas for each Slot Raft Group when the cluster is first initialized. | 0 derives the static voter count, or uses 1 during seed joining; existing clusters follow persisted Controller state. |
gateway.listenersWK_GATEWAY_LISTENERS | Defines the TCP or WebSocket listeners used by clients. | Omission opens WKProto TCP on 0.0.0.0:5100 and WSMux on 0.0.0.0:5200; an explicit empty list disables Gateway. The environment value must be JSON. |
api.listen_addrWK_API_LISTEN_ADDR | Listens for the Product HTTP API, including health and switch-controlled metrics, debug, and related HTTP routes. | Omission or an empty value disables this HTTP service; it does not create client Gateway or Manager listeners. |
manager.listen_addrWK_MANAGER_LISTEN_ADDR | Listens for the separate Manager administration service. | Omission or an empty value disables Manager; enable authentication and restrict network access before exposing it. |
manager.auth_onWK_MANAGER_AUTH_ON | Requires JWT login authentication for Manager routes. | Omission is false; when true, both manager.jwt_secret and manager.users are required. |
log.levelWK_LOG_LEVEL | Sets the minimum application log level that is recorded. | Defaults to info; allowed values are debug, info, warn, and error. Avoid leaving debug enabled after production troubleshooting. |
Continue reading
- See the Configuration overview for file lookup, environment overrides, and list replacement.
- See the Configuration Reference for seed joining, channel replicas, metrics, webhooks, and every other setting.
- Complete the Production Checklist before production use.