docs(spec): 官网部署改 Cloudflare Pages(架构变更说明)

节点 :443 被 VPN 占用 + CF 免费套餐改回源端口需 Enterprise → 官网改 CF Pages 托管 (纯静态/全程 HTTPS/CSP 生效/无 :443 冲突),已上线 pangolin.yanmeiai.com。 deploy-site.sh 用 wrangler,需 CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
refactor(ci): 官网部署改用 Cloudflare Pages(替代 rsync 到 pangolin1)
2026-07-06 10:08:20 +08:00 · 2026-07-06 09:59:58 +08:00 · 2026-07-06 00:37:48 +08:00
6 changed files with 92 additions and 32 deletions
@@ -53,7 +53,8 @@ jobs:
              /mnt/scripts/ci/deploy-site.sh \
              /mnt/scripts/ci/compile-backend.sh \
              /mnt/scripts/ci/release-server.sh \
-              /mnt/scripts/ci/deploy-server.sh
+              /mnt/scripts/ci/deploy-server.sh \
+              /mnt/scripts/ci/test.sh

  # ── Job 2: OpenAPI Sync Check ────────────────────────────────────────────
  openapi-check:
@@ -23,7 +23,11 @@ jobs:
            -e SITE_URL=https://pangolin.yanmeiai.com \
            node:20 bash scripts/ci/compile-site.sh

-      - name: Deploy → pangolin1
+      - name: Deploy → Cloudflare Pages
        env:
-          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
-        run: bash scripts/ci/deploy-site.sh
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          docker run --rm -v "$PWD:/w" -w /w \
+            -e CLOUDFLARE_API_TOKEN -e CLOUDFLARE_ACCOUNT_ID \
+            node:20 bash scripts/ci/deploy-site.sh
@@ -111,10 +111,12 @@ pangolin.yanmeiai.com）与多端产物。现状：仅 <code>ci.yml</code> 校
 </ol>
 </div>

-<h2>4. 官网部署</h2>
+<h2>4. 官网部署 —— Cloudflare Pages</h2>
+<div class="card" style="border-left:3px solid var(--warn)">
+<b>架构变更(2026-07-06 实施):</b>原计划 rsync 到 pangolin1 的 nginx。但节点 <code>:443</code> 被 sing-box(VPN 数据面)占用,而 CF 免费套餐 proxied 回源只能打 :80/:443、改回源端口需 Enterprise —— 同机同 IP 上官网 HTTPS 与 VPN 无法共存。<b>故官网改由 Cloudflare Pages 托管</b>:纯静态、全程 HTTPS、<code>_headers</code>/CSP 原生生效、不落 VPS,从根上无 :443 冲突,也不拖累 VPN 机器。<b>已上线</b> <code>https://pangolin.yanmeiai.com</code>。
+</div>
 <p>Astro <code>npm ci && npm run build</code>（<code>SITE_URL=https://pangolin.yanmeiai.com</code>）→ <code>dist/</code>
-rsync 到服务器 web 根 → nginx/Caddy 静态托管。<b>DNS</b>：CF 加记录
-<code>pangolin.yanmeiai.com</code> → 服务器（首次部署时做，记 baize）。</p>
+经 <code>npx wrangler pages deploy</code> 发布到 Pages 项目 <b>pangolin-site</b>(自定义域 <code>pangolin.yanmeiai.com</code>,CNAME → <code>pangolin-site.pages.dev</code>,proxied)。需 secret <code>CLOUDFLARE_API_TOKEN</code>（带 Account&gt;Pages&gt;Edit）+ <code>CLOUDFLARE_ACCOUNT_ID</code>；deploy 步骤在 <code>node:20</code> 容器内跑 wrangler。灾备:产物仍纯静态,可另 rsync 到镜像。</p>

 <h2>5. 下载链接闭环（30A）</h2>
 <p><code>web/website/src/config/site.ts</code> 增 <code>downloads:{ android, macos, windows }</code>，值为 Gitea release
