mirror of
https://github.com/2dust/v2rayN.git
synced 2026-10-24 06:04:59 +03:00
feat(web): 添加无头 WebAPI 支持 (#10300)
* 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
This commit is contained in:
Nozilla-X
@@ -0,0 +1,238 @@
|
||||
# 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:
|
||||
|
||||
```sh
|
||||
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_KEY` is the Management Key. Exchange it only at `POST /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-ticket` returns 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:
|
||||
|
||||
```ini
|
||||
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.
|
||||
|
||||
```sh
|
||||
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`](FEATURE-MAP.md) for the current ServiceLib/API feature boundary.
|
||||
Reference in New Issue
Block a user