flvx/docs/superpowers/specs/2026-04-01-github-proxy-config-design.md

GitHub 加速地址自定义配置设计

日期: 2026-04-01 状态: 待审核 作者: AI Assistant

概述

允许用户在面板设置中自定义 GitHub 加速地址，支持开启/关闭加速功能。配置后，面板更新节点、生成安装命令以及安装脚本都使用配置的加速地址。

背景

当前 gcode.hostcentral.cc 硬编码在多个位置：

• go-backend/internal/http/handler/upgrade.go - 节点升级下载 URL
• go-backend/internal/http/handler/mutations.go - 节点安装命令生成
• install.sh - 节点安装脚本
• panel_install.sh - 面板安装脚本

用户无法自定义加速地址或关闭加速功能。

目标

1. 面板设置中支持配置加速开关和加速地址
2. 配置影响全部下载场景（面板端 + 安装脚本）
3. 安装脚本支持交互式询问加速配置
4. 面板生成的安装命令自动嵌入加速配置

影响范围

后端

• go-backend/internal/http/handler/upgrade.go
• go-backend/internal/http/handler/mutations.go

前端

• vite-frontend/src/pages/config.tsx
• vite-frontend/src/config/site.ts（缓存配置键）

安装脚本

• install.sh
• panel_install.sh

详细设计

1. 数据存储

使用现有 vite_config 表存储两个配置项：

name	value	说明
github_proxy_enabled	"true" / "false"	是否开启加速，默认 "true"
github_proxy_url	URL 字符串	加速地址，默认 "https://gcode.hostcentral.cc"

2. 后端 Handler 修改

upgrade.go

移除硬编码常量，新增辅助函数：

// getGithubProxyConfig 获取 GitHub 加速配置
// 返回: (是否开启, 加速地址)
func (h *Handler) getGithubProxyConfig() (enabled bool, proxyURL string) {
    enabled = true  // 默认开启
    proxyURL = "https://gcode.hostcentral.cc"  // 默认地址
    
    if h == nil || h.repo == nil {
        return
    }
    
    // 读取开启状态
    if enabledCfg, err := h.repo.GetConfigByName("github_proxy_enabled"); err == nil && enabledCfg != nil {
        enabled = enabledCfg.Value != "false"
    }
    
    // 读取加速地址
    if urlCfg, err := h.repo.GetConfigByName("github_proxy_url"); err == nil && urlCfg != nil && urlCfg.Value != "" {
        proxyURL = strings.TrimSpace(urlCfg.Value)
        // 确保 URL 格式正确
        if !strings.HasPrefix(proxyURL, "http://") && !strings.HasPrefix(proxyURL, "https://") {
            proxyURL = "https://" + proxyURL
        }
        proxyURL = strings.TrimSuffix(proxyURL, "/")
    }
    
    return
}

// buildDownloadURL 构建下载地址
func (h *Handler) buildDownloadURL(version, arch string) string {
    enabled, proxyURL := h.getGithubProxyConfig()
    base := fmt.Sprintf("https://github.com/%s/releases/download/%s/gost-%s", githubRepo, version, arch)
    
    if enabled {
        return fmt.Sprintf("%s/%s", proxyURL, base)
    }
    return base
}

修改 nodeUpgrade 和 nodeBatchUpgrade 使用动态配置。

mutations.go

修改 getNodeInstallCmd 函数（约第 440-456 行）：

func (h *Handler) getNodeInstallCmd(w http.ResponseWriter, r *http.Request) {
    // ... 现有逻辑 ...
    
    enabled, proxyURL := h.getGithubProxyConfig()
    
    var cmd string
    if enabled {
        cmd = fmt.Sprintf(
            "curl -L %s/https://github.com/%s/releases/download/%s/install.sh -o ./install.sh && chmod +x ./install.sh && PROXY_ENABLED=true PROXY_URL=%s VERSION=%s ./install.sh -a %s -s %s",
            proxyURL, githubRepo, version, proxyURL, version, processServerAddress(panelAddr), secret,
        )
    } else {
        cmd = fmt.Sprintf(
            "curl -L https://github.com/%s/releases/download/%s/install.sh -o ./install.sh && chmod +x ./install.sh && PROXY_ENABLED=false VERSION=%s ./install.sh -a %s -s %s",
            githubRepo, version, version, processServerAddress(panelAddr), secret,
        )
    }
    
    response.WriteJSON(w, response.OK(cmd))
}