@@ -43,7 +43,7 @@ pangolin 现有 CI 仅 `.gitea/workflows/ci.yml`(nas,只校验无部署)+ `web/w
 - `test.sh <server|client>` —— `go test` / `flutter test`
 - `notify.sh` —— 成功/失败 Telegram 通知(可选,复用节点监控 bot)
 - `compile-site.sh` / `compile-backend.sh` / `compile-android.sh` / `compile-macos.sh` / `compile-windows.sh`
- `deploy-site.sh` / `deploy-server.sh`(ssh pangolin1)
+- `deploy-site.sh`(wrangler → CF Pages)/ `deploy-server.sh`(ssh pangolin1,复用 lib-ssh)
 - `release-<x>.sh` —— 建 release + 挂产物

 > 每个 `compile-*` 内部封装该端已验证的构建命令(如 Android 走
@@ -74,11 +74,18 @@ pangolin 现有 CI 仅 `.gitea/workflows/ci.yml`(nas,只校验无部署)+ `web/w
 5. `install` 新二进制到 `/usr/local/bin`(旧的备份为 `.bak-<tag>`)
 6. `systemctl start pangolin-server` + `/healthz` 健康检查;agent 随连接自恢复

-### 4.4 官网部署(deploy-site.sh)
+### 4.4 官网部署(deploy-site.sh)—— Cloudflare Pages

-Astro `npm ci && npm run build`(`SITE_URL=https://pangolin.yanmeiai.com`)→ `dist/` rsync 到
-服务器 web 根 → 由 nginx/Caddy 静态托管 `pangolin.yanmeiai.com`。**DNS**:CF 加 A/CNAME
-`pangolin.yanmeiai.com` → 服务器(首次部署时做,记 baize)。
+> **架构变更(2026-07-06 实施):** 原计划 rsync 到 pangolin1 的 nginx。但节点 :443 被 sing-box
+> (VPN 数据面)占用,而 CF 免费套餐 proxied 回源只能打 :80/:443、改回源端口需 Enterprise ——
+> 无法在同机同 IP 上让官网 HTTPS 与 VPN 共存。**故官网改由 Cloudflare Pages 托管**:纯静态、
+> 全程 HTTPS、`_headers`/CSP 原生生效、不落 VPS,从根上无 :443 冲突,也不拖累 VPN 机器。
+
+Astro `npm ci && npm run build`(`SITE_URL=https://pangolin.yanmeiai.com`)→ `dist/` 经
+`npx wrangler pages deploy` 发布到 CF Pages 项目 **`pangolin-site`**(自定义域
+`pangolin.yanmeiai.com`,CNAME → `pangolin-site.pages.dev`,proxied)。
+需 secret:`CLOUDFLARE_API_TOKEN`(带 Account>Pages>Edit)+ `CLOUDFLARE_ACCOUNT_ID`(账户级)。
+deploy 步骤在 `node:20` 容器内跑 wrangler。**灾备**:构建产物仍是纯静态,可另 rsync 到任意镜像。

 ## 5. 下载链接闭环(30A)

@@ -1,32 +1,29 @@
 #!/usr/bin/env bash
-# deploy-site.sh — rsync the built Astro 官网 (web/website/dist/) to the
-# pangolin1 VPS web root (/var/www/pangolin-site). Deploy user is root — the
-# CI deploy key (secrets.DEPLOY_SSH_KEY) is authorized for root on the host.
-# Static files only; nginx/caddy serves them directly, no service restart
-# needed. Assumes it is invoked from the repo root, after compile-site.sh has
-# produced web/website/dist/.
+# deploy-site.sh — 部署构建好的 Astro 官网 (web/website/dist/) 到 Cloudflare Pages。
+#
+# 官网托管在 CF Pages(项目 pangolin-site,自定义域 pangolin.yanmeiai.com),纯静态、
+# 全程 HTTPS、CSP(_headers)自动生效,不落在 VPS 上 —— 故与节点 :443(sing-box)无冲突。
+#
+# 需环境变量:
+#   CLOUDFLARE_API_TOKEN   带 Account > Cloudflare Pages > Edit 权限的 CF token
+#   CLOUDFLARE_ACCOUNT_ID  CF 账户 ID
+# 由 compile-site.sh 先产出 web/website/dist/;从 repo 根调用。
 set -euo pipefail

