From e8206046faf0c0563a75396a49eae93fc199f707 Mon Sep 17 00:00:00 2001
From: Arvin <62139570+wnlen@users.noreply.github.com>
Date: Tue, 16 Jun 2026 16:48:42 +0800
Subject: [PATCH] Improve GitHub download mirror visibility and pool (#273)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add kkgithub.com (hostpath) to the default mirror pool alongside the
  existing gh-proxy.org / ghfast.top / ghproxy.net entries; all four
  verified reachable and capable of proxying GitHub release downloads.

- Add doctor_download_mirrors() section to 'clashctl doctor': shows
  whether a custom mirror (CLASH_GH_PROXY / CLASH_GH_PROXY_POOL) is
  active or the built-in pool is in use, last successful/failed mirror
  URL from the state file, and a one-liner hint for setting a custom
  mirror prefix.

- README: add 'GitHub 下载加速' subsection under .env config to explain
  that all GitHub assets (kernel, GEO data, yq, subconverter, dashboard)
  automatically go through the mirror pool, document CLASH_GH_PROXY and
  CLASH_GH_PROXY_POOL env vars with examples, and point users to
  ghproxy.link for a live mirror list and 'clashctl doctor' for status.
---
 README.md                | 17 +++++++++++++++++
 scripts/core/clashctl.sh | 32 ++++++++++++++++++++++++++++++++
 scripts/core/common.sh   |  1 +
 3 files changed, 50 insertions(+)

diff --git a/README.md b/README.md
index 61f10ac..05558b3 100644
--- a/README.md
+++ b/README.md
@@ -296,6 +296,23 @@ CLASH_BUNDLED_ASSET_ENABLED=true
 
 按需设置即可，不需要每项都写。
 
+#### GitHub 下载加速
+
+所有来自 GitHub 的资源（内核、GEO 数据、yq、subconverter、Dashboard）在下载时会自动尝试内置镜像池（`gh-proxy.org`、`ghfast.top`、`ghproxy.net`、`kkgithub.com`），无需额外配置即可加速。
+
+如果默认镜像不满足需求，可在 `.env` 中指定自定义加速前缀：
+
+```bash
+# 单个自定义镜像（优先于内置镜像池）
+CLASH_GH_PROXY=https://ghfast.top
+
+# 自定义镜像池（完全替换内置池，格式：label|prefix|mode，mode 可选 full/hostpath）
+# CLASH_GH_PROXY_POOL="mymirror|https://mirror.example.com|full"
+```
+
+可用镜像列表参考：<https://ghproxy.link/>  
+当前镜像使用状态可通过 `clashctl doctor` 查看。
+
 ### 内置运行依赖
 
 当前正式支持的架构为 `amd64`、`arm64`、`armv7`。超出这三种架构时会明确失败，不会伪装成已支持。
diff --git a/scripts/core/clashctl.sh b/scripts/core/clashctl.sh
index 75c7b1e..7d1834d 100644
--- a/scripts/core/clashctl.sh
+++ b/scripts/core/clashctl.sh
@@ -3306,6 +3306,37 @@ doctor_dependencies() {
   fi
 }
 
+doctor_download_mirrors() {
+  doctor_print_title "下载加速配置"
+
+  local custom_prefix pool_source
+  custom_prefix="$(github_proxy_prefix 2>/dev/null || true)"
+
+  if [ -n "${custom_prefix:-}" ]; then
+    doctor_ok "自定义镜像（CLASH_GH_PROXY）：${custom_prefix}"
+    pool_source="custom"
+  elif [ -n "${CLASH_GH_PROXY_POOL:-}" ]; then
+    doctor_ok "自定义镜像池（CLASH_GH_PROXY_POOL）已配置"
+    pool_source="custom-pool"
+  else
+    doctor_ok "使用内置默认镜像池（gh-proxy.org / ghfast.top / ghproxy.net / kkgithub.com）"
+    pool_source="default"
+  fi
+
+  # Show mirror history from state file
+  local state_file mirror_info last_ok last_fail
+  state_file="$(download_mirror_state_file 2>/dev/null || true)"
+  if [ -f "${state_file:-}" ]; then
+    last_ok="$(grep 'LAST_SUCCESS_URL' "$state_file" 2>/dev/null | tail -n 1 | sed 's/.*=//;s/"//g' || true)"
+    last_fail="$(grep 'LAST_FAILURE_URL' "$state_file" 2>/dev/null | tail -n 1 | sed 's/.*=//;s/"//g' || true)"
+    [ -n "${last_ok:-}" ] && doctor_ok "上次成功镜像：${last_ok}"
+    [ -n "${last_fail:-}" ] && doctor_warn "上次失败镜像：${last_fail}"
+  fi
+
+  doctor_ok "配置提示：在 .env 中设置 CLASH_GH_PROXY=https://your-mirror.com 可指定自定义加速前缀"
+  doctor_ok "可用镜像列表参考：https://ghproxy.link/"
+}
+
 doctor_config() {
   local config_file active_profile mixed_port controller controller_secret_value external_ui_path dashboard_source
 
@@ -3868,6 +3899,7 @@ cmd_doctor() {
   ui_section "详细检查"
   doctor_install_context
   doctor_dependencies
+  doctor_download_mirrors
   doctor_container_tun
   doctor_tun_system_proxy
   doctor_config
diff --git a/scripts/core/common.sh b/scripts/core/common.sh
index 96fb59d..4207cca 100644
--- a/scripts/core/common.sh
+++ b/scripts/core/common.sh
@@ -555,6 +555,7 @@ default_github_mirror_pool() {
 gh-proxy|https://gh-proxy.org|full
 ghfast|https://ghfast.top|hostpath
 ghproxy-net|https://ghproxy.net|hostpath
+kkgithub|https://kkgithub.com|hostpath
 EOF
 }