3. 前端修改

config.tsx

在 CONFIG_ITEMS 数组中添加配置项（约第 87-158 行之后）：

{
  key: "github_proxy_enabled",
  label: "开启 GitHub 加速",
  description: "用于节点更新和安装脚本下载，解决部分地区 GitHub 访问受限问题",
  type: "switch",
},
{
  key: "github_proxy_url",
  label: "加速地址",
  placeholder: "https://gcode.hostcentral.cc",
  description: "GitHub 下载加速代理地址，开启加速后生效",
  type: "input",
  dependsOn: "github_proxy_enabled",
  dependsValue: "true",
},

在 getInitialConfigs 函数的 configKeys 数组中添加缓存键：

"github_proxy_enabled",
"github_proxy_url",

4. 安装脚本修改

install.sh

在脚本开头添加配置变量和环境变量读取：

# 镜像加速配置（可由面板传入）
PROXY_ENABLED="${PROXY_ENABLED:-}"
PROXY_URL="${PROXY_URL:-}"

修改 maybe_proxy_url 函数：

# 镜像加速
maybe_proxy_url() {
  local url="$1"
  
  # 如果明确关闭加速
  if [[ "$PROXY_ENABLED" == "false" ]]; then
    echo "$url"
    return
  fi
  
  # 默认开启加速
  local proxy="${PROXY_URL:-gcode.hostcentral.cc}"
  
  # 处理 URL 格式
  if [[ "$proxy" == https://* || "$proxy" == http://* ]]; then
    proxy="${proxy%/}"  # 移除末尾斜杠
  else
    proxy="https://${proxy}"
  fi
  
  echo "${proxy}/${url}"
}

在 install_flux_agent 函数开头添加交互式询问：

install_flux_agent() {
  echo "🚀 开始安装 flux_agent..."
  
  # 询问加速配置（如果未由面板传入）
  if [[ -z "$PROXY_ENABLED" ]]; then
    echo ""
    read -p "是否开启 GitHub 加速? (Y/n): " proxy_choice
    case "$proxy_choice" in
      n|N) PROXY_ENABLED="false" ;;
      *)   
        PROXY_ENABLED="true"
        read -p "加速地址 (默认 gcode.hostcentral.cc): " input_url
        PROXY_URL="${input_url:-gcode.hostcentral.cc}"
        ;;
    esac
  fi
  
  # ... 现有安装逻辑 ...
}

panel_install.sh

类似修改，在 install_panel 函数开头添加询问逻辑。

5. 配置缓存

site.ts

在配置缓存键列表中添加新键（如果需要前端缓存加速配置）。

默认行为

• github_proxy_enabled: 默认 "true"（开启加速）
• github_proxy_url: 默认 "https://gcode.hostcentral.cc"

测试要点

1. 后端 API 测试：

   • 未配置时使用默认值
   • 配置后正确读取并应用
   • 关闭加速后直连 GitHub

2. 前端 UI 测试：

   • Switch 开关正确切换
   • 关闭加速时隐藏地址输入框
   • 保存配置后正确持久化

3. 安装脚本测试：

   • 交互式询问正常工作
   • 环境变量传入时跳过询问
   • 加速关闭时直连 GitHub

4. 集成测试：

   • 面板生成安装命令正确包含加速配置
   • 节点升级下载使用配置的加速地址

风险与缓解

风险	缓解措施
用户输入无效加速地址	后端验证 URL 格式，前端添加格式提示
旧版本安装脚本不兼容	保持 maybe_proxy_url 函数签名不变，仅修改内部逻辑
配置缺失时行为不一致	在 getGithubProxyConfig 中提供合理的默认值

任务清单

• 后端：upgrade.go 修改
• 后端：mutations.go 修改
• 前端：config.tsx 添加配置项
• 脚本：install.sh 修改
• 脚本：panel_install.sh 修改
• 测试：验证功能正常