V2Ray Complete Guide for Beginners

Core concepts: understand the relationship between clients, cores and configuration

A graphical client is not the protocol itself

Before getting started, separate a few names that are often used interchangeably. V2Ray usually refers to the technology ecosystem developed around Project V, and users also use it as shorthand for a collection of proxy protocols, cores and graphical clients. v2rayN, v2rayNG and v2flyNG are graphical clients for different platforms. They store configuration, switch servers, control the system proxy, display logs and pass organized parameters to the core. Xray and V2Fly belong to the core family; they handle connection establishment, protocol encoding and decoding, transport layers and route matching. Once this relationship is clear, you can tell whether a problem lies in the interface, configuration data, system takeover or core runtime.

A protocol describes how a client and server exchange the information they need, such as VMess, VLESS or Trojan. A transport describes how data is carried, such as TCP, WebSocket or gRPC. Security layers such as TLS and REALITY occupy another part of the stack. A working node is not defined by its protocol name alone; it combines an address, port, user ID, transport, security layer, domain and other parameters. Any mismatch with the server can cause the connection to fail. Do not guess parameters from a name or mechanically copy fields from one node to another.

Where configuration comes from and where it goes

There are two common configuration sources. A single-node share link is useful for temporarily adding one configuration, while a subscription URL manages a set of nodes maintained by a provider. After reading a subscription, the client converts its entries into internal configuration and places them in a subscription group. At connection time, the selected node, proxy mode, routing rules and local port together produce the runtime configuration. This is why updating a subscription is not the same as starting a connection: an update refreshes the list; you still need to select a node and start the connection before the new configuration is used in the current session.

System proxy and TUN operate at different levels. A system proxy changes the proxy settings supplied by the operating system, so only apps that honor those settings send requests to the client. TUN creates a virtual network interface and receives traffic at a lower level, giving it broader coverage but also requiring more from permissions, routing and DNS. When starting out, learn the system proxy first, verify that the node and subscription work, and only then decide whether TUN is necessary. This keeps the troubleshooting scope manageable.

Troubleshoot by layer

Systematic troubleshooting should start with the shortest path. First verify that the client starts normally, then confirm that the subscription can be read. Next select a node and check whether the core starts successfully, and finally verify that app traffic enters the proxy. If the client exits immediately, check the runtime environment, directory permissions and leftover processes. If a subscription update fails, check the URL format, network reachability and system time. If the core is running but the browser shows no change, check the system proxy and the browser's own settings. If only a particular app fails, determine whether it ignores the system proxy and whether TUN is needed.

A latency test is only a screening signal; it cannot by itself prove that a node is fully usable. Different tests may check only TCP connection setup, a handshake or a specific target, and results are affected by the local network, test target and momentary load. A more reliable assessment is to confirm a successful configuration handshake, test access with the app you actually need and check the logs for repeated retries, DNS failures or routing rejections. The layered model of client, configuration, core, system and app is the foundation for every chapter that follows.

Choose a client: balance platform, core and use case

Choose v2rayN first on desktop

For Windows, macOS and Linux desktops, start with v2rayN. It brings subscription groups, server lists, the system proxy, routing rules, TUN and logs into one interface, making it a strong primary client for long-term maintenance. Desktop users often need to handle browsers, development tools, office apps and command-line programs at the same time, and v2rayN's grouping and routing features make it easier to build a stable workflow. Windows users will also find a desktop edition and a classic WPF edition on the download page. The desktop edition uses a newer cross-platform interface, while the classic WPF edition suits users who prefer a traditional Windows interface. Choose one for regular use; there is no need to run both.

When downloading for macOS, choose an Apple Silicon or Intel package according to your processor. On Linux, select deb or rpm based on your distribution and then choose between x64 and arm64. Choosing the wrong architecture usually causes installation or startup failures, not network problems. Checking system information before installing is therefore more effective than repeatedly changing nodes afterward. All installation options are listed on the installation packages page, organized by platform with the relevant selection guidance.

v2rayNG and v2flyNG on Android

