Nozilla-X
66dd7da6e6
* feat(web): add headless ServiceLib API and replaceable UI host * build(web): package API without bundled WebUI * ci(web): build and test headless API packages * docs(web): document the headless API and optional WebUI * test(web): verify restore and build before API tests * docs(web): align API release examples with current upstream * test(web): cover creating and editing an empty-URL subscription group Verify the API accepts and persists a subscription whose Url and MoreUrl stay empty, that an edit keeps the empty URL and zero interval, and that ServiceLib is untouched. * fix(web): support per-target prerelease update preferences * fix(web): require management key for non-loopback listeners * ci: reduce development Web API build matrix * fix(web): make native self-update rollback atomic and preserve progress * docs(web): remove self-update E2E report * ci(web): decouple Web releases from Linux Desktop * feat(web): support standalone WebUI clients and rename the API to v2rayN.WebAPI - Resolve every REST, login, setup, download, SSE-ticket and EventSource request through one configurable Backend base per WebUI origin, with a strict exact-match origin allowlist and no wildcard or credential CORS. - Run the origin guard before authentication, and keep first-run setup, instance diagnostics and the hosted-UI CSP same-origin as before. - Rename the project directory, csproj, namespace, executable, lock, build identity and self-update target to v2rayN.WebAPI while retaining V2RAYN_WEB_* settings, WebVersion metadata, webVersion fields and the existing release asset contracts. - Migrate API-owned update preference identifiers and reject legacy v2rayN.Web update packages with a manual reinstall instruction. - Require staged native executables to be Linux ELF images for their RID. - Add CORS, update-identity and setup-security tests, and record the standalone-WebUI audit under v2rayN.WebAPI/STANDALONE-WEBUI-AUDIT.md. * Remove WebUI hosting and configuration coupling from WebAPI * Finish WebAPI cleanup and isolate native self-update worker * Keep WebAPI client documentation implementation-neutral * ci(webapi): verify Windows win-x64 build and startup * fix(webapi): validate keys and unify loopback limits * test(webapi): isolate update smoke from systemd runner * feat(webapi): add Windows x64 release and self-update * fix(webapi): verify release manifest version * ci(webapi): publish web packages through the official release flow * ci(webapi): run the web release inside the release-all workflow * webapi: finish the rename and fix shutdown, terminal launch and help - finish the Web -> WebAPI product rename: workflow files build-WebAPI.yml / release-WebAPI.yml (path filters, reusable call sites, container tag), solution entry, health headers X-v2rayn-WebAPI-*, WebAPI.self-update capability, WebAPI-update-progress.json / WebAPI-update-runtime-state.json, WebAPIData/WebAPI-auth.json with a migration from the legacy locations, and the README compatibility notes - end /api/events when the host starts stopping so Kestrel's graceful stop cannot pin the whole shutdown budget with a client attached; a runtime cleanup that starts after the host budget was exhausted now runs a reduced fresh pass instead of skipping Core stop and shared-state saves entirely - record the interactive launch context for detached children and helpers so systemd markers leaked into a terminal (INVOCATION_ID / JOURNAL_STREAM) no longer force foreground mode or misfire the supervised-deployment key check, self-update gating and lifecycle decisions - add --help / -h with the options and common environment variables in all three launcher locales, and keep help flags out of the host arguments * fix(webapi): retry transient file replacements during native updates Windows antivirus and the search indexer can hold a freshly written executable open for a moment, so replacing the installed executable or its build identity could fail with a bare access-denied error and abort the update or its rollback. Retry these replacements for a bounded window and report the operation, target path and cause when they still fail. * ci(webapi): display the release-all Web job as release-WebAPI The reusable-workflow job key still used the pre-rename name, which is the label the Actions UI shows for the nested Web release jobs. * feat(webapi): add win-arm64, linux-riscv64 and linux-loongarch64 coverage - build, package, sign and self-update support for the three architectures: win-arm64 (windows-11-arm native startup smoke), linux-riscv64 (RISE RISC-V runners with the community xujiegb/dotnet-riscv SDK; single-file publishing verified on real hardware) and linux-loongarch64 (the upstream QEMU loong64 VM with the official Loongson SDK, smoke-tested inside the VM) - per-RID native executable validation: ELF machines x86-64/AArch64/RISC-V (0xF3)/LoongArch (0x102) and Windows PE AMD64/ARM64 (0xAA64), behind a single IsSupportedRid gate - release asset map and packager/manifest tables extended; the riscv64 and loongarch64 Core bundles ship without the cronet payload - release manifests now ignore unknown RID entries so a newer manifest cannot be rejected wholesale by an older build * fix(webapi): keep the loongarch64 QEMU smoke out of the packaged publish tree The in-VM smoke ran the app inside the virtiofs-shared publish directory and left runtime files owned by the VM root (v2rayN.WebAPI.instance.lock) that the host runner could not read, so packaging failed with EACCES. The smoke now runs in a VM-local copy, and a host-side guard verifies the shared tree is complete and readable before packaging. * docs(webapi): document the six-platform release matrix Releases now cover linux-x64/arm64/riscv64/loongarch64 and win-x64/arm64; note the per-RID machine validation and the forward-compatible manifest behavior in the API release documentation. * ci(webapi): keep the release-all desktop dispatch exactly upstream build-all.yml dispatches the desktop workflows with "ref": "master" exactly as upstream does. The fork-only github.ref_name change is reverted so the PR leaves the existing release behavior untouched; the WebAPI release stays an additive reusable job in the same workflow. * fix(webapi): probe the effective listener and refuse unverifiable updates GetCurrentHealthUri and GetLauncherUris forced every probe to 127.0.0.1 and fell back to port 5080, so IPv6-only, wildcard and port-only listeners could be checked at the wrong endpoint. The detached update helper then either rolled back a healthy replacement or restarted without being able to verify the old instance, and --stop could probe the wrong process. Both callers now resolve the probe through one WebProbeUriResolver that uses the same effective Kestrel configuration as the host (command line, urls, http/https ports, Kestrel endpoints, preferHostingUrls) and maps each listener to its matching loopback address: "*", "+" and host names probe localhost, 0.0.0.0 probes 127.0.0.1, [::] probes [::1], and loopback literals keep their family. When no loopback HTTP probe exists (HTTPS-only or an explicit non-loopback address), GetWebUpdateTarget reports canInstall=false with maintenance.webUpdateProbeUnavailable and the update is refused before anything is stopped; the helper still accepts only loopback HTTP plan URIs, now including [::1]. --stop reports the new stopUnprobeable result instead of signalling an unverified owner, and the background launcher fails closed with startUnprobeable. Regression: new resolver/listener tests (default, custom port, IPv6-only, HTTP_PORTS, Kestrel override, HTTPS-only) and the real update fixture now covers an IPv6-only replacement, asserts that a failed update leaves the old build running (replacement PID), and proves that an unprobeable instance refuses both the API and --stop while staying up. * ci(webapi): capture the real smoke PID and bound the SIGTERM waits The riscv64 smoke backgrounded "cd && app" and recorded the subshell PID, so the later kill could target the wrapper while the app kept running. Both the riscv64 and loong64 smokes now start the app directly, record the application PID, fail fast when the process exits before health, wait a bounded time for SIGTERM before printing the log and force-killing, and assert a zero exit status. The loong64 VM smoke replaces its fixed two-second sleep with the same exit assertion. * chore(webapi): drop unreferenced legacy scripts bootstrap-xray.sh installed the removed bundled core-bin layout, and test-backup-fixtures.py compared desktop/Web backup ZIPs from before the WebUI decoupling; nothing references either script. * fix(webapi): unify the loopback probe, diagnostics and helper rules The resolver rewrote a configured localhost to 127.0.0.1 while the health diagnostics and the update helper each carried their own copy of the accepted-host rule. Keep localhost as localhost (resolving it covers both families instead of forcing one IPv4 literal) and make WebProbeUriResolver.IsProbeableLoopbackUri the single rule: plain HTTP to a host the diagnostics accept as local (localhost, 127.0.0.1 or ::1). The helper validates plans with that rule, the health endpoint uses the shared WebSetupAccessPolicy.IsLocalDiagnosticSource predicate, and every probe URI the resolver produces satisfies the rule. Unprobeable listeners (HTTPS-only or an explicit non-loopback address) still refuse the self-update up front: canInstall=false with maintenance.webUpdateProbeUnavailable while the current instance keeps running. Regression: localhost stays localhost across the resolver and launcher tests, the probe-rule invariant, the shared diagnostics/probe address rule, a direct unit test of the refusal reason, and a real localhost-listener replacement scenario in the update fixture. * fix(webapi): gate generated probes through the shared loopback rule MapToLoopbackHost accepted every address the OS reports as loopback, which in .NET is the whole 127.0.0.0/8 range, and TryCreateHealthUri returned true without checking the generated URI against the same rule the diagnostics and the update helper use. A listener on 127.0.0.2 therefore passed the up-front canInstall check, but the helper rejected its plan (and refused to restart the previous build for the same reason), so an update could stop the service without bringing anything back. TryCreateHealthUri now gates the constructed probe through IsProbeableLoopbackUri, so loopback aliases are refused before the instance is stopped and a mixed listener list falls through to the next verifiable endpoint. Regression: 127.0.0.2/127.255.255.254 mapping rows, a dedicated loopback-alias rejection test, the alias canInstall=false reason case, the mixed-list fall-through, and a real 127.0.0.2-listener fixture scenario that proves the update is refused while the current instance keeps running. * refactor(webapi): centralize integration tests and simplify release scripts Move the Linux integration tests (startup security, release packaging dry-run, full-ZIP runtime, native update regression and its fixture) from Scripts/ into Tests/Integration/; Scripts/verify.sh stays the unified entry and all path resolution, workflow calls, README text and cross-script invocations were updated. No test coverage changes. Merge Test-Windows.ps1 and Test-WindowsUpdate.ps1 into one Tests/Integration/Test-Windows.ps1 with -Mode startup|update: both modes share the native process control (CREATE_NEW_PROCESS_GROUP + CTRL_BREAK), environment isolation, free-port selection, no-proxy health waiting, JSON fixtures and retained-on-failure cleanup. CI keeps the Windows x64/ARM64 startup smokes and the x64 replacement/rollback smoke. Delete the package-native.sh thin wrapper; the workflow and the packaging dry-run now call web-release-assets.py package directly with the same --rid/--publish/--dist arguments, so asset names and ZIP boundaries stay unchanged. * test(webapi): keep the Windows health-body assertion in the merged smoke The merged Wait-TestHealth only accepted HTTP 200 in startup mode, while the original startup smoke parsed the health JSON and required status == "ok". Restore the body assertion in the shared helper so both modes verify the health payload instead of trusting the status code alone. * fix(webapi): preflight and verify native backup restores * test(webapi): isolate restore preflight smoke from systemd * test(webapi): set Windows smoke autostart default * test(webapi): retry transient Windows smoke cleanup * test(webapi): retry Windows smoke temp cleanup longer * ci(webapi): check whitespace on workflow dispatch
15 KiB
v2rayN.WebAPI
v2rayN.WebAPI is a headless ASP.NET Core host for v2rayN's existing ServiceLib. It exposes
REST APIs, authenticated SSE/runtime events, setup and sessions, settings and options,
profiles/subscriptions, routing and DNS, backups, updates, and the existing Core runtime bridge.
It runs without a browser or desktop session. The API has no dependency on
Vue, React, Vite, Node.js, npm, or any frontend manifest.
The API only serves API endpoints; it does not host, inspect, or configure a WebUI. An independent WebUI or other HTTP client manages its own hosting and configuration.
Start the API
For a native install, unpack the API release ZIP and start the executable from its install directory:
cp .env.example .env
chmod 600 .env
# Set V2RAYN_WEB_API_KEY in .env for supervised, container, or remote deployments.
./v2rayN.WebAPI --foreground --no-open
On Linux, a terminal launch without flags starts the API in the background, detached from the
terminal, and prints its health endpoint. --foreground keeps it attached and stops it safely with
Ctrl+C, --stop stops the instance running for the same data directory, and --help prints every
option together with the common environment variables; --no-open suppresses the browser opener.
Detached children and later helper processes keep the launch context, so an instance started from a
terminal is never mistaken for a systemd-managed service (systemd exports INVOCATION_ID /
JOURNAL_STREAM to everything launched from such a terminal).
The default listener is http://127.0.0.1:5080. A local native install may temporarily leave
V2RAYN_WEB_API_KEY empty when all listeners are loopback (127.0.0.1, localhost, or
[::1]), then complete first-run setup through a direct loopback API client.
For LAN / NAS / headless / container / systemd deployments, preconfigure
V2RAYN_WEB_API_KEY. Systemd and containers require it even on loopback. Any non-loopback
listener (including 0.0.0.0, [::], wildcard/hostname bindings, and LAN IPs) fails startup
without this environment Key, even if a Key was previously saved through local setup.
The check uses the effective ASP.NET Core configuration, including ASPNETCORE_URLS,
command-line --urls, ASPNETCORE_HTTP_PORTS / ASPNETCORE_HTTPS_PORTS (wildcard bindings),
and Kestrel:Endpoints, respecting their precedence. With multiple URLs, one non-loopback
listener is enough to require a Key; request Host headers never determine exposure.
For remote access, set a Key before selecting e.g. ASPNETCORE_URLS=http://0.0.0.0:5080.
Protect it with a firewall/VPN or an HTTPS reverse proxy; do not expose it directly to the Internet.
GET /api/health is a non-sensitive health probe. After authentication, GET /api/status
reports the running Backend version, commit, runtime identifier, and runtime capability fields.
The API option endpoints (including /api/editor-options and DNS editor options) are authoritative
for values derived from ServiceLib; clients should consume these instead of copying enums or
option lists.
Authentication
V2RAYN_WEB_API_KEYis the Management Key. Exchange it only atPOST /api/auth/login.- Use the returned session token as
Authorization: Bearer <session-token>for protected REST endpoints. The Management Key is not a REST or SSE bearer token. POST /api/auth/sse-ticketreturns a short-lived, one-time ticket for/api/events.- Setup, login rate limits, session expiry/revocation, LAN/setup policy, DNS rebinding checks, and API authorization remain Backend-owned and apply equally to every client.
- The API never enables wildcard CORS. Client hosting and configuration are independent.
Browser/client origins and strict CORS
An independently hosted browser client can connect directly to this API:
V2RAYN_WEB_API_KEY=<your-management-key>
V2RAYN_WEB_ALLOWED_ORIGINS=https://client.example.com,https://another.example.com
Unset/empty origins deny cross-origin API requests. Entries must be exact HTTP(S) origins
(scheme, host and port); paths, queries, fragments, credentials, empty list entries and wildcard
hosts are rejected at startup. Default ports are normalized. https://good.example.com.evil.com
does not match https://good.example.com. No forwarding headers are used to determine origin.
The origin guard rejects disallowed Origin requests before rate limiting, session authorization,
SSE-ticket consumption or mutations. Origin-less native clients and same-origin clients retain
their existing behavior and still require session Bearer authentication for protected endpoints.
Allowed-origin OPTIONS preflights complete before session authorization. CORS supports GET,
HEAD, POST, PUT, DELETE and OPTIONS, Authorization / Content-Type, and exposes only
Content-Disposition for downloads. It does not enable credentials, cookies, wildcard origins
or blanket private-network preflight bypasses. SSE tickets and /api/events use the same policy.
The allowlist grants browser access, not authentication; trust every allowed browser/client origin.
A same-origin browser behind a TLS/path-prefix reverse proxy retains REST access even when
Kestrel sees an internal HTTP URL: browser-controlled Sec-Fetch-Site: same-origin identifies
that case. It does not grant CORS response headers, setup access or internal health diagnostics.
Same-site/cross-site browser requests still require an exact allowed origin. Native clients
cannot gain privileges by forging this header: they already have origin-less access and still
must authenticate with the same Management Key/session model.
First-run setup remains direct loopback + localhost/loopback Host + no forwarding headers,
and additionally requires same-origin (or an origin-less native request). Allowed CORS origins
cannot initialize a Management Key. /api/setup/status remains public and reports
setupAllowedFromThisRequest=false for standalone clients. LAN/remote/supervised deployment
must configure V2RAYN_WEB_API_KEY before startup. The historical private-network setup branch
was removed to align with the local-only initialization policy.
HTTPS public dashboards connecting to HTTP localhost/LAN remain subject to browser Local Network Access permissions and mixed-content restrictions. CORS cannot override them; verify REST and native EventSource in the target browser. Some browsers block HTTP LAN even with permission; use an HTTPS API or a same-origin reverse proxy. Never expose an unauthenticated/wildcard listener or disable the existing listener/Management Key policies to work around browser limits.
Non-API paths, including GET /, return 404. The launcher opens the API health endpoint,
not a client application. API packages contain no frontend installation directory or placeholder.
Prerelease update preferences
Update checks and installs default to each target's entry in CheckPreReleaseCoreTypes;
the API self-update target is v2rayN.WebAPI, independent of Desktop's v2rayN and Core targets.
A missing list or entry defaults to stable releases. An explicit preRelease=true or false
overrides the preference only for that request; batches use each target's own preference.
GET /api/core-updates returns checkPreReleaseCoreTypes. Pass this list to
PUT /api/core-updates/settings to save independent preferences (an empty list disables them).
Targets not exposed by this updater retain their stored preferences. For older clients that
omit the list, preRelease still applies to all exposed prerelease-capable targets, including
v2rayN.WebAPI; the response's legacy preRelease flag reflects the Web target's preference.
Build and test the Backend
Requires the .NET 10 SDK. No Node.js or npm is used by the Backend build, tests, native publish, Containerfile, or API release packaging.
bash Scripts/publish-native.sh linux-x64 # also linux-arm64 / linux-riscv64 / linux-loongarch64
bash Scripts/verify.sh
Scripts/verify.sh builds and tests the Backend, runs ServiceLib tests, checks startup/security,
and exercises API ZIP/self-update package boundaries and real different-layout Linux update,
rollback and invalid-executable rejection. Integration tests live under Tests/Integration/
(security defaults, release packaging dry-run, full-ZIP runtime, native update regression, and
the Windows smoke: Test-Windows.ps1 -Mode startup|update). The independent build-WebAPI.yml
workflow runs these checks, Windows x64/ARM64 build/startup smoke (the self-update
replacement/rollback smoke stays on win-x64), native Linux builds, and Linux container builds on
relevant PRs and pushes to master; it can also be dispatched manually or called by a release
workflow. Releases include Linux x64/ARM64/RISC-V 64/LoongArch 64 and Windows x64/ARM64 packages;
Linux containers are built for amd64 and arm64.
Tests/Integration/test-native-update-identity.py <previous-publish-dir> <candidate-publish-dir>
additionally exercises real native helper replacement and health-mismatch rollback with two
distinct versions, isolated data/ports and preserved unrelated file/Core markers. It never uses
user configuration.
Native self-update and legacy helpers
The update worker runs from a GUID-named copy of the current executable beside the installation (owner-only permissions on Linux). This keeps its single-file bundle path unchanged during replacement and rollback: .NET loads dependencies lazily, and replacing a running helper's own executable with a different bundle layout can break later assembly loads. On Linux the outer helper waits for the worker, propagates its result, and removes the copy; on Windows the detached helper waits for the prior process and schedules its own copy for deletion after exit. Configuration and data paths remain unchanged.
Tests/Integration/test-native-update-regression.sh <native-publish-directory> deliberately
changes the candidate's bundle layout with test-only assembly metadata; version-only fixtures can
conceal this failure. It checks actual replacement, rollback, invalid-executable rejection and
worker cleanup, and is included in Scripts/verify.sh.
Linux builds predating helper isolation need a one-time manual reinstall. Their already-running
old helper cannot gain this fix from the candidate package. Stop the instance, back up the
executable, build identity, data and .env, and install the corrected API package. For a failed
legacy update, retain the previous-application backup and verify the restored application's
health before discarding it. Systemd/container deployments remain check-only and use redeploy.
Pre-merge product rename and update migration
The directory, project file, namespace, assembly/executable, embedded resource names, build
identity file/product and updater target are now v2rayN.WebAPI. Launcher/update helpers,
native/package scripts, Containerfile, solution registration, CI and tests use that identity.
The lock is v2rayN.WebAPI.instance.lock; the build identity is v2rayN.WebAPI.build.json;
health headers are X-v2rayn-WebAPI-*; the update capability is WebAPI.self-update; update
progress/runtime-state files are WebAPI-update-progress.json and
WebAPI-update-runtime-state.json; workflow files are build-WebAPI.yml and
release-WebAPI.yml.
Old experimental v2rayN.Web installs require a one-time manual reinstall. Stop the old
instance first (including its systemd/container supervisor), back up data and .env, install
the new full package, update ExecStart/container entrypoint, and restore the retained data.
Do not run the two executables against the same data directory. There is no cross-name update
helper, executable alias or silent in-place migration. Old-product manifests/packages are not
accepted by the new updater; new WebAPI → WebAPI updates preserve the transactional helper,
health/PID/lock checks, atomic replacement/rollback and executable/Core/data boundaries.
Package staging checks Linux ELF64 headers/program tables (x86-64, AArch64, RISC-V, LoongArch) or
Windows PE32+ headers (AMD64, ARM64) against the declared RID before replacement; a script,
truncated image, or wrong-architecture candidate cannot reach shutdown/swap merely by carrying
the correct JSON identity.
API-owned SelectedCoreTypes and CheckPreReleaseCoreTypes entries v2rayN.Web are normalized
to v2rayN.WebAPI at startup; legacy settings payloads are also normalized. Desktop/Core/hidden
preferences are preserved. This migrates preferences, not the executable or package identity.
Intentional compatibility names remain: V2RAYN_WEB_* configuration (including the Management
Key and allowed-origin variables), WebVersion/WebCommit/WebBuildDate/WebRepository build metadata,
webVersion and related status fields, the /api/web-updates routes, generic Web host/security
class names, existing systemd unit / install-path examples, and the legacy guiConfigs/web-auth.json
location that WebAuthStorage migrates to WebAPIData/WebAPI-auth.json. These are not stale
executable assumptions.
Releases and containers
build-all.yml ("release all platforms") dispatches the desktop platform workflows and calls
release-WebAPI.yml; the WebAPI packages ride the same upload-sign.yml path and land in the same
release as the desktop assets. release-WebAPI.yml can also be dispatched directly with a
release_tag (x.y.z) to call build-WebAPI.yml, assemble and validate the Linux and Windows
WebAPI assets, then sign and upload them through the existing upload-sign.yml workflow. Signing
uses the repository GPG key, so a fork that runs this flow publishes with its own
GPG_PRIVATE_KEY secret. build-WebAPI.yml can also be dispatched with a tag for package-only
verification. Web release orchestration and artifact names are RID-based, separately from
containers and Desktop workflows. riscv64 builds on RISC-V runners with the community .NET SDK;
loongarch64 builds inside the QEMU loong64 VM with the official Loongson SDK; both run a native
smoke before packaging. Windows x64/ARM64 have full-install and app-only update ZIPs; Windows
containers are not built.
The API release provides architecture-specific full-install and app-only update ZIPs plus
WebAPI-update.json:
v2rayN-linux-64-WebAPI.zip/v2rayN-linux-arm64-WebAPI.zip/v2rayN-linux-riscv64-WebAPI.zip/v2rayN-linux-loong64-WebAPI.zip— API, runtime files,.env.example, and Core bundle.v2rayN-linux-64-WebAPI-update.zip/v2rayN-linux-arm64-WebAPI-update.zip/v2rayN-linux-riscv64-WebAPI-update.zip/v2rayN-linux-loong64-WebAPI-update.zip— API executable and build identity only; user data, Core files, credentials, and unrelated files are excluded.v2rayN-windows-64-WebAPI.zip/v2rayN-windows-arm64-WebAPI.zip— Windows API, runtime/Core files, and.env.example.v2rayN-windows-64-WebAPI-update.zip/v2rayN-windows-arm64-WebAPI-update.zip— Windows API executable and build identity only; user data, Core files, credentials, and unrelated files are excluded.WebAPI-update.json— version, commit, per-RID asset names, sizes, and SHA-256 digests. A RID entry a build does not recognize is ignored instead of rejecting the manifest.
For Docker/Podman, the included Containerfile builds only the API and Core runtime.
The Compose example requires a non-empty Management Key.
See FEATURE-MAP.md for the current ServiceLib/API feature boundary.