给桌面客户端做下载加速：从「桶直接公开」到「边缘优先、源站兜底」的三代演进

<a href="https://silo-api.apikv.com/scorpius/releases/1.0.1/Scorpius_1.0.1_macos_arm64.dmg">
  立即下载
</a>

浏览器 ──POST /v1/update/download?platform=darwin-aarch64──▶ 授权 API
        ◀──{url: "https://…/dl/<token>", expiresIn: 60, singleUse: true}

浏览器 ──GET /dl/<token>────────────────────────────────▶ 授权 API
        ◀──302 Location: https://silo-api…/x.dmg?X-Amz-Signature=…&X-Amz-Expires=20

浏览器 ──GET（带签名）──────────────────────────────────▶ 私有桶
        ◀──文件字节

const (
	dlTokenTTL  = 60 * time.Second
	redeemTTL   = 20 * time.Second
	dlTokenSize = 24 // 字节熵 → 32 个 base64url 字符
)

type dlToken struct {
	key     string   // 桶里的对象键
	exp     time.Time
	ip      string
	used    bool
	created time.Time
}

func (s *Server) issueDownloadToken(key, ip string) string {
	raw := make([]byte, dlTokenSize)
	if _, err := rand.Read(raw); err != nil {
		panic(err) // crypto/rand 失败不是请求级故障
	}
	tok := base64.RawURLEncoding.EncodeToString(raw)
	now := s.now()
	s.dlMu.Lock()
	defer s.dlMu.Unlock()
	if s.dlTokens == nil {
		s.dlTokens = map[string]*dlToken{}
	}
	// 顺手 GC：过期条目删掉，map 不会无限涨
	for k, t := range s.dlTokens {
		if now.After(t.exp) {
			delete(s.dlTokens, k)
		}
	}
	s.dlTokens[tok] = &dlToken{key: key, exp: now.Add(dlTokenTTL), ip: ip, created: now}
	return tok
}

func (s *Server) redeemDownloadToken(tok string) (key string, ok bool) {
	s.dlMu.Lock()
	defer s.dlMu.Unlock()
	t, found := s.dlTokens[tok]
	if !found || t.used || s.now().After(t.exp) {
		return "", false
	}
	t.used = true
	return t.key, true
}

// 签发：严。滥用值得在这里被挡住。
srv.download = ratelimit.New(ratelimit.Config{PerMinute: 6, Burst: 3, MaxFails: 0, BreakFails: 0})
// 兑换：宽。滥用不值得在这里被挡住——拒绝发生在用户已经开始的跳转途中。
srv.downloadRedeem = ratelimit.New(ratelimit.Config{PerMinute: 30, Burst: 15, MaxFails: 0, BreakFails: 0})
// 全局：所有 IP 共享一个桶，兜住出站流量上限。
srv.downloadGlobal = ratelimit.New(ratelimit.Config{PerMinute: cfg.DownloadsPerMinute, Burst: cfg.DownloadsPerMinute})

{ "cdn": { "darwin-aarch64": "releases/1.0.1/Scorpius_1.0.1_macos_arm64.dmg" } }

// 兑换令牌时选源
key, ok := s.redeemDownloadToken(r.PathValue("token"))
if !ok {
	// 未知 / 过期 / 已用过 —— 三者表现一致，不给攻击者探测器
	s.dlFail(w, r, dlProblem{Status: http.StatusGone, Code: "link_expired", ...})
	return
}

// 边缘优先，桶兜底。判断依据是「问边缘」，不是「读清单」。
if link, served := s.cdnLink(r.Context(), key); served {
	w.Header().Set("Cache-Control", "no-store")
	http.Redirect(w, r, link, http.StatusFound)
	return
}

// 边缘没有这个文件 / 边缘当前不可达 → 预签名桶链接
link, err := s.presign(r.Context(), key, redeemTTL)
if err != nil {
	s.dlFail(w, r, dlProblem{Status: http.StatusServiceUnavailable, ...})
	return
}
w.Header().Set("Cache-Control", "no-store")
http.Redirect(w, r, link, http.StatusFound)

const cdnPathPrefix = "/dl"

func (s *Server) cdnLink(ctx context.Context, key string) (string, bool) {
	base := strings.TrimRight(s.cfg.CDNBaseURL, "/")
	if base == "" || key == "" {
		return "", false
	}
	// 边缘上的路径与桶里的对象键同构：releases/1.0.1/x.dmg
	// → <base>/dl/releases/1.0.1/x.dmg
	url := base + cdnPathPrefix + "/" + strings.TrimLeft(key, "/")
	if !s.cdnReachable(ctx, key, url) {
		return "", false
	}
	return url, true
}

const (
	cdnProbeTTL     = 30 * time.Second
	cdnProbeTimeout = 3 * time.Second
)