v2rayNG is the first choice on Android. Based on the Xray core, it suits users who need common protocols, subscription management, per-app proxying and system VPN takeover. Packages usually come in arm64 and universal variants; most recent devices use arm64. If you cannot confirm the device architecture, the universal package offers broader coverage but is usually larger. On the first connection, Android asks for permission to establish a VPN connection, which is required for handing app traffic to the client. Permission only allows a local virtual interface to be created; it does not mean that a subscription has been imported or a node is usable.

v2flyNG is an alternative Android client centered on the V2Fly core. It suits configurations that specifically depend on V2Fly behavior or users who want to compare different core implementations on the same platform. Do not judge which client is faster by its name alone; real-world performance depends on the protocol, local network, remote status and core compatibility. For most first-time Android setups, a stable connection is easier to achieve with v2rayNG. Switch to v2flyNG only when you know the configuration source, supported protocols and core requirements.

Do not switch clients instead of locating the problem

When a connection fails, installing several clients in succession usually does not narrow the cause. A better approach is to keep one client fixed and record whether the subscription updates, whether the core starts and where the logs stop. If every node in one subscription fails, first check the subscription status, system time, network and configuration compatibility. If only one node fails, compare its protocol and transport fields with a working node. If the system proxy works but TUN does not, the node path is probably fine; investigate permissions, DNS and routing instead.

When migrating clients, avoid overwriting the existing configuration directory directly. First export or record subscription groups, routing rules and local ports. Then close the old client and its core processes, confirm that the system proxy has been restored and start the new client. Two clients taking over the system proxy or listening on the same port can cause seemingly random failures. When switching between v2rayNG and v2flyNG on Android, stop the current VPN connection before starting the other client so the previous session is not left active.

Set clear selection boundaries

Client selection comes down to three questions: Which operating system are you using? Which core does the subscription require? Do you need advanced routing or TUN? Start with v2rayN on desktop and v2rayNG on Android; consider v2flyNG when the configuration explicitly requires V2Fly behavior. Interface preferences matter, but should not override protocol compatibility or system architecture. For a detailed comparison, see the side-by-side review. Use the download page's current package list for package types.

After choosing a client, use it consistently for a while before changing tools. Stable habits are more valuable than constantly changing interfaces: standardize subscription notes, use consistent names for routing rules, make the system proxy state explicit and keep only the logs you need. These practices turn maintenance into a repeatable process. The next chapter covers installation and first launch.

Installation and first launch: build a recoverable baseline

Check the system and processor architecture before installing

The first installation step is not double-clicking the file; it is confirming the operating system version, processor architecture and a writable directory. Windows is commonly x64. macOS requires a choice between Apple Silicon and Intel. Linux requires x64 or arm64 plus the appropriate deb or rpm package for the distribution. Android requires a choice between arm64 and a universal package. System information fields such as system type, chip or processor are more reliable than device marketing names. If the architecture does not match, choose another package rather than trying to bypass the restriction by changing file extensions or copying executables.

On desktop systems, place the client in a clearly named location where the current account has read and write access. The client needs to save subscriptions, logs, routing rules and interface settings. A read-only directory can prevent settings from being saved, revert configuration after an upgrade or stop the core from releasing files. Avoid overly long paths, and do not place a running directory under a sync tool that automatically releases files on demand. To migrate, exit the client first and copy the complete configuration directory; copying only the main program will not preserve subscription groups or custom rules.

Complete only the essentials on first launch

After the first launch, verify that the interface opens normally, the core components can be invoked and the log window is not reporting continuous errors. Do not enable TUN, custom DNS or complex routing yet. Keep the default local port and basic proxy mode, import one clearly sourced subscription or single node and make the first connection. This creates the shortest validation path: client startup, configuration loading, core runtime, system proxy activation and app access. If a step fails, its boundaries are clear.

If Windows exits immediately after launch, check the system runtime, program directory permissions, old processes and possible configuration corruption. If macOS blocks the first launch, use System Settings to confirm the app can be opened instead of repeatedly copying the app file. If Linux will not start after installation, run it once from a terminal to see missing dependencies or permission messages. After installing on Android, allow necessary notifications so you can observe connection status; handle system VPN permission when making the first connection.

