发布方案（Cloudflare Pages CI 优先）

本项目对外发布分三层，可独立启用：

层内容承载状态

A. 本体 schema 实体/关系图（可交互） Ontology-Playground fork 的 Pages 流程已就绪，随时可推

B. 项目文档站 本 docs/ 目录（设计/架构/名词解释…） 并入 C 层站点 /docs/ 路径（MkDocs Material，mkdocs.yml） 已上线：https://xgb-wiki-site.pages.dev/docs/ ，随研报站一起构建发布；GitHub Pages 独立通道方案见 §B（备用）

C. 研报静态站 题材/产业链/每日题材/近90天研报（含正文） Cloudflare Pages（大陆直连✓），GitHub Actions 自动构建部署 已上线，push master 即发布

⚠️ C 层隐私提示：研报正文来自付费产品，公网发布前务必确认合规；对外分享版建议 --no-content 构建（仅标题/摘要/实体标注，不含全文）。docs 发布前已清理内网 IP 等敏感信息（2026-09-05 首次上线时核查）。

C. 研报静态站（Cloudflare Pages，CI 自动部署）

https://xgb-wiki-site.pages.dev/（项目 xgb-wiki-site；2026-08-30 本网络实测生产域名直连 200，2-4s；带哈希前缀的部署预览子域不通，日常用生产域名即可）

C1. GitHub Actions 自动构建部署（默认通道）⭐

.github/workflows/deploy-site.yml：push master（触及 data/、src/、scripts/、static/ 等）或手动触发 → 跑全功能测试 → 构建静态站 → wrangler pages deploy。仓库不再提交 data/output/site/ 产物，由 CI/本地构建生成。

首次使用需在仓库 Settings → Secrets and variables → Actions 配置两个 secret：

Secret	说明
`CLOUDFLARE_API_TOKEN`	Cloudflare 仪表盘 → My Profile → API Tokens → 创建（模板可空白自建，权限需含 Account → Cloudflare Pages → Edit）
`CLOUDFLARE_ACCOUNT_ID`	仪表盘任意域名 Overview 右侧栏的 Account ID

C2. 本地手动发布（立即生效，不依赖 CI）

python scripts/deploy_site.py                # 构建 + 发布（含正文）
python scripts/deploy_site.py --no-content   # 对外分享版（不含付费正文）

需本机 wrangler login（或 CLOUDFLARE_API_TOKEN 环境变量）。

已下线的通道

GitHub Pages 通道（seuzxh.github.io/xgb-wiki-site）：2026-08-30 移除——CI 统一走 Cloudflare，避免双通道维护
Cloudflare Workers 通道（seuzxh.workers.dev）：大陆不可达，已删除
Cytoscape 已本地 vendor（static/vendor/ → site/assets/），不依赖 jsdelivr（大陆不稳）

A. 本体 schema → Ontology-Playground Pages

fork 地址：https://github.com/seuzxh/Ontology-Playground ，Pages 已启用（https://seuzxh.github.io/Ontology-Playground/ ）。

# 1. 本仓库：导出 catalogue 条目
python scripts/export_ontology.py        # → data/output/xgb-a-chain/{xgb-a-chain.rdf, metadata.json}

