V2Ray Configuration JSON Structure Explained: A Complete Breakdown

The V2Ray configuration JSON uses eight top-level sections—log, inbounds, outbounds, routing, dns, policy, stats, and reverse—to control proxy behavior, traffic routing, and connection policies.

V2Ray's configuration is a single JSON file that orchestrates every aspect of proxy operation, from client-side listeners to server-side transport encryption. This guide dissects the schema using real examples from the bannedbook/fanqiang repository, including the default client configuration at fqnews/core/src/main/assets/v2ray_config.json and the server-side template at v2ss/server-cfg/v2/config.json.

Core Configuration Sections

Understanding each top-level key is essential for customizing V2Ray deployments. The configuration follows a predictable pattern: inbounds receive traffic, routing decides where it goes, and outbounds deliver it to its destination.

log: Controlling Output Verbosity

The log section manages diagnostic output. The loglevel field accepts "debug", "info", "warning", or "error".

{
  "log": {
    "loglevel": "warning"
  }
}

Setting loglevel to "warning" strikes a balance—errors and significant events surface without overwhelming logs with routine connection details. For troubleshooting connection failures, temporarily switch to "debug" in fqnews/core/src/main/assets/v2ray_config.json.

inbounds: Entry Points for Client Traffic

The inbounds array defines listening ports and protocols. The default configuration specifies two listeners:

• SOCKS5 proxy on port 10808
• HTTP proxy on port 58300

{
  "inbounds": [
    {
      "tag": "socks",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true,
        "userLevel": 8
      },
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls"]
      }
    },
    {
      "tag": "http",
      "port": 58300,
      "protocol": "http",
      "settings": {
        "userLevel": 8
      },
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls"]
      }
    }
  ]
}

The tag field creates a reference for routing rules. Sniffing examines traffic to detect HTTP and TLS protocols—this enables intelligent routing based on destination domains rather than just IP addresses.

outbounds: Destination Definitions

The outbounds array configures where traffic travels after processing. The default V2Ray configuration JSON structure includes three critical outbounds:

Tag	Protocol	Purpose
proxy	vmess	Encrypted tunnel to remote V2Ray server
direct	freedom	Bypass proxy for specified traffic
block	blackhole	Drop unwanted connections

The proxy outbound demonstrates V2Ray's VMess protocol with fallback Shadowsocks support:

{
  "tag": "proxy",
  "protocol": "vmess",
  "settings": {
    "vnext": [
      {
        "address": "your-server.com",
        "port": 443,
        "users": [
          {
            "id": "uuid-here",
            "alterId": 64,
            "level": 0
          }
        ]
      }
    ],
    "servers": [
      {
        "address": "fallback-server.com",
        "method": "aes-256-gcm",
        "ota": true,
        "password": "password-here",
        "port": 8388,
        "level": 1
      }
    ]
  },
  "streamSettings": {
    "network": "tcp"
  },
  "mux": {
    "enabled": false
  }
}

StreamSettings control transport-layer behavior—options include "tcp", "ws" (WebSocket), "kcp", and "quic". The mux object enables connection multiplexing; disabling it ("enabled": false) simplifies debugging at the cost of connection efficiency.

routing: Traffic Direction Rules

The routing section implements the decision engine. The default configuration uses IPIfNonMatch strategy with no rules:

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": []
  }
}

The domainStrategy options determine how V2Ray resolves domains:

• "AsIs" — Pass domain directly to outbound without resolution
• "IPIfNonMatch" — Resolve to IP only if no domain rule matches (default, balances performance and flexibility)
• "IPOnDemand" — Resolve all domains to IP before routing

Empty rules means all traffic defaults to the first outbound (proxy). Production deployments typically populate this array with geo-based routing:

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "outboundTag": "direct",
        "domain": ["geosite:cn", "geosite:private"]
      },
      {
        "type": "field",
        "outboundTag": "proxy",
        "network": "tcp,udp"
      }
    ]
  }
}

dns: Resolver Configuration

The dns object specifies custom name servers. When empty (as in the default), V2Ray uses system DNS:

{
  "dns": {
    "hosts": {},
    "servers": []
  }
}

Populate servers with DNS-over-HTTPS endpoints or specific IPs to prevent DNS leaks. The hosts map enables local overrides—useful for blocking advertising domains or routing internal services.

policy: Connection Limits and Timeouts

Global and per-user resource constraints live in policy:

{
  "policy": {
    "levels": {
      "8": {
        "handshake": 4,
        "connIdle": 300,
        "uplinkOnly": 2,
        "downlinkOnly": 5
      }
    },
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true
    }
  }
}