Windows: Settings → System → About → System type
macOS: Apple menu → About This Mac → Chip
Linux：uname -m
Android: Check the ABI in a system information tool and identify arm64-v8a first

Exit, restart and restore the system proxy

Closing a desktop client's window does not always exit it immediately; some settings keep the program running in the background. Before updating, migrating or troubleshooting a port conflict, use the client's exit command and confirm that its core process has also ended. If a process is terminated directly, the system proxy may continue pointing to the previous local port, causing every browser request to fail. Even when the node itself is healthy, restore the system proxy first and then restart the client.

A safe exit sequence is: stop the current connection, disable the system proxy or TUN, exit the client and confirm that the process has ended. Restart in reverse: open the client, confirm that configuration has loaded, select a node and start the core, then enable the system proxy or TUN. This prevents traffic from being sent to a local port that is not listening yet. On Android, swiping the app away from recent tasks may also trigger a vendor background policy. For persistent connections, use the maintenance chapter to configure battery exceptions and background permissions.

Keep a baseline for future troubleshooting

After the first successful connection, do not immediately pile on more settings. Record the client, subscription group, node type, proxy mode and whether TUN is enabled, then confirm that one browser and one everyday app can access the network reliably. This is your baseline. If a routing or DNS change causes trouble, return to the baseline to identify the change responsible instead of reinstalling every component.

Also learn where to find logs and configuration backups. The most useful log details are the stage of failure, target address, protocol handshake result and DNS messages; there is no need to retain verbose debug output indefinitely. Back up only after the client has fully exited, including at least subscription information, routing rules and key preferences. For startup failures caused by runtimes or permissions, continue with the client startup crash fix guide.

Subscriptions and nodes: organize configuration into maintainable groups

Subscription URLs, share links and manual configuration

A subscription URL fetches and continuously updates a group of nodes, making it suitable for long-term maintenance. A share link usually describes one node, making it useful for temporary imports or targeted testing. Manual configuration requires entering the address, port, user ID, transport and security parameters one by one, which is useful when no import format is available or details need to be checked. All three methods ultimately create selectable server entries, but they update differently. Nodes from a subscription should be maintained through subscription updates; manual edits may be overwritten at the next refresh.

When adding a subscription, create a recognizable group note first, then paste the complete URL. Use a service name, purpose or environment in the note rather than generic labels such as Subscription 1 or Backup 2, which become hard to distinguish when several sources coexist. Save it, run one manual update and check whether entries are returned and whether any format errors appear. Subscription URLs contain access credentials, so keep them only on controlled devices and in client configuration; do not put them in public documents, screenshots or shared logs.

An update does not mean an immediate switch

A subscription update may add, remove or modify nodes in the current group, but it does not automatically replace the active connection. After the update, check that the selected entry still exists and reconnect to another node if necessary. If the list looks unchanged, first confirm that the target group was updated, then check keyword filters, deduplication and sorting. Nodes with identical names may make the results look unchanged even when their internal parameters have been refreshed.

When an update fails, check the URL format, network reachability, system time and client logs in that order. Do not include leading or trailing spaces or line breaks when copying the URL. A page opening in a browser does not prove that the subscription endpoint is reachable. An inaccurate system clock can affect secure connections. Status codes and parsing messages in the logs can distinguish a failed request from unsupported content. Do not repeatedly click Update at the same time; repeated requests cannot fix a format problem and make the logs harder to read.

Subscription group naming examples:
Work environment | Primary subscription
Mobile devices | Frequently used
Protocol testing | Temporary

Filter rule examples:
Include keywords: VLESS|Trojan
Exclude keywords: maintenance|expired|remaining

Choose nodes based on protocol, location and the task at hand

Names in a node list are usually labels supplied by the provider, not a verdict on stability. Latency tests are useful for quickly removing entries that cannot connect or respond unusually slowly, but results depend on the route, test method and momentary state. Choose nodes by considering whether the current core supports the protocol, whether transport parameters are complete, whether the required app works reliably and whether the connection avoids frequent reconnects over time. A single low reading cannot replace sustained access testing.

