From 45643fbed1c92a009b16e9184064bc1c1b7dde92 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=B8=96=E7=95=8C?= <i@sekai.icu>
Date: Wed, 20 Jul 2022 07:36:06 +0800
Subject: [PATCH] Add documentation for clash_api

---
 docs/configuration/experimental.md | 39 ++++++++++++++++++++++++++++++
 docs/configuration/index.md        | 18 ++++++++------
 docs/index.md                      | 13 +++++++++-
 experimental/clashapi/server.go    | 10 +++++++-
 mkdocs.yml                         |  1 +
 option/experimental.go             |  1 +
 6 files changed, 72 insertions(+), 10 deletions(-)
 create mode 100644 docs/configuration/experimental.md

diff --git a/docs/configuration/experimental.md b/docs/configuration/experimental.md
new file mode 100644
index 00000000..a2f80787
--- /dev/null
+++ b/docs/configuration/experimental.md
@@ -0,0 +1,39 @@
+### Structure
+
+```json
+{
+  "experimental": {
+    "clash_api": {
+      "external_controller": "127.0.0.1:9090",
+      "external_ui": "folder",
+      "secret": ""
+    }
+  }
+}
+```
+
+### Clash API Fields
+
+!!! error ""
+
+    Clash API is not included by default, see [Installation](/#Installation).
+
+!!! note ""
+
+    Traffic statistics and connection management will disable TCP splice in linux and reduce performance, use at your own risk.
+
+#### external_controller
+
+RESTful web API listening address. Disabled if empty.
+
+#### external_ui
+
+A relative path to the configuration directory or an absolute path to a
+directory in which you put some static web resource. Clash core will then
+serve it at `http://{{external-controller}}/ui`.
+
+#### secret
+
+Secret for the RESTful API (optional)
+Authenticate by spedifying HTTP header `Authorization: Bearer ${secret}`
+ALWAYS set a secret if RESTful API is listening on 0.0.0.0
\ No newline at end of file
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 0b8a54a5..4f13ada6 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -10,19 +10,21 @@ sing-box uses JSON for configuration files.
   "dns": {},
   "inbounds": {},
   "outbounds": {},
-  "route": {}
+  "route": {},
+  "experimental": {}
 }
 ```
 
 ### Fields
 
-| Key         | Format                 |
-|-------------|------------------------|
-| `log`       | [Log](./log)           |
-| `dns`       | [DNS](./dns)           |
-| `inbounds`  | [Inbound](./inbound)   |
-| `outbounds` | [Outbound](./outbound) |
-| `route`     | [Route](./route)       |
+| Key            | Format                         |
+|----------------|--------------------------------|
+| `log`          | [Log](./log)                   |
+| `dns`          | [DNS](./dns)                   |
+| `inbounds`     | [Inbound](./inbound)           |
+| `outbounds`    | [Outbound](./outbound)         |
+| `route`        | [Route](./route)               |
+| `experimental` | [Experimental](./experimental) |
 
 ### Check
 
diff --git a/docs/index.md b/docs/index.md
index 9223e20c..1d18fa86 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -9,9 +9,20 @@ The universal proxy platform.
 sing-box requires Golang 1.18 or a higher version.
 
 ```bash
-go install github.com/sagernet/sing-box/cmd/sing-box@latest
+go install -v github.com/sagernet/sing-box/cmd/sing-box@latest
 ```
 
+Install with options:
+
+```bash
+go install -v -tags "with_clash_api,no_gvisor" github.com/sagernet/sing-box/cmd/sing-box@latest
+```
+
+| Build Tag        | Description                                                                             |
+|------------------|-----------------------------------------------------------------------------------------|
+| `with_clash_api` | Build with clash api support, see [Experimental](./configuration/experimental).         |
+| `no_gvisor`      | Build without gVisor, which required by the [Tun](./configuration/inbound/tun) inbound. |
+
 The binary is built under $GOPATH/bin
 
 ```bash
diff --git a/experimental/clashapi/server.go b/experimental/clashapi/server.go
index d7a4cfd0..46aec394 100644
--- a/experimental/clashapi/server.go
+++ b/experimental/clashapi/server.go
@@ -58,7 +58,15 @@ func NewServer(router adapter.Router, logFactory log.ObservableFactory, options
 		r.Mount("/profile", profileRouter())
 		r.Mount("/cache", cacheRouter())
 	})
-
+	if options.ExternalUI != "" {
+		chiRouter.Group(func(r chi.Router) {
+			fs := http.StripPrefix("/ui", http.FileServer(http.Dir(options.ExternalUI)))
+			r.Get("/ui", http.RedirectHandler("/ui/", http.StatusTemporaryRedirect).ServeHTTP)
+			r.Get("/ui/*", func(w http.ResponseWriter, r *http.Request) {
+				fs.ServeHTTP(w, r)
+			})
+		})
+	}
 	return &Server{
 		logFactory.NewLogger("clash-api"),
 		&http.Server{
diff --git a/mkdocs.yml b/mkdocs.yml
index 8620f839..2deef2e3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -62,6 +62,7 @@ nav:
           - Geosite: configuration/route/geosite.md
           - Route Rule: configuration/route/rule.md
           - Protocol Sniff: configuration/route/sniff.md
+      - Experimental: configuration/experimental.md
   - Examples:
       - examples/index.md
       - Shadowsocks Server: examples/ss-server.md
diff --git a/option/experimental.go b/option/experimental.go
index 10fcc661..3af9aa42 100644
--- a/option/experimental.go
+++ b/option/experimental.go
@@ -6,5 +6,6 @@ type ExperimentalOptions struct {
 
 type ClashAPIOptions struct {
 	ExternalController string `json:"external_controller,omitempty"`
+	ExternalUI         string `json:"external_ui,omitempty"`
 	Secret             string `json:"secret,omitempty"`
 }