Server Configuration

WuKongIM supports both YAML configuration files and environment variables. Environment variables take precedence over configuration files.

Basic Server Configuration

# Basic server configuration
mode: "release"                       # Run mode: debug, test, release, bench
addr: "tcp://0.0.0.0:5100"           # TCP listen address
httpAddr: "0.0.0.0:5001"             # HTTP API listen address
wsAddr: "ws://0.0.0.0:5200"          # WebSocket listen address
wssAddr: "wss://0.0.0.0:5210"        # Secure WebSocket address
rootDir: "./wukongimdata"             # Data storage directory
ginMode: "release"                    # Gin framework mode
deadlockCheck: false                  # Deadlock detection
pprofOn: false                        # pprof performance analysis

WK_MODE=release
WK_ADDR=tcp://0.0.0.0:5100
WK_HTTPADDR=0.0.0.0:5001
WK_WSADDR=ws://0.0.0.0:5200
WK_WSSADDR=wss://0.0.0.0:5210
WK_ROOTDIR=./wukongimdata
WK_GINMODE=release
WK_DEADLOCKCHECK=false
WK_PPROFON=false

Admin Authentication Configuration

# Admin authentication configuration
tokenAuthOn: false                    # Enable admin token authentication
managerUID: "____manager"             # Admin user ID
managerToken: ""                      # Admin API token
whitelistOffOfPerson: true            # Disable personal whitelist verification

WK_TOKENAUTHON=false
WK_MANAGERUID=____manager
WK_MANAGERTOKEN=
WK_WHITELISTOFFOFPERSON=true

External Access Configuration

# External access configuration
external:
  ip: ""                              # External IP address
  tcpAddr: ""                         # External TCP address
  wsAddr: ""                          # External WebSocket address
  wssAddr: ""                         # External secure WebSocket address
  monitorAddr: ""                     # External monitor address
  apiUrl: ""                          # External API URL

WK_EXTERNAL_IP=
WK_EXTERNAL_TCPADDR=
WK_EXTERNAL_WSADDR=
WK_EXTERNAL_WSSADDR=
WK_EXTERNAL_MONITORADDR=
WK_EXTERNAL_APIURL=

SSL/TLS Configuration

# SSL/TLS configuration
wssConfig:
  certFile: ""                        # SSL certificate file path
  keyFile: ""                         # SSL private key file path

WK_WSSCONFIG_CERTFILE=
WK_WSSCONFIG_KEYFILE=

Logging Configuration

# Logging configuration
logger:
  level: 0                            # Log level: 0=auto, 1=debug, 2=info, 3=warn, 4=error
  dir: "./logs"                       # Log directory
  lineNum: false                      # Show line numbers

WK_LOGGER_LEVEL=0
WK_LOGGER_DIR=./logs
WK_LOGGER_LINENUM=false

Monitoring Configuration

# Monitoring configuration
monitor:
  on: true                            # Enable monitoring
  addr: "0.0.0.0:5300"               # Monitor listen address

# Demo interface configuration
demo:
  on: true                            # Enable demo interface
  addr: "0.0.0.0:5172"               # Demo interface address

WK_MONITOR_ON=true
WK_MONITOR_ADDR=0.0.0.0:5300
WK_DEMO_ON=true
WK_DEMO_ADDR=0.0.0.0:5172

Channel Configuration

# Channel configuration
channel:
  cacheCount: 1000                    # Channel cache count
  createIfNoExist: true               # Auto-create non-existent channels
  subscriberCompressOfCount: 0        # Subscriber compression threshold

# Temporary channel configuration
tmpChannel:
  suffix: "@tmp"                      # Temporary channel suffix
  cacheCount: 500                     # Temporary channel cache count

WK_CHANNEL_CACHECOUNT=1000
WK_CHANNEL_CREATEIFNOEXIST=true
WK_CHANNEL_SUBSCRIBERCOMPRESSOFCOUNT=0
WK_TMPCHANNEL_SUFFIX=@tmp
WK_TMPCHANNEL_CACHECOUNT=500

User Authentication Configuration

# User authentication configuration
auth:
  on: true                            # Enable user authentication
  kind: "jwt"                         # Authentication method: jwt, none
  users:                              # User list (for username/password auth)
    - "admin:pwd:*"                   # Admin user
    - "guest:guest:[*:r]"             # Read-only user

# JWT configuration
jwt:
  secret: ""                          # JWT secret (32-character random string)
  expire: "30d"                       # Token expiration time

WK_AUTH_ON=true
WK_AUTH_KIND=jwt
WK_AUTH_USERS="admin:pwd:* guest:guest:[*:r]"
WK_JWT_SECRET=
WK_JWT_EXPIRE=30d

Webhook Configuration