When a node is unavailable, first select another node in the same subscription group. If the others work, the issue is usually limited to one configuration or the remote status. If the whole group fails, check whether the subscription has expired and whether its updated content is abnormal. If multiple sources fail at once, inspect the local network, system proxy and client core. This comparison is more effective than changing DNS, routing and ports without a plan.

Multiple subscription groups and filtering strategies

When maintaining multiple subscriptions, keep their sources separate instead of merging them into one flat list. Groups define update boundaries and make it easier to apply independent filters to each source. Use a consistent naming order for nodes, such as protocol or region followed by the original label. Keep filters simple and solve one goal at a time: hide maintenance notices, retain a specific protocol or exclude an unwanted use case. Overly broad rules can easily hide new nodes by accident.

After changing filters, first compare the unfiltered count and names, then add conditions gradually. In regular expressions, the vertical bar means or, parentheses group expressions, and periods and asterisks have special meanings. For ordinary words, using explicit keywords is safer. For practical guidance on grouping, labeling and filtering multiple subscription sources, see Managing multiple subscription groups. Once subscriptions are organized, move on to proxy modes rather than mistaking a list problem for a system-takeover problem.

Proxy modes: understand the system proxy, rule mode and global handling

The system proxy directs apps that support it to the client

On desktop systems, the system proxy essentially sets the operating system's proxy address to the local port listened to by the client. Browsers and many desktop apps read this setting and send HTTP or SOCKS requests to the client, which then decides how to handle them based on the current node and routing rules. System proxy coverage is clear and requires relatively few permissions, making it a good default for first connections and everyday use. Some apps use their own network stack or independent proxy settings, however, and will not follow it automatically.

Before enabling the system proxy, the client core must already be running and listening on the relevant port. If nothing is listening on the configured port, every app that follows the system setting will fail to connect. To check, disable the system proxy first and confirm that local networking returns, then start the client and enable it again. Do not change the local port casually. If you must change it, make sure the client's inbound port, system proxy address and any apps with manually configured proxies all match.

What rule, global and direct modes are for

Rule mode decides whether traffic uses the proxy, connects directly or is blocked based on conditions such as domain, IP, port, process or protocol. It is usually the best balance for everyday use. Global mode generally sends all traffic that can be intercepted through the current proxy. It is useful for briefly verifying that a node can handle a target request or ruling out a routing mistake, but it does not mean the connection is higher quality. Direct mode bypasses the remote proxy and can temporarily restore ordinary networking or provide a comparison test.

During troubleshooting, use the three modes as a comparison. If global mode works but rule mode does not, check which routing rule is matching. If global mode also fails, the problem is more likely in the node, core or system takeover. If an app still uses a proxy after the system proxy is disabled, it may have an independent proxy configured or another network tool may still be running. Reconnect after every mode change and check outbound tags in the logs to confirm that the new setting is active in the current session.

Browsers, command-line tools and independent proxy apps

Browsers usually follow the system proxy, but extensions or enterprise policies may provide independent settings. When troubleshooting a browser, disable extra proxy extensions, open a fresh window to access the target and compare the result with other system apps. Command-line tools do not always read the desktop system proxy; you may need to set HTTP_PROXY, HTTPS_PROXY or ALL_PROXY in the current terminal session. Point these variables only to the local address and port actually listened to by the client, and clear them after testing so later commands do not fail when the client is closed.

# Temporarily set a local proxy for the current terminal session; the port must match the client setting
export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809

# Clear it after testing
unset HTTP_PROXY
unset HTTPS_PROXY

Some development tools, download utilities and game platforms have independent network settings, so check the app's own documentation first. Do not switch to TUN immediately just to cover an app that ignores the system proxy. Check whether it supports a manual HTTP or SOCKS proxy; that is often easier to control. If the app truly cannot use a proxy and needs UDP or child processes intercepted as well, then evaluate whether TUN is necessary.

Judge connection status separately from actual access