# 2. 复制到 fork 仓库（社区目录，首次需建目录）
cp data/output/xgb-a-chain/*  <Playground仓库>/catalogue/community/seuzxh/xgb-a-chain/

# 3. fork 仓库内：校验 + 重建 catalogue + 推送
npm run validate
npm run catalogue:build
git add catalogue && git commit -m "catalogue: xgb-a-chain" && git push

推送后 Pages 自动更新，线上入口：https://seuzxh.github.io/Ontology-Playground/#/catalogue/community/seuzxh/xgb-a-chain。

注意事项：

Playground 只渲染 schema 层（8 实体/11 关系的类型图），实例数据不导出、不上传
metadata.json 字段受 additionalProperties: false 约束（name/description/category/icon/tags/author），多字段会被 validate 拒绝
style-validator 有命名 lint；导出文件已按 catalogue/official/finance/finance.rdf 实测格式对齐
本地镜像与线上 fork 并存：本地 /Ontology-Playground/ 镜像内嵌在 Flask（无外网也可用，条目放在 official/ 下）；重镜像后记得重跑 scripts/localize_playground.py 汉化

B. 项目文档站

当前通道（已上线）：文档随研报站一起发布——build_static_site.py 构建末尾执行 mkdocs build --site-dir site/docs/，经 C 层同一 Cloudflare Pages 项目部署，线上入口 /docs/，主导航有"项目文档"入口。本地预览：python -m mkdocs serve。docs/ 或 mkdocs.yml 变更已加入 CI 触发路径。

以下为 GitHub Pages 独立通道方案（备用，未启用）：

docs/ 已按静态站点习惯组织（英文文件名做 URL slug、中文内容、相对链接、README 导航、mermaid 图），Jekyll / MkDocs / docsify 均可直接渲染，无需改动文档本身。

方案 B1：MkDocs Material（推荐）

步骤 1 — 仓库根新建 mkdocs.yml：

site_name: xgb_wiki 题材本体
site_description: 选股宝脱水研报的题材本体 Wiki——设计、架构与数据字典
repo_url: https://github.com/<你的用户名>/xgb_wiki        # 按实际仓库改
repo_name: <你的用户名>/xgb_wiki
theme:
  name: material
  language: zh
  palette:
    - scheme: default
      primary: indigo
      toggle: { icon: material/weather-night, name: 切换暗色 }
    - scheme: slate
      toggle: { icon: material/weather-sunny, name: 切换亮色 }
  features: [navigation.tabs, content.code.copy]
markdown_extensions:
  - tables
  - admonition
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
nav:
  - 首页: README.md
  - 设计方案: design.md
  - 整体架构: architecture.md
  - 数据模型: data-model.md
  - 名词解释: glossary.md
  - 运行手册: operations.md
  - Pages 发布: publishing.md

步骤 2 — .github/workflows/docs.yml：

name: docs
on:
  push: { branches: [master] }
permissions: { contents: write, pages: write, id-token: write }
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.13" }
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

步骤 3 — 仓库 Settings → Pages → Source 选 Deploy from a branch → 分支选 gh-pages（首次构建后出现）。之后每次 push master 自动重建。

方案 B2：Jekyll 零配置（最快但最简陋）

Settings → Pages → Source 选 main（或 master）+ /docs 目录即可。默认主题、无 mermaid 渲染、无搜索。适合先上线占位，后续再切 B1。

方案 B3：docsify（无构建）

根目录放一个 index.html（docsify CDN 加载 docs/README.md 做侧边栏），Pages 指向根。改动零构建，但 SEO 与渲染质量弱于 MkDocs。

发布前检查清单

[ ] 仓库可见性：私有仓库的 Pages 需付费计划。当前仓库含付费产品正文与 SQLite 实例数据，应保持私有——建议文档站放独立公开仓库（仅拷贝 docs/ + mkdocs 配置），或确认计划支持后再启用本仓库 Pages
[ ] 确认 .gitignore 覆盖 .env、*.db-shm、*.db-wal；Pages 产物中不含数据库与正文
[ ] mkdocs.yml 的 repo_url、workflow 触发分支名（master/main）按实际修改
[ ] 文档内本地交叉引用（design.md 引凭据项目 2_xuangubao、operations.md 引 .env 来源）在公网站点上无对应物，属预期，无需修复
[ ] 首次发布后人工过一遍：mermaid 是否渲染、表格是否错位、中文是否乱码（统一 UTF-8）

本地预览

pip install mkdocs-material
mkdocs serve            # → http://127.0.0.1:8000

层	内容	承载	状态
A. 本体 schema	实体/关系图（可交互）	Ontology-Playground fork 的 Pages	流程已就绪，随时可推
B. 项目文档站	本 `docs/` 目录（设计/架构/名词解释…）	并入 C 层站点 `/docs/` 路径（MkDocs Material，`mkdocs.yml`）	已上线：https://xgb-wiki-site.pages.dev/docs/ ，随研报站一起构建发布；GitHub Pages 独立通道方案见 §B（备用）
C. 研报静态站	题材/产业链/每日题材/近90天研报（含正文）	Cloudflare Pages（大陆直连✓），GitHub Actions 自动构建部署	已上线，push master 即发布