v2rayN WebAPI / WebUI 配置指南

[Nozilla-X]

v2rayN WebAPI ⁄ WebUI 配置指南.md

[2dust]

v2rayN WebAPI / WebUI 配置指南

v2rayN 提供独立的 WebAPI 后端，可用于 Linux、Windows、NAS、服务器及无桌面环境。

WebAPI 与 WebUI 完全解耦：

• v2rayN.WebAPI：提供 v2rayN 后端能力，包括Core 管理、配置、订阅、路由、DNS、更新等 API。
• v2rayN WebUI：独立的静态网页客户端，通过 HTTP(S) 连接 WebAPI，目前已部署在 GitHub Pages。
• WebAPI 不内置、不托管、也不依赖 WebUI。
• WebUI 可以单独部署，也可以使用已经部署好的 WebUI。
• WebAPI 不需要 Node.js、npm、Vue 等前端运行环境。

项目：

• WebAPI: https://github.com/2dust/v2rayN
• WebUI: https://github.com/2dust/v2rayN-WebUI
• 示例 WebUI: https://nozilla-x.github.io/v2rayN-WebUI/

---

1. 下载 WebAPI

从 v2rayN Releases 中选择与你的平台和架构对应的 WebAPI 完整包。

例如：

v2rayN-linux-64-WebAPI.zip
v2rayN-linux-arm64-WebAPI.zip
v2rayN-linux-riscv64-WebAPI.zip
v2rayN-linux-loong64-WebAPI.zip

v2rayN-windows-64-WebAPI.zip
v2rayN-windows-arm64-WebAPI.zip

首次安装请使用普通的 WebAPI.zip 完整包。

名称中带有： -WebAPI-update.zip 的是 WebAPI 自更新（或手动更新）使用的增量包，不适合作为首次安装包。

---

2. 最简单的本地启动

WebAPI 默认地址：

# 监听地址
http://127.0.0.1:5080
# 健康检查地址
http://127.0.0.1:5080/api/health

Linux

解压后进入 WebAPI 目录：

cp .env.example .env
chmod 600 .env
# 以下启动命令在完成“3. `.env` 配置”后使用，可按需选择

# 以后台方式启动并脱离当前终端，默认行为
./v2rayN.WebAPI
# 以前台方式启动，日志输出至终端，可按 Ctrl + C 停止
./v2rayN.WebAPI --foreground

停止后台实例：

./v2rayN.WebAPI --stop

--stop 当前仅适用于 Linux，Windows 用户请使用任务管理器。
systemd 管理的实例请使用 systemctl stop。

Windows

复制配置后启动：

Copy-Item .env.example .env
# 以下启动命令在完成“3. `.env` 配置”后使用，可按需选择

# 默认以前台方式启动
.\v2rayN.WebAPI.exe
# 需要后台运行时
.\v2rayN.WebAPI.exe --background

---

3. .env 配置

WebAPI 会读取程序目录中的 .env。

一个常见的配置如下：

# 管理密钥，可通过`openssl rand -hex 32`生成填入
V2RAYN_WEB_API_KEY=change-this-to-a-random-management-key

# 监听地址（见注意事项及详情1）
ASPNETCORE_URLS=http://127.0.0.1:5080

# 是否自启即打开内核？
V2RAYN_WEB_AUTOSTART=true

# 允许浏览器跨域访问 WebAPI 的 WebUI 来源（见注意事项及详情2）
# V2RAYN_WEB_ALLOWED_ORIGINS=https://example.com

# 覆盖代理监听端口，默认10808
# V2RAYN_WEB_PROXY_PORT=10808

# 代理是否监听0.0.0.0（局域网是否可以访问代理）？默认false。
# V2RAYN_WEB_PROXY_LISTEN_ALL=false

# 指定V2rayN数据目录位置，默认启动路径下
# V2RAYN_DATA_HOME=/path/to/v2rayn-data

注意事项及详情1