A client showing Connected usually means that the core has started or a local VPN interface has been created; it does not mean that every remote request succeeds. Actual access also depends on DNS resolution, route matching, the protocol handshake and the target response. When it says connected but access fails, check the logs for DNS failures, connection timeouts, routes going direct or remote rejections. The target and outbound tags in the logs show whether traffic followed the expected path.

Once the setup is stable, use rule mode as the daily default and keep global mode as a diagnostic tool. Whenever you change a subscription, node or mode, change only one item, reconnect and test against the same target. The results remain comparable and provide a solid basis for writing routing rules in the next chapter.

Split routing: control the exit for each type of traffic with explicit rules

Rules consist of match conditions, targets and order

The point of split routing is not to accumulate rules but to answer two questions: Which traffic needs special handling, and which exit should it use? Common match conditions include full domains, domain suffixes, IP ranges, ports, network types and process names. Targets are usually proxy, direct or block. The client converts interface rules into core configuration and matches them in a defined order. In general, more specific rules should come first, with broad fallback rules later.

Domain rules can behave differently before and after DNS resolution. If an app connects directly to an IP, a domain-suffix rule alone will not match. If the client does not receive the original domain, it can only evaluate the resolved IP. Process rules depend on system permissions and process identification, which may vary by desktop platform. Before writing rules, confirm which conditions the client interface supports; do not paste syntax from another tool without checking it.

Start with the smallest useful rule set

A maintainable rule set usually has explicit direct rules, explicit proxy rules and a final fallback. Begin with the most certain conditions, such as sending local-network addresses direct or routing a specific work domain through a chosen exit, then decide the default path for everything else. Do not import a large set of unknown rules at the start: rules can overlap, and later updates make changes difficult to trace. For every added rule, know what it matches, why it is needed and why it belongs where it is.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": ["domain:example.com", "domain:example.net"],
        "outboundTag": "proxy"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

The structure above illustrates common core routing logic: private addresses go direct first, specified domains use the proxy and all other TCP and UDP traffic uses the proxy exit. In v2rayN and mobile clients, outbound tags may be generated by the interface, so do not assume their names. Before copying a configuration fragment, confirm whether the client supports editing the complete configuration directly. If you use a graphical rule editor, enter each condition into its corresponding field instead of placing an entire JSON block in one input.

Understand how domain strategy and DNS work together

AsIs means matching the original domain first, without resolving an IP just for routing decisions. Other strategies may continue with IP resolution when no domain rule matches. The more aggressive the strategy, the more DNS queries it may generate and the more it depends on correct DNS configuration. If your main need is splitting by domain suffix, simple domain logic is easier to troubleshoot. If you must route by IP range, verify that the resolution result, DNS exit and IP rules are consistent.

DNS and routing affect each other. DNS queries are traffic too, so you must decide which server resolves them and through which exit they are sent; the result then participates in later IP rules. Common failures include a domain resolving to an address unsuitable for the current route, a query being sent through the wrong exit or a cache retaining an old result. During troubleshooting, inspect the resolution result for the specific domain first, then check which rules matched the query and the application connection. Do not change multiple DNS servers, domain strategies and routing sets at once, or it becomes difficult to tell which change took effect.

Test rule matches and locate conflicts

When validating rules, choose a target with clear characteristics and inspect the domain, target IP and outbound tag in the logs. If a specific rule does not match, check whether a broader rule comes before it, whether the domain format is correct, whether the app connects directly by IP and whether an old connection is still being reused. Browsers may keep connections open, so refreshing a page after changing rules may not rebuild every request. Close the relevant tabs or restart the app before testing if necessary.

Process-based routing must account for child processes. A browser's main process and network service may have different names, and a launcher may be separate from the actual program. On mobile, per-app proxying is better handled by selecting app packages. The result depends on whether the client means bypass selected apps or proxy only selected apps, so read the option carefully before switching. For Android permissions, battery exceptions and per-app proxying, see v2rayNG Android essentials.

Keep rules readable and reversible

Document the purpose of each rule group and export a backup before major changes. Names such as local network direct, work domains via proxy and specific app direct are easier to maintain than abstract numbers. Disable a rule and observe for a while before deleting it. If a subscription supplies the rule set, store it separately from personal rules so updates do not overwrite manual changes.