# Webhook configuration
webhook:
  httpAddr: ""                        # Webhook HTTP address
  grpcAddr: ""                        # Webhook gRPC address
  msgNotifyEventPushInterval: "500ms" # Message notification push interval
  msgNotifyEventRetryMaxCount: 5      # Max retry count for push failures
  msgNotifyEventCountPerPush: 100     # Message count limit per push
  focusEvents:                        # Focused event types
    - "msg.offline"
    - "msg.notify"
    - "user.onlinestatus"

WK_WEBHOOK_HTTPADDR=
WK_WEBHOOK_GRPCADDR=
WK_WEBHOOK_MSGNOTIFYEVENTPUSHINTERVAL=500ms
WK_WEBHOOK_MSGNOTIFYEVENTRETRYMAXCOUNT=5
WK_WEBHOOK_MSGNOTIFYEVENTCOUNTperpush=100
WK_WEBHOOK_FOCUSEVENTS="msg.offline msg.notify user.onlinestatus"

Datasource Configuration

# Datasource configuration
datasource:
  addr: ""                            # Datasource address
  channelInfoOn: false                # Enable channel info datasource

WK_DATASOURCE_ADDR=
WK_DATASOURCE_CHANNELINFOON=false

Conversation Configuration

# Recent conversation configuration
conversation:
  on: true                            # Enable recent conversations
  cacheExpire: "1d"                   # Cache expiration time
  syncInterval: "5m"                  # Save interval
  syncOnce: 100                       # Sync save count
  userMaxCount: 1000                  # Max conversation count per user

WK_CONVERSATION_ON=true
WK_CONVERSATION_CACHEEXPIRE=1d
WK_CONVERSATION_SYNCINTERVAL=5m
WK_CONVERSATION_SYNCONCE=100
WK_CONVERSATION_USERMAXCOUNT=1000

Message Retry Configuration

# Message retry configuration
messageRetry:
  interval: "60s"                     # Retry interval
  scanInterval: "5s"                  # Scan interval
  maxCount: 5                         # Max retry count

# User message queue configuration
userMsgQueueMaxSize: 0                # User message queue max size, 0 for unlimited

WK_MESSAGERETRY_INTERVAL=60s
WK_MESSAGERETRY_SCANINTERVAL=5s
WK_MESSAGERETRY_MAXCOUNT=5
WK_USERMSGQUEUEMAXSIZE=0

Tracing Configuration

# Data tracing configuration
trace:
  prometheusApiUrl: ""                # Prometheus API URL

WK_TRACE_PROMETHEUSAPIURL=

Cluster Configuration

# Cluster configuration
cluster:
  nodeId: 1001                        # Node ID
  addr: "tcp://0.0.0.0:11110"        # Distributed listen address
  serverAddr: ""                      # Inter-node communication address
  apiUrl: ""                          # Node HTTP address
  slotCount: 64                       # Slot count
  slotReplicaCount: 3                 # Slot replica count
  channelReplicaCount: 3              # Channel replica count
  initNodes:                          # Initial node list
    - "1001@192.168.1.12:11110"
    - "1002@192.168.1.13:11110"
    - "1003@192.168.1.14:11110"
  seed:                               # Cluster seed nodes
    - "1001@192.168.1.12:11110"

WK_CLUSTER_NODEID=1001
WK_CLUSTER_ADDR=tcp://0.0.0.0:11110
WK_CLUSTER_SERVERADDR=
WK_CLUSTER_APIURL=
WK_CLUSTER_SLOTCOUNT=64
WK_CLUSTER_SLOTREPLICACOUNT=3
WK_CLUSTER_CHANNELREPLICACOUNT=3
WK_CLUSTER_INITNODES="1001@192.168.1.12:11110 1002@192.168.1.13:11110 1003@192.168.1.14:11110"
WK_CLUSTER_SEED="1001@192.168.1.12:11110"

Plugin Configuration

# Plugin configuration
plugin:
  socketPath: "./wukongimdata/1/wukongim.sock"  # Plugin Unix Socket address
  install:                                      # Default installed plugin list
    - "https://gitee.com/WuKongDev/plugins/releases/download/latest/wk.plugin.ai-example-${os}-${arch}.wkp"
    - "https://gitee.com/WuKongDev/plugins/releases/download/latest/wk.plugin.ai-volcengine-${os}-${arch}.wkp"

WK_PLUGIN_SOCKETPATH=./wukongimdata/1/wukongim.sock
WK_PLUGIN_INSTALL="https://gitee.com/WuKongDev/plugins/releases/download/latest/wk.plugin.ai-example-${os}-${arch}.wkp https://gitee.com/WuKongDev/plugins/releases/download/latest/wk.plugin.ai-volcengine-${os}-${arch}.wkp"

Configuration Examples

