EdgeOne 部署规划设计

版本 0.2（实施记录）· 2026-09-25 · 状态：阶段1已实施——部署成功，大陆验收不达标（平台政策原因），待用户决策 目标：为研报静态站增加腾讯云 EdgeOne Pages 发布通道，形成 pages.dev（海外/备份）+ EdgeOne（大陆主力）双通道，解决 GitHub Pages 已移除、pages.dev 大陆可达性不稳的问题。上位文档：publishing.md（发布矩阵总览）。

0. 阶段1 实施记录（2026-09-25）

部署事实： - 命令：PAGES_SOURCE=skills edgeone makers deploy data/output/site -n xgb-wiki-site --json（注意 edgeone pages 已废弃；--area 默认 global=大陆+海外，无需指定） - 项目：xgb-wiki-site，Project ID makers-kvbfvyfny1yr，部署 ID dppv26k6phri（Production 环境），控制台 https://console.cloud.tencent.com/edgeone/pages/project/makers-kvbfvyfny1yr/deployment/dppv26k6phri - 内容：--no-content 稳妥版（1693 文件/46MB），线上抽查确认研报页带"正文未包含"标记 ✓ - 访问 URL：https://xgb-wiki-site-qgkowg18.edgeone.cool?eo_token=...&eo_time=...（带 token 预览链接）

关键发现（推翻本规划前提）： 1. ~~*.edgeone.app 免备案公开默认域~~ —— 实测 xgb-wiki-site.edgeone.app 返回 404（泛解析 CNAME 到 pages.openedge.sched.ovscdns.com，但无项目绑定该主机名）；Makers CLI 部署只产出 token 门控的 .edgeone.cool 预览链接。 2. 官方域名管理文档明确：默认域名在中国大陆只能通过系统生成的预览链接访问，链接 3 小时有效（过期 401），控制台"项目概览→预览"按钮可续；非大陆网络可直接访问；大陆稳定访问必须绑定已 ICP 备案的自定义域名（https://pages.edgeone.ai/zh/document/domain-overview）。 3. 本机环境注意：Clash 类代理 fake-IP 模式劫持全部 DNS（含指定公共 DNS），实测真实 IP 须走 DoH（doh.pub）+ curl --resolve。

阶段1验收结论：① 部署成功、内容一致 ✓；② 大陆免 token 直连 ✗（平台政策，非网络问题）——按 §4 终止性条款，方案在默认域形态下不达标。出路二选一：(a) 用户有已备案域名 → 绑定自定义域名走大陆节点；(b) 无备案域名 → EdgeOne 通道仅作海外/预览备用（pages.dev 地位对调），或终止本通道。

1. 背景与动机

现状	问题
线上唯一通道 = Cloudflare Pages（`xgb-wiki-site.pages.dev`），push master 由 CI 自动发布	pages.dev 生产域名当前大陆直连可达，但属非承诺的灰色可达（Cloudflare 无国内节点，随时可能劣化）
GitHub Pages / Workers 通道已先后移除	workers.dev 被 DNS 污染/SNI 阻断实证；github.io 大陆时通时断
本地手动通道 `scripts/deploy/deploy_site.py` 仅 wrangler 单目标	无 --target 参数，扩展点已具备

为什么是 EdgeOne Pages：腾讯云静态托管（对标 Cloudflare Pages），免费档、免服务器、默认域 *.edgeone.app 免 ICP 备案、腾讯国内边缘节点在大陆访问质量上是目前所有选项中最稳的一档。

不选 EdgeOne CDN 站点接入（另一条产品线）：那需要自建公网源站；本项目动态部分依赖内网 MySQL，不可暴露，静态托管才是正解。

2. 方案总览

flowchart LR
    subgraph 构建（一次）
        B["python scripts/build/build_static_site.py<br/>--days 90 [--no-content]<br/>→ data/output/site/（约13MB/1600文件）"]
    end
    subgraph 发布通道
        CF["Cloudflare Pages<br/>xgb-wiki-site.pages.dev<br/>（CI 自动 + 本地 wrangler）"]
        EO["EdgeOne Pages<br/>xgb-wiki-site.edgeone.app<br/>（本设计新增）"]
    end
    B -->|"npx wrangler pages deploy（现状）"| CF
    B -->|"edgeone pages deploy（新增）"| EO

原则：一次构建、多通道分发——两通道吃同一份 data/output/site/ 产物，保证内容一致，禁止各建各的构建。

3. 关键设计决策

3.1 接入方式：本地 CLI 起步，CI token 演进

先辨析腾讯的三个易混工具（截至 2026-09）：

工具	面向	能力	与本项目的关系
edgeone CLI（`npm i -g edgeone`）	EdgeOne Pages 静态托管	`edgeone pages deploy <目录>` 上传构建产物，产出 `*.edgeone.app`	✅ 部署主路径（本节方案 A/B 的载体）
EdgeOne Pages MCP（官方 MCP Server）	EdgeOne Pages 静态托管	把 HTML 文件/文件夹发布为网站，供 AI agent 调用（Cursor/Claude/ZCode 等可配）	✅ 可选替代：配到本机 MCP 后由 agent 端到端"构建→部署"，效果等价 CLI
EdgeOne Skill（CodeBuddy/ClawHub 等 AI 插件）	EdgeOne CDN 站点运维	域名接入向导、缓存刷新/预热、证书管理、安全防护（IP 拉黑/模板审计）、流量周报/日志分析	⚠️ 不做 Pages 部署（其"站点接入"是 CDN 接入、需自有源站）。互补价值在阶段4+：自定义域名接入与证书、部署后缓存刷新、流量简报当作大陆访问质量监控

（EdgeOne Skill 与 Pages MCP 授权均为浏览器 OAuth，不向 AI 暴露 SecretId/SecretKey；变更类操作执行前需确认。）

