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
wukongim config init creates a security-oriented installation baseline and explicitly disables Diagnostics and Plugin. wukongim.toml.example is a loadable development and tuning baseline. Neither 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.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.
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.
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 is optional; 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.
Enforces receiver-side allowlist checks for person messages; disabled by default for compatibility.
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.