A mature routing setup is not the one with the most rules; it is the one that can reliably explain every match. Cover the main use cases first, then handle a small number of exceptions. If exceptions keep growing, reconsider whether the default exit is appropriate. After the routing basics work, move to TUN only when apps that ignore the system proxy, UDP traffic or complex child processes genuinely need interception.

TUN mode: expand traffic interception while keeping complexity under control

Why TUN covers more applications

TUN mode receives system traffic through a virtual network interface and passes it to the client core for routing decisions. Apps do not need to support HTTP or SOCKS proxies, so TUN can cover programs that ignore the system proxy, some UDP traffic and multi-process apps. The system VPN connection created by Android clients follows a similar interception model. Broader coverage also brings system routes, DNS, permissions and exclusions into play, so enable TUN only after the basic node and rule mode have been verified.

TUN does not mean that all traffic must use the remote proxy. After entering the virtual interface, traffic still follows routing rules to the proxy, direct connection or block. If local-network access, printing or development environments must stay direct, verify private-address and related domain rules before enabling it. A wrong default route can make local devices unreachable, while incorrect DNS can appear as IP access working but domain access failing.

Pre-enable checklist

First close other network tools that may create virtual interfaces or modify the routing table, then confirm that a regular system-proxy connection works in v2rayN. Check that the current node supports the required network types, record the existing DNS settings and routing mode, and only then enable TUN. Desktop systems may require administrator privileges or additional components; complete them when the client clearly prompts you. If permission is denied, repeatedly toggling the switch will not help; fix it in system permission settings.

After enabling it, test three layers: access a normal domain, access an IP directly and access a local-network resource. If the domain fails but the IP works, check DNS first. If both fail, inspect the virtual interface, default route and core logs. If external access works but local-network access fails, check direct rules for private ranges. Keep test targets fixed and reconnect after each change so caches and old sessions do not distort the conclusion.

DNS, strict routing and loopback issues

TUN often needs to intercept DNS, so domain resolution and subsequent connections must follow a consistent routing strategy. Adding more DNS servers does not automatically improve reliability; it can instead produce inconsistent results. Start with the simple setup recommended by the client, confirm that queries reach the core and then separate direct and proxy resolution as needed. If a resolution loop occurs, check whether DNS requests are being sent back to the same local listening port.

Strict routing reduces the chance of traffic bypassing the virtual interface, but it can also affect virtual machines, containers, local-network sharing and custom network adapters. Before enabling it, record the existing networks and interfaces, especially private ranges used by development environments. If container access suddenly fails, do not change the node protocol first. Compare the routing tables before and after TUN and add explicit handling for required ranges. Rules should be narrow and accurate; avoid covering normal system routes with oversized ranges.

Android connection permission and per-app proxying

v2rayNG or v2flyNG requests system VPN permission on the first connection. Android normally permits only one active VPN session at a time, so stop the current connection before switching clients. Per-app proxying has two opposite modes: proxy only selected apps, or bypass the proxy for selected apps. Check the wording in the interface first, then test with one easy-to-verify app instead of selecting many at once.

If the connection frequently drops after the screen locks, the cause is often battery optimization, background restrictions or the device manufacturer's task management. Add the client to the battery exception list, allow background activity and keep persistent notifications enabled to help maintain the VPN service. Do not leave verbose logging enabled permanently; it increases write and processing overhead. For a fuller mobile battery and background troubleshooting guide, see v2rayNG battery and background operation troubleshooting.

When should you fall back to the system proxy?

If your main needs are a browser and a few desktop apps that support proxies, the system proxy is usually simpler. TUN should solve a specific problem rather than add default complexity. If it causes persistent local-network, container or DNS conflicts, return to the system proxy first, restore daily work and analyze the apps that actually need interception separately. Keeping a verified regular proxy configuration provides an important fallback for TUN failures.

When disabling TUN, use the client switch to stop it normally so the virtual interface and routes are cleaned up, then confirm that networking has recovered. If the network is abnormal after forcibly ending the process, restart the client and shut it down normally once, or inspect leftover interfaces in system network settings. With these basics in place, the next chapter turns updates, backups, logs and troubleshooting into a repeatable maintenance workflow.