The levels object maps userLevel values (from inbound settings) to specific limits:

• handshake — Connection establishment timeout (seconds)
• connIdle — Idle connection timeout
• uplinkOnly / downlinkOnly — Buffer timeouts when data flows one direction

The system subsection enables traffic statistics collection for monitoring dashboards.

stats and reverse: Advanced Features

The stats object is reserved for runtime metrics when enabled. V2Ray exposes these via API for external collection.

The reverse section configures reverse proxy bridges—rarely used in standard client configurations but essential for corporate penetration scenarios documented in v2ss/V2Ray之TLS+WebSocket翻墙方法.md.

Complete Minimal Configuration

A functional client setup requires only log, inbounds, and outbounds:

{
  "log": { "loglevel": "warning" },
  "inbounds": [
    {
      "tag": "socks",
      "port": 1080,
      "protocol": "socks",
      "settings": { "auth": "noauth", "udp": true }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "proxy",
      "protocol": "vmess",
      "settings": {
        "vnext": [{
          "address": "server.example.com",
          "port": 443,
          "users": [{
            "id": "a-b-c-d",
            "alterId": 0,
            "security": "auto"
          }]
        }]
      },
      "streamSettings": {
        "network": "ws",
        "security": "tls",
        "tlsSettings": {
          "allowInsecure": false,
          "serverName": "server.example.com"
        },
        "wsSettings": {
          "path": "/v2ray"
        }
      }
    }
  ],
  "routing": {
    "rules": [
      { "type": "field", "outboundTag": "direct", "ip": ["geoip:private"] }
    ]
  }
}

This configuration from the bannedbook/fanqiang repository patterns enables WebSocket-over-TLS with private IP direct routing—optimal for circumventing deep packet inspection.

How Traffic Flows Through the JSON Structure

1. Client connects to SOCKS5 port 10808 (or HTTP 8080)
2. Sniffing detects protocol if enabled
3. Routing engine evaluates rules against destination
4. Matched outbound processes the connection:
   • proxy → Encrypt via VMess, transmit through streamSettings transport
   • direct → Unmodified exit to destination
   • block → Connection terminated with configured response
5. Policy limits enforce timeouts and rate constraints per userLevel

Key Configuration Files in bannedbook/fanqiang

File Path	Purpose
fqnews/core/src/main/assets/v2ray_config.json	Android client default—demonstrates dual inbound (SOCKS+HTTP) setup
v2ss/server-cfg/v2/config.json	Server template deployed by one-click installer
v2ss/V2ray官方一键安装脚本.md	Documentation for automated server provisioning
v2ss/V2Ray之TLS+WebSocket翻墙方法.md	Transport customization for WebSocket deployments
v2ss/V2Ray之TLS+WebSocket+Nginx+CDN配置方法.md	Enterprise-grade configuration with CDN fronting

Summary

• The V2Ray configuration JSON structure organizes proxy behavior into eight top-level sections with clear responsibilities
• inbounds and outbounds form the traffic pipeline; routing controls the switching logic
• streamSettings within outbounds determines transport encryption and obfuscation—critical for bypassing detection
• policy enforces resource limits using the userLevel reference system
• Real-world configurations in bannedbook/fanqiang demonstrate progression from basic SOCKS proxy to TLS+WebSocket+CDN deployments

Frequently Asked Questions

What is the minimum valid V2Ray configuration JSON?

A functional configuration requires three sections: log (optional but recommended), inbounds with at least one listener, and outbounds with at least one destination. The "freedom" protocol creates a transparent forwarding outbound that requires no server infrastructure—useful for testing routing rules locally.

How does domainStrategy affect routing performance?

"IPIfNonMatch" avoids DNS resolution until necessary, preserving latency for domain-based rules. "IPOnDemand" resolves everything upfront, enabling precise IP-based routing at the cost of additional queries. "AsIs" delegates all resolution to the outbound server, fastest when the remote handles routing intelligence.

Why does the default configuration include both vmess and shadowsocks in settings?

The vnext array (VMess) and servers array (Shadowsocks) provide protocol fallback. If VMess connection fails, V2Ray attempts Shadowsocks negotiation. This redundancy appears in fqnews/core/src/main/assets/v2ray_config.json for compatibility with mixed infrastructure during server transitions.

What security considerations apply to streamSettings?

Always configure tlsSettings with "allowInsecure": false to prevent man-in-the-middle attacks. The serverName field must match the TLS certificate's CN or SAN. For WebSocket transports, combine with wsSettings.path to randomize the endpoint and resist active probing—patterns documented in v2ss/V2Ray之TLS+WebSocket+Nginx+CDN配置方法.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}