func (s *Server) cdnReachable(ctx context.Context, key, url string) bool {
	now := s.now()
	if v, ok := s.cdn.verdict(key, now); ok {
		return v.ok
	}

	probeCtx, cancel := context.WithTimeout(ctx, cdnProbeTimeout)
	defer cancel()
	req, err := http.NewRequestWithContext(probeCtx, http.MethodHead, url, nil)
	if err != nil {
		s.cdn.put(key, cdnVerdict{ok: false, at: now, err: err.Error()})
		return false
	}
	resp, err := s.cdnClient().Do(req)
	if err != nil {
		s.log.Warn("cdn probe failed", "key", key, "err", err)
		s.cdn.put(key, cdnVerdict{ok: false, at: now, err: err.Error()})
		return false
	}
	defer resp.Body.Close()

	ok := resp.StatusCode >= 200 && resp.StatusCode < 300
	s.cdn.put(key, cdnVerdict{ok: ok, at: now})
	return ok
}

type Config struct {
	// CDNBaseURL：承载安装包的边缘基址，如 https://scorpius-pages.apikv.com。
	// 留空表示「没有 CDN」，所有下载都走对象存储。
	CDNBaseURL string
	// …
}

// server/cmd/licensed/main.go
CDNBaseURL: os.Getenv("CDN_BASE_URL"),

api:
  env:
    # 承载安装包的 CDN 基址。服务端会先问边缘有没有这个文件，有就从边缘跳，
    # 没有就回落到对象存储的预签名链接（Linux AppImage 超过 CDN 单文件上限，
    # 一直走对象存储）。留空则全部走对象存储。
    CDN_BASE_URL: https://scorpius-pages.apikv.com

// Pages 的单文件上限与站点总容量。写在这里而不是散落在别处，因为它们是
// 平台的硬限制，改错了会直接导致部署被拒。
const PAGES_MAX_FILE_BYTES = 25 * 1024 * 1024;

// 会被误当成安装包的文件。
const NOT_AN_INSTALLER = (name) =>
  name.startsWith(".") ||
  name.endsWith(".sig") ||
  name.endsWith(".app.tar.gz") ||
  name.endsWith("_windows_x64.exe") ||
  name.endsWith("_windows_arm64.exe");

function compareVersions(a, b) {
  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
    const d = (pa[i] || 0) - (pb[i] || 0);
    if (d !== 0) return d;
  }
  return 0;
}

if (st.size > MAX_FILE_BYTES) {
  // 超过 Pages 单文件上限。留给对象存储，由服务端兜底。
  skipped.push({ version, file: f.name, bytes: st.size });
  continue;
}

EO_CDN_VERSIONS ?= 2
pages-deploy-eo:
	cd web && pnpm install --frozen-lockfile && pnpm build
	node scripts/cdn-release-assets.mjs --release-dir release --out web/dist/dl \
	  --versions $(EO_CDN_VERSIONS) --manifest web/dist/dl/manifest.json
	cd web && PAGES_SOURCE=skills edgeone makers deploy dist -n $(EO_PROJECT) -e production

{
  "caches": [{ "source": "/dl/releases/*", "cacheTtl": 604800 }],
  "headers": [
    {
      "source": "/dl/releases/*",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=604800, immutable" },
        { "key": "Pages-Cache-Control", "value": "s-maxage=604800" }
      ]
    }
  ]
}

func TestDownloadFallsBackWhenTheCDNIsDown(t *testing.T) {
	edge := cdnEdge(t, map[string]bool{
		"/dl/releases/0.3.0/Scorpius_0.3.0_macos_arm64.dmg": true,
	})
	url := edge.URL
	edge.Close() // 边缘在下载到达之前就没了

	e := withCOS(t, testManifest, nil)
	e.srv.cfg.CDNBaseURL = url

	r := e.do("POST", "/v1/update/download?platform=darwin-aarch64", nil, nil)
	tok := strings.TrimPrefix(r.Body["url"].(string), "https://api.example.com")
	red := e.do("GET", tok, nil, nil)
	loc := red.Header.Get("Location")
	if !strings.Contains(loc, "q-signature=") {
		t.Fatalf("a dead edge must not be the redirect target: %s", loc)
	}
}

// cdnPathPrefix is where release files live on the CDN. It must agree with
// the directory scripts/cdn-release-assets.mjs writes to and the path
// edgeone.json caches. A mismatch here fails silently: the probe finds
// nothing and every download falls back to the bucket, which looks like
// "the CDN never worked" rather than like a bug.
const cdnPathPrefix = "/dl"

// TestCDNPathPrefixAgreesWithTheSiteDeployment
func TestCDNPathPrefixAgreesWithTheSiteDeployment(t *testing.T) {
	root := filepath.Join("..", "..", "..")
	mk, err := os.ReadFile(filepath.Join(root, "Makefile"))
	if err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(string(mk), "--out web/dist"+cdnPathPrefix) {
		t.Fatalf("Makefile does not publish the release assets to web/dist%s; the server's cdnPathPrefix=%q no longer matches",
			cdnPathPrefix, cdnPathPrefix)
	}
	cfg, err := os.ReadFile(filepath.Join(root, "web", "public", "edgeone.json"))
	if err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(string(cfg), cdnPathPrefix+"/releases/*") {
		t.Fatalf("web/public/edgeone.json does not cache %s/releases/*", cdnPathPrefix)
	}
}

--- FAIL: TestCDNPathPrefixAgreesWithTheSiteDeployment
    cdn_test.go:182: Makefile does not publish the release assets to web/dist/dl; the server's cdnPathPrefix="/dl" no longer matches