Production Environment

# Production configuration
mode: "release"
tokenAuthOn: true
managerUID: "admin"
managerToken: "prod-secure-token-2024"

external:
  ip: "203.0.113.1"
  wssAddr: "wss://yourdomain.com:5210"

wssConfig:
  certFile: "/etc/letsencrypt/live/yourdomain.com/fullchain.pem"
  keyFile: "/etc/letsencrypt/live/yourdomain.com/privkey.pem"

logger:
  level: 3
  dir: "/var/log/wukongim"

auth:
  on: true
  kind: "jwt"

jwt:
  secret: "your-production-jwt-secret-32-chars"
  expire: "7d"

monitor:
  on: true

demo:
  on: false

Development Environment

# Development configuration
mode: "debug"
tokenAuthOn: false

logger:
  level: 1
  lineNum: true

auth:
  on: true
  kind: "jwt"
  users:
    - "dev:dev123:*"
    - "test:test123:[*:r]"

jwt:
  secret: "dev-jwt-secret-for-testing-only"
  expire: "24h"

monitor:
  on: true

demo:
  on: true

Docker Compose Configuration

version: '3.7'
services:
  wukongim:
    image: wukongim/wukongim:latest
    environment:
      # Basic configuration
      - "WK_MODE=release"
      - "WK_TOKENAUTHON=true"
      - "WK_MANAGERTOKEN=secure-token-123"

      # External access
      - "WK_EXTERNAL_IP=203.0.113.1"
      - "WK_EXTERNAL_WSSADDR=wss://yourdomain.com:5210"

      # SSL configuration
      - "WK_WSSCONFIG_CERTFILE=/etc/ssl/certs/wukongim.crt"
      - "WK_WSSCONFIG_KEYFILE=/etc/ssl/private/wukongim.key"

      # User authentication
      - "WK_AUTH_ON=true"
      - "WK_AUTH_KIND=jwt"
      - "WK_JWT_SECRET=your-secure-jwt-secret-32-characters"

    ports:
      - "5001:5001"   # HTTP API
      - "5100:5100"   # TCP
      - "5200:5200"   # WebSocket
      - "5210:5210"   # WSS
      - "5300:5300"   # Monitor

    volumes:
      - "./data:/root/wukongim"
      - "./certs:/etc/ssl/certs:ro"
      - "./private:/etc/ssl/private:ro"

Environment Variable Rules

Prefix: All environment variables start with WK_
Hierarchy: Use underscore _ to separate configuration levels
Case: Use all uppercase letters
Array Format: Use space-separated values, e.g., WK_AUTH_USERS="user1:pass1 user2:pass2"
Boolean Values: Use true or false
Priority: Environment variables > Configuration file > Default values

Configuration Validation

Validate configuration before startup:

# Check configuration syntax
./wukongim --config wukongim.yaml --validate

# Check configuration on startup
./wukongim --config wukongim.yaml --check-config

Security Recommendations

Production environments must enable tokenAuthOn
Use 32-character random string for JWT secret
Regularly rotate admin tokens and JWT secrets
Set SSL certificate file permissions to 600
Disable unnecessary demo interfaces and debug features

Installation & Configuration

Core Concepts

Learning

Server Configuration

Basic Server Configuration

Admin Authentication Configuration

External Access Configuration

SSL/TLS Configuration

Logging Configuration

Monitoring Configuration

Channel Configuration

User Authentication Configuration

Webhook Configuration

Datasource Configuration

Conversation Configuration

Message Retry Configuration

Tracing Configuration

Cluster Configuration

Plugin Configuration

Configuration Examples

Production Environment

Development Environment

Docker Compose Configuration

Environment Variable Rules

Configuration Validation

Security Recommendations

​Basic Server Configuration

​Admin Authentication Configuration

​External Access Configuration

​SSL/TLS Configuration

​Logging Configuration

​Monitoring Configuration

​Channel Configuration

​User Authentication Configuration

​Webhook Configuration

​Datasource Configuration

​Conversation Configuration

​Message Retry Configuration

​Tracing Configuration

​Cluster Configuration

​Plugin Configuration

​Configuration Examples

​Production Environment

​Development Environment

​Docker Compose Configuration

​Environment Variable Rules

​Configuration Validation

​Security Recommendations

Basic Server Configuration

Admin Authentication Configuration

External Access Configuration

SSL/TLS Configuration

Logging Configuration

Monitoring Configuration

Channel Configuration

User Authentication Configuration

Webhook Configuration

Datasource Configuration

Conversation Configuration

Message Retry Configuration

Tracing Configuration

Cluster Configuration

Plugin Configuration

Configuration Examples

Production Environment

Development Environment

Docker Compose Configuration

Environment Variable Rules

Configuration Validation

Security Recommendations