方案	说明	结论
A. 本地 CLI 上传（阶段1采用）	`npm i -g edgeone` → `edgeone login`（浏览器授权）→ `edgeone pages deploy data/output/site --project-name xgb-wiki-site`	✅ MVP 最快路径，与现有 wrangler 手动通道同构，内容版本完全可控
B. CI + API Token（阶段2）	GitHub Actions 中用 `EDGEONE_API_TOKEN`（Secrets）调 CLI/API 上传，push master 双通道自动发布	✅ 目标态；前提：验证 CLI 支持 token 环境变量鉴权（登录态不进 CI），实现时核对官方文档
C. Git 仓库集成	EdgeOne 控制台绑定 GitHub 私有仓库自动构建	❌ 不采用：私有库需授权给腾讯侧；构建环境要装 Python 3.13 + 拉取 85MB db，慢且重；内容策略（--no-content）失控

3.2 域名策略

阶段1 用默认域：项目命名 xgb-wiki-site → xgb-wiki-site.edgeone.app，免备案直接用
注意区分：*.edgeone.app（正式默认域，公开可访问）≠ *.edgeone.cool（预览临时域，带 ?eo_token= 全站鉴权，仅预览用）
阶段3（可选）自定义域名：绑定自有域名需 CNAME 到 EdgeOne；启用中国大陆节点必须已有 ICP 备案。无备案域名则止步默认域（edgeone.app 本身腾讯已备案，大陆可直接访问）

3.3 内容策略（⚠️ 需用户拍板的决策点）

pages.dev 通道当前发布全量版（含付费研报正文，用户此前已授权该模式发布到海外）。EdgeOne 是国内云，对版权/合规内容的平台审查显著严于 Cloudflare，全量付费正文放国内 CDN 存在被处置风险。

选项	内容	建议
稳妥版（建议默认）	EdgeOne 通道用 `--no-content`（标题/题材/个股/观点结构在，正文摘要去掉或截断）	大陆主力通道保安全，看正文走 pages.dev
全量版	与 pages.dev 完全一致	用户明确授权后可切换，一行参数

实现上无需二选一死：deploy_site.py 加 --content/--no-content 作用到各通道的映射参数即可。

3.4 deploy_site.py 改造设计

python scripts/deploy/deploy_site.py [--days 90] [--no-content] [--target auto|cf|edgeone|all]
                                   auto = 交互式选择；all = 双通道

构建一次 → 按 target 依次分发；单通道失败不阻塞其他通道（报告失败项、退出码非 0，支持 --target edgeone 单独重试）
edgeone 分发 = edgeone pages deploy data/output/site --project-name xgb-wiki-site（命令语法以实测为准，CLI 升级可能调整）
前置检查：edgeone --version 不存在时提示 npm i -g edgeone；登录态失效时提示 edgeone login（wrangler OAuth 多实例并发 CSRF 的教训同样适用：单实例操作，避免并发部署）

3.5 CI 集成设计（阶段2）

.github/workflows/deploy-site.yml 追加步骤（在现有 Cloudflare 步骤之后）：

- name: 发布到 EdgeOne Pages
  run: npm install -g edgeone && edgeone pages deploy data/output/site --project-name xgb-wiki-site
  env:
    EDGEONE_API_TOKEN: ${{ secrets.EDGEONE_API_TOKEN }}   # 机制待实测确认

双通道串行部署、互不阻塞（continue-on-error + 最后汇总），避免一个平台故障导致整体 CI 红。

4. 实施计划与验收

阶段	内容	验收标准
0 准备	edgeone.ai 注册（腾讯云账号）/ `npm i -g edgeone` / `edgeone login`	CLI 登录态就绪
1 MVP	本地：build → CLI 部署 → 拿到 `xgb-wiki-site.edgeone.app`；大陆直连实测（curl/浏览器无代理）	① 域名 200 可访问；② 大陆直连可达（核心验收，不可达则本方案终止，回退评估自定义域名或其他通道）；③ 内容抽查与构建产物一致
2 脚本化	deploy_site.py 加 --target；docs 同步；跑通 `--target all`	双通道一键发布可重复执行
3 CI	验证 token 鉴权 → workflow 加 EdgeOne 步骤 + Secrets	push master 双通道自动更新，CI 绿
4 可选	自定义域名（需备案域名）、Pages Functions 动态能力（如未来 NL 查询要真后端）、访问控制/WAF 规则	按需

5. 风险与对策

风险	对策
`edgeone.app` 默认域大陆可达性不达预期	阶段1 设为终止性验收点；不达标不投入后续阶段
免费额度（流量/构建次数）政策变动或超限	个人站量级（13MB/次、日常访问）远低于免费档；部署频率受数据同步节奏约束；超限再评估付费
付费正文在国内平台的合规处置风险	默认走 --no-content 稳妥版（§3.3），全量版需用户每次明确授权
CLI 浏览器登录态过期/多实例冲突	部署脚本前置检查登录态；单实例操作；CI 阶段切换 token 鉴权
~1600 文件目录上传耗时/失败重传	CLI 目录上传实测；失败重跑（Pages 增量上传按文件哈希，重传成本低）
三方 CLI 命令变更	deploy_site.py 中 EdgeOne 命令集中一处，便于跟进

6. 与现有发布矩阵的关系

实施完成后矩阵为：

通道	域名	定位	触发
Cloudflare Pages	xgb-wiki-site.pages.dev	海外访问 / 全量版 / 备份	CI（push master）+ 本地
EdgeOne Pages	xgb-wiki-site.edgeone.app	大陆主力（内容策略见 §3.3）	本地（阶段2 后 CI）
~~GitHub Pages~~	~~seuzxh.github.io/xgb-wiki-site~~	已移除	—