Routine maintenance: updates, backups, logs and stability checks

Separate updates into client, subscription and rule updates

Routine updating is not one action. A client update can change the interface, core or feature behavior; a subscription update refreshes node parameters; a rule update may change traffic exits. Perform the three separately and complete a basic verification after each. If you replace the client, refresh the subscription and import new rules on the same day, it becomes difficult to identify the source of a failure. In a stable environment, back up first, update the client and verify that startup and the old configuration work, then refresh the subscription and handle rules last.

Before updating the client, stop the running core and record the current package type and architecture. Do not overwrite files while the old program is still running. After the update, check that subscription groups, routing mode, local port and TUN settings remain intact, then start with a known-good node. For subscription updates, review the entry count, current selection and filters. After rule updates, reconnect and use the logs to confirm that important targets still use the expected exit.

The goal of a backup is recovery, not file count

A useful backup should include at least subscription groups, manual nodes, custom routing, DNS preferences and key client settings. Fully exit the client before backing up so you do not copy a configuration file that is still being written. You can organize backup directories by date and client name, but never upload files containing subscription credentials to a public location. Test recovery in the same client family first before attempting migration across versions or clients.

Also keep a short environment record covering the platform, processor architecture, client name, proxy mode, custom local port and whether TUN is enabled. It need not contain node credentials, but it can quickly restore the operating logic after a reinstall. Add purpose notes to complex routing rules so they do not become unexplained conditions months later. A recoverable configuration should answer: what are the fewest steps needed to return from an empty environment to a stable state?

Use logs to locate the stage, not just to search for error words

Start log analysis with the timeline: when did the client read configuration, the core start, the local port begin listening, DNS queries run, routes match, the remote connection occur and the app request arrive? A single error may be one retry; repeated errors of the same kind are more likely to identify the blocked stage. Record the exact time of the failure and capture the relevant lines before and after it. This is easier to analyze than sharing the entire log and reduces the risk of exposing subscription URLs or other sensitive data.

Troubleshooting record template
1. Platform and client: Windows / v2rayN
2. Traffic takeover: system proxy or TUN
3. Scope: all apps, one app or one domain
4. Recent changes: client, subscription, rules, DNS
5. Comparison: behavior in direct, rule and global modes
6. Log stage: startup, resolution, routing, handshake or timeout

If the client will not start, check the runtime environment, directory permissions, configuration corruption and port conflicts first. If a subscription will not update, check the URL and request errors. If every node fails after the core starts, check the system time, network and protocol compatibility. If only rule mode fails, check rule order. If only TUN fails, investigate permissions, DNS and system routes. Classifying the failure by stage usually narrows it to one or two modules.

Handle port conflicts, leftover proxies and background restrictions

Port conflicts commonly occur after an abnormal exit, duplicate launch or simultaneous use of multiple tools. Exit all related clients normally first, then check for leftover processes. If you change the local port, update the system proxy and any apps with manually specified proxies as well. A stale system proxy can prevent the browser from accessing the network after the client closes. Restore the operating system proxy settings first; there is no need to delete subscriptions or reinstall the system.

For Android background interruptions, check battery optimization, background activity limits, auto-start permission and persistent notifications. Settings differ by device, but the diagnosis is the same: stable in the foreground but interrupted after locking usually points to background management; failure even in the foreground points first to configuration or VPN permission. Do not keep the service alive by endlessly increasing the log level. Logs observe the system; they do not change scheduling.

Establish lightweight periodic checks

Routine maintenance does not require constant changes. Periodically update subscriptions, remove clearly expired temporary configurations, check that filters are not hiding new nodes and confirm that client settings still match current needs. Change routing rules only when the workload changes, and enable TUN only when broader coverage is genuinely required. Long-term stability matters more than chasing every new option.

