This is the quick-reference handbook for WuKongIM's public startup configuration, checked against the startup schema. Every row explains what the field controls, its one environment mapping, and any important default, zero-value, mutual-exclusion, compatibility, or security boundary.
Browse by domain with the page outline, or use browser Find to search for a TOML key, WK_* environment variable, or keyword.
Prefer TOML for normal configuration; environment variables override TOML. Unknown TOML paths and unknown WK_* variables fail startup.
duration uses Go syntax such as 500ms, 5s, or 24h. Environment values for string_list and object_list must be JSON and replace the complete list.
Configuration is loaded at node startup. Restart the node after a change unless the subsystem explicitly documents otherwise.
Defaults and configuration baselines
Starting with v3.0.0-beta.7, wukongim init creates a security-oriented installation baseline at /etc/wukongim/wukongim.toml by default and explicitly disables Diagnostics and Plugin. Use wukongim init --config PATH to choose another location; the original wukongim config init --config PATH compatibility entry point also remains available. wukongim.toml.example is a loadable development and tuning baseline. Neither baseline is a complete catalog of runtime defaults. In the table, “omitted” means neither TOML nor an environment value was supplied; it may differ from an explicit 0, empty string, or false.
node.id, node.data_dir, and cluster.listen_addr are always required. Seed joining additionally requires cluster.id, non-empty cluster.seeds, a peer-reachable cluster.advertise_addr, and a non-empty cluster.join_token.
For task-oriented field discovery, start with Common Configurations; this page is the field-by-field reference.
Listener for inter-node Cluster RPC; it may bind 0.0.0.0, but a wildcard must not be advertised to peers. Required at startup.
cluster.start_timeout
WK_CLUSTER_START_TIMEOUT
duration
Maximum wait for startup readiness gates, including committed Slot write probes; omitted or 0 uses 30s. Must be non-negative. Size from measured cold recovery; quorum, routing, and placement checks and steady-state request timeouts remain unchanged.
cluster.id
WK_CLUSTER_ID
string
Stable Controller cluster identity; required for seed joining. Static inventories and implicit single-node clusters derive it from node IDs when omitted.
cluster.seeds
WK_CLUSTER_SEEDS
string_list
Existing node addresses used to discover the cluster during dynamic joining; must be non-empty and cannot be combined with cluster.nodes.
cluster.advertise_addr
WK_CLUSTER_ADVERTISE_ADDR
string
Stable address stored in membership for peers to call this node; required with cluster.seeds and must be reachable by peers.
cluster.join_token
WK_CLUSTER_JOIN_TOKEN
string
Shared credential that authenticates dynamic cluster joining; it must be non-empty whenever present and is required with cluster.seeds. Redacted in startup snapshots and diagnostics.
cluster.nodes
WK_CLUSTER_NODES
object_list
Static Controller voters with {id, addr} elements; a non-empty list must contain the current node.id, with non-zero unique IDs and non-empty addresses. It cannot be combined with cluster.seeds; an explicit empty list (including environment JSON null) currently falls back to an implicit single-node cluster and cannot disable clustering.
Independent Slot Raft Groups written to persisted Controller state at first initialization; it cannot exceed cluster.hash_slot_count, and omitted or 0 uses 1. Existing clusters follow the persisted value: changing this setting does not resize Slots, and increasing it may block readiness. Do not change it after initialization.
cluster.hash_slot_count
WK_CLUSTER_HASH_SLOT_COUNT
uint16
Stable hash-slot partitions that route keys across Slot Raft Groups; omitted or 0 uses 256. Do not change it after cluster initialization.
cluster.slot_replica_n
WK_CLUSTER_SLOT_REPLICA_N
uint16
Voter replicas per Slot Raft Group when initializing Controller state; existing clusters follow persisted Controller state. 0 derives the static voter count but falls back to 1 during seed joining; an explicit static value cannot exceed the voter count.
cluster.channel_replica_n
WK_CLUSTER_CHANNEL_REPLICA_N
uint16
Desired data replicas for newly created channels; 0 follows the local effective cluster.slot_replica_n, becoming 1 during seed joining rather than reading the persisted Controller replica count. Multi-replica clusters should set the same explicit value on every node and fit available nodes and failure domains.
cluster.slot_tick_interval
WK_CLUSTER_SLOT_TICK_INTERVAL
duration
Local Slot Raft tick interval; defaults to 50ms and must be greater than 0.
cluster.slot_election_tick
WK_CLUSTER_SLOT_ELECTION_TICK
int
Ticks waited before a Slot Raft election can start; defaults to 40 and must exceed the heartbeat tick.
cluster.slot_heartbeat_tick
WK_CLUSTER_SLOT_HEARTBEAT_TICK
int
Slot Raft heartbeat interval in ticks; defaults to 2 and must be greater than 0.
cluster.slot_log_compaction_enabled
WK_CLUSTER_SLOT_LOG_COMPACTION_ENABLED
bool
Enables local Slot Raft snapshots and log compaction; enabled when omitted.
cluster.slot_log_compaction_trigger_entries
WK_CLUSTER_SLOT_LOG_COMPACTION_TRIGGER_ENTRIES
uint64
Applied entries since the last snapshot required before another compaction; defaults to 10000 and must be positive.
cluster.slot_log_compaction_check_interval
WK_CLUSTER_SLOT_LOG_COMPACTION_CHECK_INTERVAL
duration
Minimum interval between Slot Raft log-compaction checks; defaults to 30s and must be positive.
Interval for reporting compact node health to Controller; defaults to 5s and must be positive.
cluster.node_health_report_ttl
WK_CLUSTER_NODE_HEALTH_REPORT_TTL
duration
How long Controller trusts the latest node-health report; defaults to 30s and cannot be shorter than the report interval.
cluster.commit_coordinator_sync
WK_CLUSTER_COMMIT_COORDINATOR_SYNC
bool
Durable-commit compatibility switch; omitted is equivalent to true, and an explicit value must also be true because WuKongIM does not allow durable sync to be disabled.
cluster.commit_coordinator_flush_window
WK_CLUSTER_COMMIT_COORDINATOR_FLUSH_WINDOW
duration
Maximum delay for grouping adjacent Channel durable commits; defaults to 500us, and an explicit value must be positive.
cluster.commit_coordinator_max_requests
WK_CLUSTER_COMMIT_COORDINATOR_MAX_REQUESTS
int
Maximum logical requests grouped into one physical commit; 0 applies no request-count limit.
cluster.commit_coordinator_max_records
WK_CLUSTER_COMMIT_COORDINATOR_MAX_RECORDS
int
Maximum message records grouped into one physical commit; 0 applies no record-count limit.
cluster.commit_coordinator_max_bytes
WK_CLUSTER_COMMIT_COORDINATOR_MAX_BYTES
int
Maximum approximate payload bytes grouped into one physical commit; 0 applies no byte limit.
cluster.commit_coordinator_shards
WK_CLUSTER_COMMIT_COORDINATOR_SHARDS
int
Independent commit coordinators for the message database; 0 uses 1. Increase only after storage-specific load tests.
Listener for the product HTTP API; an empty value disables this HTTP service.
api.external_tcp_addr
WK_EXTERNAL_TCPADDR
string
WKProto TCP address override published to capacity discovery and similar callers, in host:port form; empty derives from the first matching gateway.listeners entry and stays empty if none matches. It does not create a listener.
api.external_ws_addr
WK_EXTERNAL_WSADDR
string
WebSocket URL override published to capacity discovery and similar callers; empty derives from the first matching gateway.listeners entry and stays empty if none matches. It does not create a listener and is redacted from diagnostic artifacts.
api.external_wss_addr
WK_EXTERNAL_WSSADDR
string
Secure WebSocket URL override published to capacity discovery and similar callers; empty derives from the first matching gateway.listeners entry and stays empty if none matches. It does not create a listener and is redacted from diagnostic artifacts.
When the corresponding api.external_* is omitted, default external /route and /route/batch complete only wildcard listener hosts from a valid request Host, preserving the Gateway port, scheme, and path. Explicit addresses, concrete listener hosts (including loopback), intranet queries, and explicit node selectors stay unchanged; capacity discovery still returns listener-derived addresses. Completed responses use Cache-Control: no-store. Completion ignores forwarded headers and cannot infer NAT ports or TLS ingress; reverse proxies should preserve the original Host. Configure client-reachable overrides for remapped external ports, separate ingress, or a backend calling /route through an internal host.
Listener for the Manager administration service; an empty value disables Manager.
manager.auth_on
WK_MANAGER_AUTH_ON
bool
Requires JWT login authentication for Manager routes; disabled when omitted. With false, Manager routes require no JWT, so do not expose an unauthenticated service to untrusted networks.
manager.jwt_secret
WK_MANAGER_JWT_SECRET
string
Secret used to sign and verify Manager JWTs; required when Manager is listening with authentication enabled. Redacted in startup snapshots and diagnostics.
manager.jwt_issuer
WK_MANAGER_JWT_ISSUER
string
Issuer written to the Manager JWT iss claim.
manager.jwt_expire
WK_MANAGER_JWT_EXPIRE
duration
Manager JWT lifetime; when Manager is listening with authentication enabled, omitted or explicit 0 uses 24h, while a negative value fails startup.
manager.users
WK_MANAGER_USERS
object_list
Static Manager users with username, password, and permissions[{resource, actions}]; actions are r, w, or *. Required when Manager is listening with authentication enabled and fully redacted.
Exposes /bench/v1/* routes on the API listener for controlled benchmark environments; disabled when omitted and requires non-empty api.listen_addr.
bench.api_token
WK_BENCH_API_TOKEN
string
Bench API bearer token; an empty value skips token validation, so set it whenever the API is remotely reachable. Redacted in snapshots and diagnostics.
bench.api_max_batch_size
WK_BENCH_API_MAX_BATCH_SIZE
int
Maximum top-level records accepted by one Bench API mutation request; omitted uses 10000, while an explicit value at or below 0 removes this limit and is not recommended for remotely reachable environments.
bench.api_max_payload_bytes
WK_BENCH_API_MAX_PAYLOAD_BYTES
int
Maximum JSON body bytes accepted by one Bench API mutation request; omitted uses 10485760 (10 MiB), while an explicit value at or below 0 removes this limit and is not recommended for remotely reachable environments.
Enables runtime metric observers and exposes /metrics when an API listener exists; disabled when omitted. The HTTP metrics endpoint requires non-empty api.listen_addr.
observability.debug_api_enable
WK_DEBUG_API_ENABLE
bool
Exposes /debug diagnostics on the API listener; disabled when omitted and requires non-empty api.listen_addr. Never publish it directly to the internet.
Starts a Prometheus child process managed by WuKongIM; disabled when omitted. Enabling also requires an API listener, metrics, and valid scrape targets; keep it disabled with external Prometheus.
prometheus.query_base_url
WK_PROMETHEUS_QUERY_BASE_URL
string
Base URL used by Manager to query an external Prometheus HTTP API; it must be an HTTP(S) URL with a host and no query or fragment. Empty may fall back to managed Prometheus. Redacted from diagnostics.
prometheus.binary_path
WK_PROMETHEUS_BINARY_PATH
string
External Prometheus executable used by the managed process; empty uses the embedded binary.
prometheus.listen_addr
WK_PROMETHEUS_LISTEN_ADDR
string
Web listener for the managed Prometheus process, in host:port form; defaults to 127.0.0.1:9099.
prometheus.data_dir
WK_PROMETHEUS_DATA_DIR
string
Directory for generated Prometheus configuration and TSDB data; empty derives it from node.data_dir.
prometheus.retention_time
WK_PROMETHEUS_RETENTION_TIME
duration
Time-based retention window for the managed Prometheus TSDB; omitted or 0 uses 360h.
prometheus.retention_size
WK_PROMETHEUS_RETENTION_SIZE
string
Optional size-based retention limit for the managed Prometheus TSDB; empty applies no size limit.
prometheus.scrape_interval
WK_PROMETHEUS_SCRAPE_INTERVAL
duration
Interval for managed Prometheus to scrape WuKongIM metrics; omitted or 0 uses 15s.
prometheus.scrape_targets
WK_PROMETHEUS_SCRAPE_TARGETS
string_list
Metrics targets for managed Prometheus as host:port values without a URL scheme and with ports from 1 to 65535; an empty list may be derived from the API listener.
Captures bounded node-local diagnostic events; enabled when omitted.
diagnostics.buffer_size
WK_DIAGNOSTICS_BUFFER_SIZE
int
Maximum diagnostic events retained in memory; 0 uses 50000.
diagnostics.sample_rate
WK_DIAGNOSTICS_SAMPLE_RATE
float
Baseline keep probability for successful diagnostic events, from 0 to 1; omitted uses 0.01.
diagnostics.slow_threshold_ms
WK_DIAGNOSTICS_SLOW_THRESHOLD_MS
int
Duration threshold for keeping successful slow events, in milliseconds; omitted or 0 uses 500.
diagnostics.error_sample_rate
WK_DIAGNOSTICS_ERROR_SAMPLE_RATE
float
Keep probability for non-success diagnostic events, from 0 to 1; omitted uses 1.
diagnostics.deep_sample_rate
WK_DIAGNOSTICS_DEEP_SAMPLE_RATE
float
Sampling probability for expensive Reactor or store detail, from 0 to 1; defaults to 0.
diagnostics.deep_slow_threshold_ms
WK_DIAGNOSTICS_DEEP_SLOW_THRESHOLD_MS
int
Threshold for deep tracing slow Reactor or store stages, in milliseconds; omitted or 0 follows the normal slow threshold.
diagnostics.deep_max_items_per_batch
WK_DIAGNOSTICS_DEEP_MAX_ITEMS_PER_BATCH
int
Maximum messages expanded into events by one deep-trace batch; 0 uses 16.
diagnostics.debug_matches
WK_DIAGNOSTICS_DEBUG_MATCHES
object_list
Temporary high-priority sampling rules; an empty list means none. Each item needs at least one of uid, channel_key, client_msg_no, or trace_id; positive ttl_seconds is required to take effect and zero is silently ignored. sample_rate ranges from 0 to 1, where 0 retains nothing.
Requires each CONNECT token to exactly match the stored device token for the same UID and device_flag; defaults to true. Disable only for a controlled compatibility migration.
gateway.gnet_multicore
WK_GATEWAY_GNET_MULTICORE
bool
Enables gnet's CPU-scaled multi-event-loop mode; enabled when omitted.
gateway.gnet_num_event_loop
WK_GATEWAY_GNET_NUM_EVENT_LOOP
int
gnet event-loop count; 0 retains the WuKongIM baseline of 4.
gateway.runtime_async_send_workers
WK_GATEWAY_RUNTIME_ASYNC_SEND_WORKERS
int
Maximum workers dispatching SEND frames asynchronously; a non-positive value uses 1000.
gateway.runtime_async_send_queue_capacity
WK_GATEWAY_RUNTIME_ASYNC_SEND_QUEUE_CAPACITY
int
Maximum queued asynchronous SEND frames; a non-positive value uses 131072, and a full queue rejects new SEND frames.
gateway.runtime_async_auth_workers
WK_GATEWAY_RUNTIME_ASYNC_AUTH_WORKERS
int
Maximum workers processing CONNECT authentication asynchronously; a non-positive value uses 16.
gateway.runtime_async_auth_queue_capacity
WK_GATEWAY_RUNTIME_ASYNC_AUTH_QUEUE_CAPACITY
int
Maximum queued CONNECT authentications; a non-positive value uses 8192, and a full queue rejects new CONNECT authentication requests.
gateway.runtime_async_pool_release_timeout
WK_GATEWAY_RUNTIME_ASYNC_POOL_RELEASE_TIMEOUT
duration
Maximum graceful-release wait for asynchronous worker pools during shutdown; a non-positive value uses 100ms.
Maximum payload bytes in one Gateway SEND micro-batch; 0 uses 524288.
gateway.listeners
WK_GATEWAY_LISTENERS
object_list
Client listener list: name, network, address, transport, and protocol are required; path and proxy_protocol_trusted_cidrs are optional; direct/PROXY v1/v2 detection is enabled by default, with omitted or empty CIDRs accepting unverified address assertions from any peer; names and addresses must each be unique. Omitted opens WKProto TCP on 0.0.0.0:5100 and WSMux on 0.0.0.0:5200; an explicit empty list (including JSON null in the environment) disables Gateway.
gateway.send_timeout
WK_GATEWAY_SEND_TIMEOUT
duration
Maximum duration allowed for one message send initiated by Gateway; a non-positive value uses 5s.
This capability is currently under Unreleased; use a target binary containing
proxy_protocol_trusted_cidrs. Older binaries require disabling the PROXY preface
at the upstream proxy.
Every TCP or WebSocket listener automatically accepts plain client traffic and
PROXY protocol v1/v2 on the same port by default, without SDK changes or a proxy
vendor selector. proxy_protocol_trusted_cidrs is an optional source filter.
Omitted or empty accepts headers from any peer: connection information and logs
can contain client-declared addresses whose authenticity has not been verified.
Built-in token authentication and message permissions do not rely on those addresses.
To restrict header sources to controlled proxies, configure the filter as follows:
[[gateway.listeners]]name = "tcp-wkproto"network = "tcp"address = "0.0.0.0:5100"transport = "gnet"protocol = "wkproto"# Replace with the actual controlled proxy egress IP/CIDR.proxy_protocol_trusted_cidrs = ["192.0.2.10/32"]
Use the same field on a network = "websocket" listener. At most 128 IPv4/IPv6
CIDRs are accepted; invalid CIDRs fail configuration loading. WK_GATEWAY_LISTENERS
accepts this field inside its JSON listener objects and replaces the entire
listener list, including all trust rules.
When setting the filter, match the actual TCP peer as seen by WuKongIM, including
any SNAT. Use controlled proxy egress networks. A trusted proxy must prepend its own header
on forwarded connections; a transparent TCP relay that passes arbitrary client
prefixes through is not a safe trusted source. Listeners with nonempty CIDRs reject
recognized PROXY headers from other peers. Direct traffic remains accepted.
The upstream proxy must support and send the protocol; WuKongIM cannot recover
an address that it did not receive. Parsing occurs before authentication and,
for WebSocket, before HTTP Upgrade. TLS/WSS termination belongs to the upstream
proxy; X-Forwarded-For is not used by this feature. It does not change the HTTP
API, Manager, cluster RPC, advertised routes, or token authentication.
Detection has an absolute five-second deadline from TCP accept, including clients
that send no data. Incomplete, malformed, or oversized headers close the connection.
The v1 limit is 107 bytes; v2 permits 4096 bytes including the fixed header and
optional TLVs. TLV values are ignored; supported TCP address blocks validate TLV
framing. UNKNOWN, LOCAL, and valid unsupported v2 address transports retain
the physical endpoints. Sessions use the asserted client source as RemoteAddr,
retain the actual listener as LocalAddr, and expose the physical proxy through
gateway.peer_addr; connection debug logs include peerAddr when it differs.
Enforces receiver-side allowlist checks for person messages; disabled by default for compatibility.
message.cmd_channel_suffix
WK_MESSAGE_CMD_CHANNEL_SUFFIX
string
Reserved command-channel suffix; omitted or empty uses ____cmd. Only ASCII letters, digits, underscores and hyphens are allowed; reserve it from business channel IDs. Must match on every node and requires restart. Choose before first use: changing it does not migrate stored command channels or UID bindings and can make pending commands inaccessible.
message.system_uid
WK_MESSAGE_SYSTEM_UID
string
Primary system account UID used when trusted sends omit a sender; omitted or empty uses ____system. Every cluster node must use the same value.
message.system_device_id
WK_MESSAGE_SYSTEM_DEVICE_ID
string
Device ID for trusted system sessions; omitted or empty uses ____device, so an empty value cannot disable recognition. Such sessions may bypass channel-type send permissions after the send-ban check.
message.permission_cache_ttl
WK_MESSAGE_PERMISSION_CACHE_TTL
duration
Cache lifetime for permission, membership, and missing-channel reads; 0 disables caching.
Timeout for Gateway session route activation against the UID authority; 0 uses 3s.
presence.touch_flush_interval
WK_PRESENCE_TOUCH_FLUSH_INTERVAL
duration
Interval for flushing local connection activity to UID authorities; 0 uses 1s.
presence.touch_batch_size
WK_PRESENCE_TOUCH_BATCH_SIZE
int
Maximum local touched routes processed per flush chunk; 0 uses 512.
presence.touch_max_routes_per_flush
WK_PRESENCE_TOUCH_MAX_ROUTES_PER_FLUSH
int
Maximum dirty routes processed across all chunks in one flush; omitted uses 65536, while an explicit value must be positive and at least presence.touch_batch_size.
presence.route_ttl
WK_PRESENCE_ROUTE_TTL
duration
How long a UID authority keeps a route alive after its latest activity; 0 uses 90s.