-# shellcheck source=scripts/ci/lib-ssh.sh
-. scripts/ci/lib-ssh.sh
-
-# setup_ssh registers the EXIT cleanup trap itself (before writing the key),
-# so a mid-setup failure still cleans up — see lib-ssh.sh.
-setup_ssh
-
-# Guard against deploying a missing/empty build: `rsync --delete` against an
-# empty source would wipe the live site.
 if [ ! -d web/website/dist ]; then
-  echo "==> deploy-site: web/website/dist/ does not exist — refusing to deploy" >&2
+  echo "==> deploy-site: web/website/dist/ 不存在 — 拒绝部署" >&2
  exit 1
 fi
 if ! find web/website/dist -mindepth 1 -print -quit | grep -q .; then
-  echo "==> deploy-site: web/website/dist/ is empty — refusing to deploy" >&2
+  echo "==> deploy-site: web/website/dist/ 为空 — 拒绝部署" >&2
  exit 1
 fi

-DEPLOY_TARGET="root@${DEPLOY_HOST}:/var/www/pangolin-site/"
-echo "==> deploy-site: rsync web/website/dist/ -> ${DEPLOY_TARGET}"
-rsync -az --delete -e "${RSYNC_SSH}" web/website/dist/ "${DEPLOY_TARGET}"
+: "${CLOUDFLARE_API_TOKEN:?deploy-site: CLOUDFLARE_API_TOKEN 未设(需带 Pages:Edit)}"
+: "${CLOUDFLARE_ACCOUNT_ID:?deploy-site: CLOUDFLARE_ACCOUNT_ID 未设}"
+
+echo "==> deploy-site: wrangler pages deploy → project pangolin-site (branch main)"
+npx --yes wrangler@4 pages deploy web/website/dist \
+  --project-name=pangolin-site --branch=main --commit-dirty=true

 echo "==> deploy-site: done"
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# test.sh <server|client> — run the test suite for one side of the repo.
+# Invoked directly on the nas runner (see deploy-server.yml's "Test" step),
+# so this script itself owns the docker invocation — Go/Flutter are not on
+# the host.
+#
+# server: `go test ./...` inside golang:1.25, mirroring the go-server job's
+#   docker invocation in .gitea/workflows/ci.yml (mounts + gomod/gobuild
+#   caches), plus GOPROXY from _env.sh so it doesn't hit proxy.golang.org.
+# client: `flutter test` inside ghcr.io/cirruslabs/flutter:stable, mirroring
+#   the flutter-client job's docker invocation in .gitea/workflows/ci.yml
+#   (pub-cache volume, same test dirs); analyze/coverage stay in that job.
+#
+# Run from the repo root (relative paths below assume this).
+set -euo pipefail
+
+# shellcheck source=scripts/ci/_env.sh
+. scripts/ci/_env.sh
+
+TARGET="${1:-}"
+
+case "$TARGET" in
+  server)
+    mkdir -p "$HOME/.cache/pangolin-ci/gomod" "$HOME/.cache/pangolin-ci/gobuild"
+    echo "==> test: go test ./... (golang:1.25 容器)"
+    docker run --rm \
+      -v "$PWD/server:/app" -w /app \
+      -v "$HOME/.cache/pangolin-ci/gomod:/go/pkg/mod" \
+      -v "$HOME/.cache/pangolin-ci/gobuild:/root/.cache/go-build" \
+      -e GOPROXY="$GOPROXY" \
+      golang:1.25 \
+      go test ./...
+    ;;
+  client)
+    mkdir -p "$HOME/.cache/pangolin-ci/pubcache"
+    echo "==> test: flutter test (ghcr.io/cirruslabs/flutter:stable 容器)"
+    docker run --rm \
+      -v "$PWD/client:/app" -w /app \
+      -v "$HOME/.cache/pangolin-ci/pubcache:/root/.pub-cache" \
+      ghcr.io/cirruslabs/flutter:stable \
+      bash -c "flutter pub get && flutter test test/unit test/widget test/contract"
+    ;;
+  *)
+    echo "usage: scripts/ci/test.sh <server|client>" >&2
+    exit 1
+    ;;
+esac
+
+echo "==> test: ${TARGET} 通过"