When something goes wrong, recall the most recent change and follow this order: disable advanced features, restore the baseline node, verify the system proxy and add settings back one at a time. If reinstalling is necessary, back up the configuration and confirm that old processes have exited first. For more on startup crashes, permissions and leftover processes, see runtime and permission troubleshooting. The next chapter extends these fundamentals to protocols, cores and configuration reading.

Advanced path: move from using a client to understanding configuration

Stage 1: understand one complete node

Advanced learning does not need to begin with writing an entire configuration. Choose a working node and use the client interface to understand its address, port, user ID, protocol, transport, security layer, domain and fingerprint fields one by one. The goal is not to memorize every option, but to know which parameters must match the server and which are local preferences. Copy the working configuration into a test entry, change one non-critical field at a time and observe the logs to connect each field with its behavior.

Study the protocol and transport layers separately. VLESS, VMess and Trojan describe identity and protocol interaction; TCP, WebSocket and gRPC describe how data is carried; TLS and REALITY handle their respective security and handshake requirements. Similar names do not make parameters interchangeable. Read a configuration from the outside in: confirm the server address and port, then protocol identity, transport, security layer and domain. The same order works for manually checking a failed connection.

Stage 2: understand the Xray and V2Fly ecosystem

Xray and V2Fly are both development branches of the Project V technology ecosystem, and clients integrate the core that matches their role. v2rayN is commonly used for comprehensive desktop management, v2rayNG is primarily based on the Xray core and v2flyNG offers an Android option built around the V2Fly core. Different cores affect protocol support, configuration fields and release cadence. When a subscription explicitly depends on a capability, use a compatible client and core.

When learning core differences, do not reduce a support list to an absolute ranking. More useful questions are: Which protocols and transport fields does the current configuration use? Can the integrated core recognize them? Did behavior change after an upgrade? Do the logs report unknown fields? For an in-depth look at the evolution of both core paths and client selection, read Xray vs. V2Fly core differences explained.

Stage 3: move from graphical rules to structured configuration

Once you are comfortable with the client's routing editor, begin reading the basic structure of a core configuration. A typical configuration contains logging, DNS, inbounds, outbounds and routing. Inbounds receive traffic from the system proxy or TUN, outbounds define exits such as proxy and direct, and routing maps match conditions to outbounds. First trace references between tags, then inspect each object's parameters. Inconsistent tag spelling can point a rule to an outbound that does not exist, a common problem in manual editing.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

This example shows only a local SOCKS inbound, a direct outbound and private-address rules; it contains no remote server credentials. Clients usually generate the inbound and primary outbound automatically. Before editing manually, export and read the current result rather than replacing a configuration in use. After each change, verify that the JSON structure is complete and use client logs to confirm that the core accepts the fields.

Stage 4: build a repeatable experiment method

Advanced configuration easily turns into changing many things without knowing what helped. Create a separate subscription group or test configuration for experiments, keep a stable baseline and record each change, expected result and actual log output. Fix the node when testing routing, fix the routes when testing a node and fix the target domain when testing DNS. Fewer variables produce more reliable conclusions. When something fails, revert the last change instead of adding more parameters.

You can raise the log level for a short test, but restore the normal level after locating the issue. Detailed logs contain more information and may include target addresses and configuration fragments, so remove subscription URLs, user IDs and other credentials before sharing them. Command-line tests should use only the local loopback address and the port actually used by the client; do not write temporary credentials directly into long-lived scripts.

Stage 5: create your own maintenance documentation

When a setup includes multiple subscriptions, routing groups, TUN and per-app rules, write a short environment guide. Include why each client was chosen, the purpose of each subscription group, the default proxy mode, important routes, the DNS plan, backup location and recovery order. Do not record sensitive parameters, but make the recovery process clear after a reinstall or upgrade. Update the guide after every major change; it is more reliable than memory.

Going from zero to proficiency does not mean enabling every option. It means being able to explain why the current configuration works and knowing which layer to inspect when something fails. A practical long-term path is to keep one stable client, master subscription groups and the system proxy, write a minimal routing set, enable TUN only for a clear need and then read structured configuration and core logs. If you have not completed your first connection, return to the quick setup and follow the main path. To change platform or architecture, visit the installation packages page and choose the matching client.