常用配置

先按任务找配置。WK_ 环境变量覆盖 TOML；完整字段、环境变量映射与默认值可展开。

高频配置

启动节点

用途	配置与验收
身份	node.id 非零、集群内唯一；有数据后不再修改
磁盘	node.data_dir 节点独占、可写，使用持久化且受备份保护的磁盘
互连	cluster.listen_addr 本机监听；远端连接用真实可达地址，不能用通配地址

静态 cluster.nodes 与非空 cluster.seeds 二选一。环境变量列表用 JSON 整体替换。

接入客户端

用途	配置与验收
客户端	gateway.listeners 省略时监听所有接口：TCP 5100 / WSMux 5200；显式空列表关闭 Gateway
业务 API	api.listen_addr 省略或留空不启动 WuKongIM HTTP API；与 Gateway、Manager 分开设置

保持 gateway.token_auth_on=true。CONNECT 按相同 UID + device_flag 精确匹配已存设备 Token；空值、缺记录或不匹配返回 ReasonAuthFail。WuKongIM HTTP API 仍需受信任网络或外部鉴权。

打开管理后台

用途	配置与验收
监听	manager.listen_addr 省略或留空不启动 Manager；用回环 / 管理内网，通过 SSH 或 HTTPS 代理访问
JWT	manager.auth_on 省略默认 false；生产设为 true，同时提供 manager.jwt_secret 与 manager.users

验收： 替换示例凭据，登录后只授予所需资源和动作。

查看日志

log.level 默认 info，可选 debug、info、warn、error。排障临时提高到 debug，结束后恢复，避免长期增加生产日志量。

全部高频字段、默认值与环境变量映射

本页只保留启动、客户端接入和日常运维中最常查阅的配置项。每项均可通过 TOML 或环境变量设置；同时提供时，环境变量会覆盖配置文件。全部字段及精确语义见配置参考。

配置（TOML / 环境变量）	作用	默认与注意事项
node.id WK_NODE_ID	标识当前节点，是消息与集群状态使用的稳定节点身份。	启动必填，必须非零且在集群内唯一；产生数据后不要修改。
node.data_dir WK_NODE_DATA_DIR	保存当前节点的 Controller、Slot、Channel 等持久化数据。	启动必填；目录必须可写，并应使用持久化、受备份保护的磁盘。
cluster.listen_addr WK_CLUSTER_LISTEN_ADDR	监听节点之间的 Cluster RPC。	启动必填；可绑定 0.0.0.0，但提供给其他节点连接的地址必须可达且不能是通配地址。
cluster.nodes WK_CLUSTER_NODES	定义静态 Controller 投票节点列表，元素包含节点 id 和集群地址 addr。	同时未配置 cluster.seeds 时，省略或使用空列表会回退为隐式单节点集群；不能与非空 cluster.seeds 同时使用。环境变量必须使用 JSON，并替换整张列表。
cluster.slot_replica_n WK_CLUSTER_SLOT_REPLICA_N	设置集群首次初始化时每个 Slot Raft Group 的投票副本数。	0 在静态拓扑按投票节点数推导，种子加入时使用 1；已有集群以 Controller 持久状态为准。
gateway.listeners WK_GATEWAY_LISTENERS	定义客户端使用的 TCP 或 WebSocket 监听器。	省略时开放 0.0.0.0:5100 WKProto TCP 和 0.0.0.0:5200 WSMux；显式空列表会关闭 Gateway。环境变量必须使用 JSON。
gateway.token_auth_on WK_GATEWAY_TOKEN_AUTH_ON	要求 CONNECT Token 与相同 UID、device_flag 的已存设备 Token 完全匹配。	默认为 true；空 Token、缺少记录或不匹配会返回 ReasonAuthFail。仅在受控兼容迁移期间临时关闭。
api.listen_addr WK_API_LISTEN_ADDR	监听 WuKongIM HTTP API，并承载健康检查及按开关启用的指标、调试等 HTTP 路由。	省略或留空时不启动该 HTTP 服务；它不会创建客户端 Gateway 或 Manager 监听器。
manager.listen_addr WK_MANAGER_LISTEN_ADDR	监听独立的 Manager 管理服务。	省略或留空时不启动 Manager；绑定回环或管理内网地址，通过 SSH 转发或内网 HTTPS 代理访问，并启用认证。
manager.auth_on WK_MANAGER_AUTH_ON	要求 Manager 路由使用 JWT 登录认证。	省略时为 false；设为 true 时必须同时提供 manager.jwt_secret 和 manager.users。
log.level WK_LOG_LEVEL	设置应用记录的最低日志级别。	默认 info；可选 debug、info、warn、error。生产排障结束后应避免长期使用 debug。

继续查阅

• 配置文件查找顺序、环境变量覆盖和列表替换规则见配置概览。
• 多节点种子加入、频道副本、指标、Webhook 等配置见配置参考。