UI 面板

本仓库包含一个本地 UI 面板，用于查看节点、连接、规则、日志，并提供基础的配置写入能力。

组成与数据流

• ui/：React 前端（Vite 构建）。
• controller-ui/：本地控制台服务（Node.js），提供 /api/* 接口并代理到核心。

数据流：

1. 浏览器访问 controller-ui 暴露的页面；
2. 前端调用 controller-ui 的 /api/*；
3. controller-ui 通过 HTTP 调用核心 metrics API，并通过 gRPC 读取出站/观测信息。

启动与构建

构建前端（生成 ui/dist）：

cd ui
npm install
npm run build

启动 controller：

cd controller-ui
npm install
npm run start

默认端口为 5100（可用 PORT 环境变量覆盖）。

controller-ui 配置

controller 默认读取 controller-ui/settings.json，路径可通过 SETTINGS_FILE 修改。
常用环境变量：

• XRAY_GRPC：核心 gRPC 地址（默认 127.0.0.1:10085）
• XRAY_METRICS：核心 metrics 地址（默认 http://127.0.0.1:8080）
• XRAY_METRICS_KEY：metrics HTTP 访问密钥
• PORT：controller 监听端口
• UI_DIST：前端静态文件目录（默认 ui/dist）
• LOG_FILE：controller 直接读取的日志文件路径
• HOT_RELOAD_FILE：（deprecated）旧版用于 touch 文件触发外部热更新；当前建议直接调用核心 metrics 的 POST /core/hotreload（重新载入启动配置并尽可能在不重启的情况下应用）
• RESTART_COMMAND：外部重启命令
• BALANCER_TAGS：限定展示的 balancer tags（逗号分隔）
• OBSERVATORY_PROBE_MODE：默认探测模式

核心侧 UI 文件

核心 metrics 会维护以下文件：

• xray.ui.json：UI/metrics 设置 + UI 状态（controller.uiState，通过 /settings 与 /ui/state 更新）
• 当主配置文件（包含 log 的那份）为 YAML 时，以上内容会写入 xray.ui.yaml

路径由 core 自动推断，也可通过 SETTINGS_FILE 覆盖。若需要使用独立的 UI 状态文件（兼容模式），可通过 UI_STATE_FILE 指定。

WARNING

若使用独立 UI 状态文件（UI_STATE_FILE），请避免将该文件放入 -confdir 目录中。

UI 使用的 /api 接口

以下为 controller 对外暴露的主要接口（/api/*），其内部会代理到核心 metrics 或 gRPC：

状态与设置

• GET /api/health
• GET /api/settings / POST /api/settings（controller 设置）
• GET /api/ui/state / POST /api/ui/state（代理到核心）

连接与节点

• GET /api/connections
• GET /api/connections/stream
• POST /api/connections/close
• GET /api/nodes
• POST /api/balancer/override（{ balancerTag, target }；target: "" 表示清除覆写）
• GET /api/balancer/:tag
• GET /api/outbounds

路由与配置

• GET /api/rules
• GET /api/config/routing
• POST /api/config/routing
• GET /api/config/subscription
• POST /api/config/subscription

日志与控制

• GET /api/logs
• GET /api/logs/stream
• POST /api/core/hotreload
• POST /api/core/restart

更多核心侧 metrics API 详情请参考 Metrics。