feat(config): introduce optional checks in health checks and update example configurations

- Added support for optional checks in the health check system, allowing certain checks to be marked as warnings instead of failures.
- Updated the RunConfig struct to include an OptionalChecks field for specifying these checks.
- Modified example configuration files to include "optional_checks" for better flexibility in health checks.
- Enhanced the UI to reflect the status of optional checks, providing clearer feedback on their results.

This update improves the robustness of health checks and enhances user experience by clearly distinguishing between critical and non-critical checks.

Author: hiddifydeveloper

cmd/main.go

@@ -180,7 +180,10 @@ func checkCmd() *cobra.Command {
 			// Read run.json to know the core, then call core.Check.
 			// For now: just verify run.json parses and referenced config files exist.
 			path := filepath.Join(args[0], "run.json")
-			if _, err := os.Stat(path); err != nil {
+			pathJ2 := filepath.Join(args[0], "run.json.j2")
+			_, err1 := os.Stat(path)
+			_, err2 := os.Stat(pathJ2)
+			if err1 != nil && err2 != nil {
 				return fmt.Errorf("run.json not found in %s", args[0])
 			}
 			fmt.Println("OK")
@@ -270,10 +273,17 @@ func findExamples(root string) ([]string, error) {
 		if err != nil || d.IsDir() {
 			return nil
 		}
-		if d.Name() != "run.json" {
+		if d.Name() != "run.json" && d.Name() != "run.json.j2" {
 			return nil
 		}
 		dir := filepath.Join(root, filepath.Dir(path))
+		// A dir with both run.json and run.json.j2 is visited twice; the .j2
+		// is the source of truth, so skip the plain run.json in that case.
+		if d.Name() == "run.json" {
+			if _, err := os.Stat(filepath.Join(dir, "run.json.j2")); err == nil {
+				return nil
+			}
+		}
 		// Skip "inheritance-only" run.json files that have no config files
 		// alongside them (no .json/.j2/.tpl other than run.json itself).
 		if !hasConfigFiles(dir) {

examples/sing-box/shadowsocks/run.json

@@ -14,5 +14,6 @@
   ],
 
   "checks": ["dns", "http", "quic"],
+  "optional_checks": ["quic"],
   "timeout_sec": 30,
 }

examples/sing-box/vless-xhttp/run.json

@@ -16,5 +16,6 @@
   ],
 
   "checks": ["dns", "http", "quic", "speedtest"],
+  "optional_checks": ["quic"],
   "timeout_sec": 30,
 }

examples/xray/vless-vision/client.json.j2

@@ -0,0 +1,22 @@
+{% extends "../templates/base/client.json.j2" %}
+
+{% block outbound %}
+{
+  "tag": "proxy",
+  "protocol": "vless",
+  "settings": {
+    "vnext": [
+      {
+        "address": "{{ SERVER }}",
+        "port": {{ PORT }},
+        "users": [{"id": "{{ UUID }}", "encryption": "{{ VLESS_ENC }}", "flow": "{{ VLESS_FLOW }}"}]
+      }
+    ]
+  },
+  "streamSettings": {
+    "network": "tcp",
+    {% include "../templates/tls/client.tpl" %}
+    "tcpSettings": {}
+  }
+}
+{% endblock %}

examples/xray/vless-vision/run.json.j2

@@ -0,0 +1,26 @@
+{
+  // VLESS + XTLS-Vision (xray-core) — raw TCP + TLS + xtls-rprx-vision flow.
+  // This is the canonical "one good protocol" setup: VLESS over TCP with
+  // real TLS and the Vision flow control (anti-active-probing). Inherits
+  // binary paths and deploy settings from ../run.json and ../../run.json.
+  "name": "VLESS + Vision (xray)",
+  "server_config": "server",
+  "client_config": "client",
+  "tls": true,
+
+  "vars": [
+    {
+      "TITLE":      "vless-vision",
+      "TLS":        "1",
+      "VLESS_ENC":  "none",
+      "VLESS_DEC":  "none",
+      "VLESS_FLOW": "xtls-rprx-vision",
+      "HOST_NAME":  "127.0.0.1",
+      "SNI_NAME":   "127.0.0.1",
+    },
+  ],
+
+  "checks": ["dns", "http", "quic", "speedtest"],
+  "optional_checks": ["quic"],
+  "timeout_sec": 30,
+}

examples/xray/vless-vision/server.json.j2

@@ -0,0 +1,24 @@
+{% extends "../templates/base/server.json.j2" %}
+
+{% block inbound %}
+{
+  "tag": "proxy-in",
+  "port": {{ PORT }},
+  "listen": "{{ SERVER }}",
+  "protocol": "vless",
+  "settings": {
+    "clients": [
+      {
+        "id": "{{ UUID }}",
+        "flow": "{{ VLESS_FLOW }}"
+      }
+    ],
+    "decryption": "{{ VLESS_DEC }}"
+  },
+  "streamSettings": {
+    "network": "tcp",
+    {% include "../templates/tls/server.tpl" %}
+    "tcpSettings": {}
+  }
+}
+{% endblock %}

examples/xray/vless-xhttp/run.json

@@ -26,5 +26,6 @@
     },
   ],
   "checks": ["dns", "http", "quic", "speedtest"],
+  "optional_checks": ["quic"],
   "timeout_sec": 30
 }

examples/xray/vless-xhttp/run.json.j2

@@ -6,20 +6,21 @@
   "client_config": "client",
   "tls": true,
 
+  // NOTE: xtls-rprx-vision flow is NOT valid over xHTTP — it requires raw
+  // TCP+TLS. See the vless-vision example for that. xHTTP uses flow "".
   "vars": [
-    {% for flow in ",xtls-rprx-vision"|split:"," %}
     {
-      "TITLE":      "{% if flow %}vless-flow{% else %}plain-tls{% endif %}",
+      "TITLE":      "plain-tls",
       "TLS":        "1",
       "VLESS_ENC":  "none",
       "VLESS_DEC":  "none",
-      "VLESS_FLOW": "{{ flow }}",
+      "VLESS_FLOW": "",
       "HOST_NAME":  "127.0.0.1",
       "SNI_NAME":   "127.0.0.1",
     },
-    {% endfor %}
   ],
 
   "checks": ["dns", "http", "quic", "speedtest"],
+  "optional_checks": ["quic"],
   "timeout_sec": 30,
 }

hiddify-health

@@ -86,6 +86,8 @@ func (c *Config) defaults() {
 type Result struct {
 	Name      string
 	OK        bool
+	// Optional marks a check whose failure is a warning, not a run failure.
+	Optional  bool
 	Duration  time.Duration
 	Err       error
 	// Extra human-readable detail (throughput, ping stats, …).