Knowledge Base updated: 2026-11-16
Knowledge Base Index
Orientation
This repository is v2rayN, a .NET proxy client suite built around a shared ServiceLib core. The highest-level flow is: UI or WebAPI input updates shared configuration/profile state, generates a proxy-core config, launches or restarts a proxy core, and reports status/statistics back to the caller.
Main parts:
v2rayN/ServiceLib/— shared domain logic, persistence, profile parsing, config generation, core runtime control, network/update flows, and UI-agnostic MVVM view models.v2rayN/v2rayN/— Windows WPF desktop shell.v2rayN/v2rayN.Desktop/— cross-platform Avalonia desktop shell.v2rayN/v2rayN.WebAPI/— headless ASP.NET WebAPI runtime with auth, setup, update, backup, and launcher support.v2rayN/ServiceLib.Tests/,v2rayN/v2rayN.WebAPI/Tests/,v2rayN/ServiceLib.UdpTest/,v2rayN/AmazTool/— test suites and supporting tools.
Critical state lives in ServiceLib configuration/database entities under ServiceLib/Handler/Data/** and ServiceLib/Models/Entities/**; WebAPI auth/session/setup state is owned by v2rayN.WebAPI/Security/**; runtime process and update state is coordinated in ServiceLib managers/services and WebAPI runtime services.
Architecture diagrams
flowchart TD
subgraph UI[Desktop UI shells]
WPF[v2rayN WPF]
Avalonia[v2rayN.Desktop Avalonia]
end
subgraph Shared[ServiceLib]
VM[ViewModels]
Data[Config persistence]
Fmt[Profiles and subscriptions]
Config[Core config generation]
Runtime[Core runtime/processes]
Net[Download/update/speedtest]
end
subgraph Headless[v2rayN.WebAPI]
API[Api endpoints]
WebRuntime[Runtime services]
Security[Security and sessions]
Launcher[Launcher/deployment]
end
subgraph Tools[Build, tests, tools]
Tests[Test projects]
Amaz[AmazTool]
Packaging[Packaging scripts]
end
WPF --> VM
Avalonia --> VM
VM --> Data
VM --> Fmt
VM --> Config
VM --> Runtime
VM --> Net
API --> WebRuntime
API --> Security
WebRuntime --> Data
WebRuntime --> Config
WebRuntime --> Runtime
WebRuntime --> Net
Launcher --> API
Tests --> Shared
Tests --> Headless
Amaz --> Packaging
flowchart LR
Input[UI or WebAPI request] --> Profiles[Profile/subscription handling]
Profiles --> Persist[ConfigDbHandler / persisted entities]
Persist --> Build[CoreConfigHandler and core config services]
Build --> Launch[CoreManager / ProcessService]
Launch --> ProxyCore[Proxy core process]
ProxyCore --> Stats[Statistics services]
Stats --> Caller[UI status or WebAPI response/events]
sequenceDiagram
participant Client as Browser/API client
participant Endpoints as v2rayN.WebAPI Api
participant Auth as Security services
participant Runtime as V2rayRuntime services
participant ServiceLib as ServiceLib
participant Core as Proxy core process
Client->>Endpoints: authenticated runtime request
Endpoints->>Auth: validate session/setup policy
Auth-->>Endpoints: allowed
Endpoints->>Runtime: apply profile/settings/update action
Runtime->>ServiceLib: mutate config or generate runtime config
ServiceLib->>Core: start/restart/stop process
Core-->>ServiceLib: status/statistics
Runtime-->>Endpoints: result/snapshot/events
Endpoints-->>Client: API response or stream
flowchart TD
Release[Release/package metadata] --> UpdateService[ServiceLib UpdateService]
UpdateService --> Download[DownloadService / DownloaderHelper]
Download --> Stage[WebAPI or desktop staging policy]
Stage --> Preflight[Preflight and mutation gates]
Preflight --> Apply[Apply core/web/geofile update]
Apply --> Restart[Runtime restart or launcher workflow]
Glossary
ServiceLib— shared library containing the core application model, persistence, runtime orchestration, and UI-independent view models.ProfileItem— persisted proxy/server profile entity used as input to share-link handling and core config generation.CoreConfig— generated v2ray/Xray, sing-box, or Clash runtime configuration emitted from app profiles/settings.V2rayRuntime— WebAPI-side runtime facade coordinating headless core lifecycle, settings/profile mutations, updates, and backups.AmazTool— repository tool project used by build/release workflows outside the main apps.
Codebase-wide invariants
- Shared business logic is centralized under
v2rayN/ServiceLib/**, while product surfaces live in separate host projects:v2rayN/v2rayN/**,v2rayN/v2rayN.Desktop/**, andv2rayN/v2rayN.WebAPI/**. - Desktop UI shells mirror many shared workflows with platform-specific views: WPF uses
v2rayN/v2rayN/Views/*.xaml*, while Avalonia usesv2rayN/v2rayN.Desktop/Views/*.axaml*. - WebAPI runtime concerns are separated by directory: routes in
v2rayN/v2rayN.WebAPI/Api/**, DTO/contracts inContracts/**, orchestration inServices/**, auth/policy middleware inSecurity/**, and native process workflows inLauncher/**. - Core-family config generation is split by target runtime under
v2rayN/ServiceLib/Services/CoreConfig/V2ray/**,v2rayN/ServiceLib/Services/CoreConfig/Singbox/**, and v2rayN/…/CoreConfigClashService.cs. - Tests are colocated by product area rather than embedded in production projects:
v2rayN/ServiceLib.Tests/**,v2rayN/v2rayN.WebAPI/Tests/**, andv2rayN/ServiceLib.UdpTest/**.
Routing table
-
v2rayN/ServiceLib/Handler/Data/**-> docs/service-lib-configuration-persistence.md -
v2rayN/ServiceLib/Models/Configs/**-> docs/service-lib-configuration-persistence.md -
v2rayN/ServiceLib/Models/Entities/**-> docs/service-lib-configuration-persistence.md -
v2rayN/…/SqliteHelper.cs -> docs/service-lib-configuration-persistence.md
-
v2rayN/…/Global.cs -> docs/service-lib-configuration-persistence.md
-
v2rayN/…/GlobalUsings.cs -> docs/service-lib-configuration-persistence.md
-
v2rayN/ServiceLib/Enums/**-> docs/service-lib-configuration-persistence.md -
any persisted configuration/entity/schema change -> docs/service-lib-configuration-persistence.md
-
v2rayN/ServiceLib/Handler/Fmt/**-> docs/service-lib-profile-formats-subscriptions.md -
v2rayN/…/SubscriptionHandler.cs -> docs/service-lib-profile-formats-subscriptions.md
-
v2rayN/ServiceLib/Models/Dto/*Profile*-> docs/service-lib-profile-formats-subscriptions.md -
v2rayN/ServiceLib/Models/Dto/*QRCode*-> docs/service-lib-profile-formats-subscriptions.md -
v2rayN/…/SsSIP008.cs -> docs/service-lib-profile-formats-subscriptions.md
-
v2rayN/…/HyRealm.cs -> docs/service-lib-profile-formats-subscriptions.md
-
v2rayN/…/RetResult.cs -> docs/service-lib-profile-formats-subscriptions.md
-
v2rayN/ServiceLib/Sample/**-> docs/service-lib-profile-formats-subscriptions.md -
any new protocol share link, subscription parser, or export format -> docs/service-lib-profile-formats-subscriptions.md
-
v2rayN/ServiceLib/Handler/Builder/**-> docs/service-lib-core-config-generation.md -
v2rayN/…/CoreConfigHandler.cs -> docs/service-lib-core-config-generation.md
-
v2rayN/ServiceLib/Services/CoreConfig/**-> docs/service-lib-core-config-generation.md -
v2rayN/ServiceLib/Models/CoreConfigs/**-> docs/service-lib-core-config-generation.md -
any change to generated v2ray/Xray, sing-box, or Clash runtime config -> docs/service-lib-core-config-generation.md
-
v2rayN/…/CoreManager.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/…/CoreAdminManager.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/…/CoreInfoManager.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/…/StatisticsManager.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/…/CertPemManager.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/…/ConnectionHandler.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/…/AutoStartupHandler.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/ServiceLib/Handler/SysProxy/**-> docs/service-lib-core-runtime-processes.md -
v2rayN/…/ProcessService.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/…/WindowsJobService.cs -> docs/service-lib-core-runtime-processes.md
-
v2rayN/ServiceLib/Services/Statistics/**-> docs/service-lib-core-runtime-processes.md -
any change to proxy-core process lifecycle, system proxy, or traffic statistics -> docs/service-lib-core-runtime-processes.md
-
v2rayN/…/DownloadService.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/…/UpdateService.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/…/SpeedtestService.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/…/DownloaderHelper.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/…/HttpClientHelper.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/…/HttpRequestHeadersHelper.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/…/NetworkUtils.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/…/FileUtils.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/…/ProcUtils.cs -> docs/service-lib-download-update-speedtest.md
-
v2rayN/ServiceLib/Models/Dto/*Download*-> docs/service-lib-download-update-speedtest.md -
v2rayN/ServiceLib/Models/Dto/*Update*-> docs/service-lib-download-update-speedtest.md -
v2rayN/ServiceLib/Models/Dto/*Release*-> docs/service-lib-download-update-speedtest.md -
v2rayN/ServiceLib/Models/Dto/*Speed*-> docs/service-lib-download-update-speedtest.md -
v2rayN/ServiceLib/Models/Dto/*Test*-> docs/service-lib-download-update-speedtest.md -
any release check, package download, update, latency, availability, or speed-test behavior -> docs/service-lib-download-update-speedtest.md
-
v2rayN/ServiceLib/ViewModels/**-> docs/service-lib-viewmodels-app-orchestration.md -
v2rayN/…/AppManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/…/ClashApiManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/…/EndpointResolveManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/…/GroupProfileManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/…/NoticeManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/…/PacManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/…/ProfileExManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/…/TaskManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/…/WebDavManager.cs -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/ServiceLib/Base/**-> docs/service-lib-viewmodels-app-orchestration.md -
v2rayN/ServiceLib/Events/**-> docs/service-lib-viewmodels-app-orchestration.md -
any UI-agnostic workflow, view model command, profile/routing/settings orchestration, or app-level event/task plumbing -> docs/service-lib-viewmodels-app-orchestration.md
-
v2rayN/ServiceLib/Common/**-> docs/service-lib-common-utilities.md -
v2rayN/ServiceLib/Resx/**-> docs/service-lib-common-utilities.md -
v2rayN/ServiceLib/ServiceLib.csproj-> docs/service-lib-common-utilities.md -
any localization/resource, JSON/YAML/logging/QR/embed/fake-IP/country utility change not owned by a narrower runtime/update doc -> docs/service-lib-common-utilities.md
-
v2rayN/v2rayN/**-> docs/windows-wpf-ui-shell.md -
any Windows-only WPF view, window, converter, resource, hotkey, or dialog behavior -> docs/windows-wpf-ui-shell.md
-
v2rayN/v2rayN.Desktop/**-> docs/desktop-avalonia-ui-shell.md -
any Avalonia desktop view, dialog, converter, asset, or cross-platform shell behavior -> docs/desktop-avalonia-ui-shell.md
-
v2rayN/v2rayN.WebAPI/Api/**-> docs/webapi-runtime-and-endpoints.md -
v2rayN/v2rayN.WebAPI/Contracts/**-> docs/webapi-runtime-and-endpoints.md -
v2rayN/v2rayN.WebAPI/Services/**-> docs/webapi-runtime-and-endpoints.md -
v2rayN/v2rayN.WebAPI/Adapters/**-> docs/webapi-runtime-and-endpoints.md -
v2rayN/v2rayN.WebAPI/Configuration/**-> docs/webapi-runtime-and-endpoints.md -
v2rayN/…/FEATURE-MAP.md -> docs/webapi-runtime-and-endpoints.md
-
v2rayN/v2rayN.WebAPI/v2rayN.WebAPI.csproj-> docs/webapi-runtime-and-endpoints.md -
any new WebAPI endpoint, API model, runtime operation, backup/restore flow, geofile/core/web update workflow, or hosted runtime change -> docs/webapi-runtime-and-endpoints.md
-
v2rayN/v2rayN.WebAPI/Security/**-> docs/webapi-security-launcher-deployment.md -
v2rayN/v2rayN.WebAPI/Launcher/**-> docs/webapi-security-launcher-deployment.md -
v2rayN/v2rayN.WebAPI/Deploy/**-> docs/webapi-security-launcher-deployment.md -
v2rayN/v2rayN.WebAPI/Scripts/**-> docs/webapi-security-launcher-deployment.md -
v2rayN/v2rayN.WebAPI/Assets/**-> docs/webapi-security-launcher-deployment.md -
v2rayN/v2rayN.WebAPI/Properties/**-> docs/webapi-security-launcher-deployment.md -
v2rayN/…/.env.example -> docs/webapi-security-launcher-deployment.md
-
v2rayN/…/compose.yaml -> docs/webapi-security-launcher-deployment.md
-
v2rayN/v2rayN.WebAPI/Containerfile-> docs/webapi-security-launcher-deployment.md -
v2rayN/v2rayN.WebAPI/Containerfile.dockerignore-> docs/webapi-security-launcher-deployment.md -
any WebAPI auth/session/setup/CORS/header/listener policy, launcher, native update/restore, container, or deployment script change -> docs/webapi-security-launcher-deployment.md
-
v2rayN/*.sln-> docs/build-tests-and-tools.md -
v2rayN/*.slnx-> docs/build-tests-and-tools.md -
v2rayN/Directory.Build.props-> docs/build-tests-and-tools.md -
v2rayN/Directory.Packages.props-> docs/build-tests-and-tools.md -
v2rayN/ServiceLib.Tests/**-> docs/build-tests-and-tools.md -
v2rayN/ServiceLib.UdpTest/**-> docs/build-tests-and-tools.md -
v2rayN/v2rayN.WebAPI/Tests/**-> docs/build-tests-and-tools.md -
v2rayN/AmazTool/**-> docs/build-tests-and-tools.md -
.github/**-> docs/build-tests-and-tools.md -
.editorconfig-> docs/build-tests-and-tools.md -
.gitattributes-> docs/build-tests-and-tools.md -
.gitignore-> docs/build-tests-and-tools.md -
.gitmodules-> docs/build-tests-and-tools.md -
any solution, package version, build property, test harness, packaging, or repository CI/configuration change -> docs/build-tests-and-tools.md