Add dashboard support for API service

2026-06-13 23:00:53 +08:00
parent a14fd97b5c
commit 79ee5b3cc0
9 changed files with 521 additions and 7 deletions
@@ -119,7 +119,16 @@ HTTP Client for downloading rule-set.

 See [HTTP Client Fields](/configuration/shared/http-client/) for details.

-Default transport will be used if empty.
+When empty, the default HTTP client is used: the one named by
+[`default_http_client`](/configuration/route/#default_http_client), or the first top-level
+`http_clients` entry when `default_http_client` is empty.
+
+!!! failure "Implicit default deprecated in sing-box 1.14.0"
+
+    When neither `http_clients` nor `default_http_client` is configured, an implicit HTTP
+    client connecting through the default outbound is used. This implicit default is
+    deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0; define
+    `http_clients` instead.

 #### update_interval

@@ -119,7 +119,13 @@

 参阅 [HTTP 客户端字段](/zh/configuration/shared/http-client/) 了解详情。

-如果为空，将使用默认传输。
+留空时使用默认 HTTP 客户端：即由 [`default_http_client`](/zh/configuration/route/#default_http_client)
+指定的客户端，或当 `default_http_client` 为空时使用顶级 `http_clients` 的第一项。
+
+!!! failure "隐式默认已在 sing-box 1.14.0 废弃"
+
+    当 `http_clients` 与 `default_http_client` 均未配置时，将使用通过默认出站连接的隐式 HTTP 客户端。
+    该隐式默认已在 sing-box 1.14.0 废弃，并将在 sing-box 1.16.0 移除；请改为定义 `http_clients`。

 #### update_interval

@@ -23,6 +23,13 @@ for bidirectional streaming methods.
  "secret": "",
  "access_control_allow_origin": [],
  "access_control_allow_private_network": false,
+  "dashboard": {
+    "enabled": true,
+    "path": "",
+    "download_url": "",
+    "http_client": "", // or {}
+    "update_interval": ""
+  },
  "tls": {}
 }
 ```
@@ -49,6 +56,59 @@ CORS allowed origins, `*` will be used if empty.

 Allow access from private network.

+#### dashboard
+
+Web dashboard downloaded and served over the API listener at `/dashboard/`; other browser
+requests are redirected to it.
+
+!!! info ""
+
+    The object can be replaced with a boolean value (equivalent to `{ "enabled": <bool> }`),
+    or with a string path (equivalent to `{ "enabled": true, "path": "<string>" }`).
+
+##### enabled
+
+Enable the dashboard.
+
+##### path
+
+Directory the dashboard files are stored in.
+
+`dashboard` in the working directory will be used by default.
+
+If the directory is empty, the dashboard is downloaded and an `.etag` file is stored inside
+it to skip unchanged updates. A non-empty directory without an `.etag` file is served as-is
+and never updated automatically.
+
+##### download_url
+
+Download URL of the dashboard archive (zip).
+
+`https://github.com/SagerNet/sing-box-dashboard/archive/refs/heads/gh-pages.zip` will be used by default.
+
+##### http_client
+
+HTTP client used to download the dashboard, with the same behavior as remote rule-sets.
+
+See [HTTP Client Fields](/configuration/shared/http-client/) for details.
+
+When empty, the default HTTP client is used: the one named by
+[`default_http_client`](/configuration/route/#default_http_client), or the first top-level
+`http_clients` entry when `default_http_client` is empty.
+
+!!! failure "Implicit default deprecated in sing-box 1.14.0"
+
+    When neither `http_clients` nor `default_http_client` is configured, an implicit HTTP
+    client connecting through the default outbound is used. This implicit default is
+    deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0; define
+    `http_clients` instead.
+
+##### update_interval
+
+Update interval of the dashboard.
+
+`1d` will be used by default.
+
 #### tls

 TLS configuration, see [TLS](/configuration/shared/tls/#inbound).
@@ -22,6 +22,13 @@ sing-box API 服务是用于观察与控制正在运行的 sing-box 实例的 gR
  "secret": "",
  "access_control_allow_origin": [],
  "access_control_allow_private_network": false,
+  "dashboard": {
+    "enabled": true,
+    "path": "",
+    "download_url": "",
+    "http_client": "", // 或 {}
+    "update_interval": ""
+  },
  "tls": {}
 }
 ```
@@ -38,7 +45,7 @@ API 密钥。

 客户端通过标准的 `authorization: Bearer <secret>` gRPC metadata 头认证。

-留空则禁用认证。
+默认无需认证。

 #### access_control_allow_origin

@@ -48,6 +55,54 @@ API 密钥。

 允许从私有网络访问。

+#### dashboard
+
+下载并通过 API 监听器在 `/dashboard/` 提供的 Web 仪表板；其他浏览器请求将被重定向到该路径。
+
+!!! info ""
+
+    该对象可以替换为布尔值（等同于 `{ "enabled": <bool> }`），
+    或字符串路径（等同于 `{ "enabled": true, "path": "<string>" }`）。
+
+##### enabled
+
+启用仪表板。
+
+##### path
+
+存放仪表板文件的目录。
+
+默认使用工作目录下的 `dashboard`。
+
+如果目录为空，将下载仪表板，并在其中存放 `.etag` 文件以跳过未变更的更新。
+非空且不含 `.etag` 文件的目录将按原样提供，且不会自动更新。
+
+##### download_url
+
+仪表板压缩包（zip）的下载 URL。
+
+默认使用 `https://github.com/SagerNet/sing-box-dashboard/archive/refs/heads/gh-pages.zip`。
+
+##### http_client
+
+用于下载仪表板的 HTTP 客户端，行为与远程规则集相同。
+
+参阅 [HTTP 客户端字段](/zh/configuration/shared/http-client/)。
+
+留空时使用默认 HTTP 客户端：即由 [`default_http_client`](/zh/configuration/route/#default_http_client)
+指定的客户端，或当 `default_http_client` 为空时使用顶级 `http_clients` 的第一项。
+
+!!! failure "隐式默认已在 sing-box 1.14.0 废弃"
+
+    当 `http_clients` 与 `default_http_client` 均未配置时，将使用通过默认出站连接的隐式 HTTP 客户端。
+    该隐式默认已在 sing-box 1.14.0 废弃，并将在 sing-box 1.16.0 移除；请改为定义 `http_clients`。
+
+##### update_interval
+
+仪表板的更新间隔。
+
+默认使用 `1d`。
+
 #### tls

 TLS 配置,参阅 [TLS](/zh/configuration/shared/tls/#inbound)。