# V2Ray Configuration JSON Structure Explained: A Complete Breakdown

> Understand the V2Ray configuration JSON structure with this complete breakdown. Explore log, inbounds, outbounds, routing, and more to control proxy behavior and traffic.

- Repository: [如何翻墙/fanqiang](https://github.com/bannedbook/fanqiang)
- Tags: deep-dive
- Published: 2026-09-06

---

**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](https://github.com/bannedbook/fanqiang) repository, including the default client configuration at [`fqnews/core/src/main/assets/v2ray_config.json`](https://github.com/bannedbook/fanqiang/blob/main/fqnews/core/src/main/assets/v2ray_config.json) and the server-side template at [`v2ss/server-cfg/v2/config.json`](https://github.com/bannedbook/fanqiang/blob/main/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"`.

```json
{
  "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`](https://github.com/bannedbook/fanqiang/blob/main/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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`:

```json
{
  "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`:

```json
{
  "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`](https://github.com/bannedbook/fanqiang/blob/main/fqnews/core/src/main/assets/v2ray_config.json) | Android client default—demonstrates dual inbound (SOCKS+HTTP) setup |
| [`v2ss/server-cfg/v2/config.json`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/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`.