可以有以下使用情况：

# 默认
ASPNETCORE_URLS=http://127.0.0.1:5080
# 监听所有网络
ASPNETCORE_URLS=http://0.0.0.0:5080
# 监听特定地址
ASPNETCORE_URLS=http://192.168.1.10:5080

只要监听地址不是 loopback，本项就必须同时配置 V2RAYN_WEB_API_KEY。

包括：

0.0.0.0
[::]
局域网 IP
主机名
通配监听地址

都属于非 loopback 监听。

注意事项及详情2

填写我的示例WebUI即可：

V2RAYN_WEB_ALLOWED_ORIGINS=https://nozilla-x.github.io

也可自建，多个来源可使用逗号分隔，目前不支持路径和通配符：

V2RAYN_WEB_ALLOWED_ORIGINS=https://example.com,https://web.example.net

4. 常用启动参数

查看完整帮助：

./v2rayN.WebAPI --help

常用参数：

参数	说明
--foreground	前台运行，日志输出到终端，可使用 Ctrl+C 停止
--background	后台运行并脱离终端
--no-open	启动时不自动打开浏览器
--stop	停止同一数据目录中的后台实例，仅 Linux
--help / -h	显示帮助

其他 ASP.NET Core 参数也可以直接传递。

例如：

./v2rayN.WebAPI --foreground --urls http://0.0.0.0:5080

非 loopback 地址仍然要求预先设置 V2RAYN_WEB_API_KEY。

---

5. 使用 WebUI

WebUI 与 WebAPI 是两个独立程序。

可以：

1. 自己部署 WebUI；
2. 使用其他人部署的兼容 WebUI；
3. 使用在线 WebUI。

例如：

https://nozilla-x.github.io/v2rayN-WebUI/

打开 WebUI 后，在登录页面直接填写 IP + 端口即可：

# 例如本机：
http://127.0.0.1:5080
# 局域网：
http://192.168.1.10:5080
# HTTPS 反向代理：
https://v2rayn-api.example.com

测试连接成功后，填入 WebAPI 的 Management Key 登录。

---

浏览器限制

HTTPS WebUI 访问 HTTP localhost/LAN 时，还会受到浏览器的影响：

• Mixed Content
• Local Network Access
• 浏览器安全策略

这些限制和 CORS 是不同的。

因此即使：V2RAYN_WEB_ALLOWED_ORIGINS设置正确，浏览器仍有可能阻止 HTTPS 页面直接连接 HTTP 局域网地址。

如果出现这种情况，推荐使用：

• HTTPS WebAPI；
• HTTPS 反向代理；
• WebUI 与 WebAPI 同源部署。

不要通过关闭浏览器安全机制或者关闭 WebAPI 的安全检查来解决。

6. Docker / Podman

仓库提供：

Containerfile
compose.yaml

容器模式必须配置：

V2RAYN_WEB_API_KEY

即使容器内部只监听 loopback，也不能留空。

例如：

export V2RAYN_WEB_API_KEY="$(openssl rand -hex 32)"
docker compose up -d --build

仓库提供的 Compose 示例默认将宿主机端口绑定到：

127.0.0.1

因此默认不会直接暴露给局域网。

如需 LAN 访问，请根据自己的网络环境调整 Compose 的端口绑定，同时务必保留 Management Key，并配置防火墙。

数据保存在持久化 /data Volume 中。在SELinux生效的情况下，您可能需要在挂载路径添加:z标签。

---

7. First-run Setup 限制

为了避免未初始化的 WebAPI 被远程接管，首次设置 Management Key 有额外限制。只有直接的本机 loopback 请求才能执行首次 Setup。

跨域 WebUI 即使已经加入：V2RAYN_WEB_ALLOWED_ORIGINS也不能远程执行首次初始化。

因此对于 NAS、服务器、容器或局域网部署，推荐在第一次启动前就直接配置 V2RAYN_WEB_API_KEY。