跳到主要内容

Prof. Net 官网部署说明（profine.darra.xyz）

链路：GitHub 仓库 → GitHub Actions 编译 Docusaurus → 推送 Cloudflare Pages。 本文档面向运维/首次建站，含 CF Pages 创建、GitHub secrets、自定义域名绑定与验证步骤。

一、流水线总览​

GitHub 仓库 Darra_Profinet_Slave (master)
  └─ push（docs/** 或 workflow 文件变更，见 .github/workflows/deploy-docs.yml paths 过滤）
      → GitHub Actions: deploy-docs
          ├─ checkout → setup-node(20) → npm ci → npm run build（工作目录 docs/）
          └─ cloudflare/pages-action
              → CF Pages 项目 profine-darra-xyz（上传目录 docs/build，分支 master=生产分支）
                  → 自定义域名 profine.darra.xyz
  • 触发条件：master 分支 docs/** 或 workflow 本身变更；也可在 Actions 页 workflow_dispatch 手动触发。
  • 站点纯静态，运行时无环境变量/密钥；密钥只存在 GitHub secrets，不落仓库文件。

二、与 ETH 推送方式对照​

仓方式CF Pages 项目说明
ETH 文档仓（Darra_EtherCAT_Master/云端/ethercat-doc）CF Pages GitHub source 直连（CF 侧构建，构建命令 npm run build、输出 build/，域名 ethercat.darra.xyz）darra-ethercat-doc仓内无 GH Actions，连接由 CF 项目配置管理
CAD 文档仓（Darra_CAD/云端/cad-doc）wrangler pages deploy build --project-name=darra-cad（CLI，需 CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID）darra-cad本地/脚本触发
本仓（Prof. Net）GitHub Actions 编译 + cloudflare/pages-action 推送profine-darra-xyz编译在 GitHub 侧执行，过程可观测；只在 docs 变更时触发

三条路径互不冲突。本仓选 GH Actions 的原因是编译过程在 GitHub 侧可控（node 版本、npm ci 锁版本），且首次建站只需在 CF 建好空项目 + GitHub 配两个 secrets。

三、Cloudflare Pages 项目创建步骤​

  1. 登录 dash.cloudflare.com → 左侧 Workers & Pages → Create → Pages。
  2. 创建方式选 Direct Upload（最简）：因为部署走 pages-action 直传产物，不需要 CF 连 GitHub。项目名填： 
    profine-darra-xyz
    若选了 Connect to Git 也可（构建配置：根目录 docs、构建命令 npm run build、输出目录 build，仅作 CF 直连兜底，与 Actions 推送互不影响）。
  3. Settings → Builds & deployments：生产分支（Production branch）= master（与 workflow 的 branch: master 参数对应）。
  4. 环境变量：不需要（站点纯静态）。
  5. 注意事项：pages-action 要求项目已存在，所以先建项目、后推代码。

四、GitHub secrets 配置​

仓库（GitHub 上的 Darra_Profinet_Slave）→ Settings → Secrets and variables → Actions → New repository secret，加两个：

Secret 名取值
CF_API_TOKENCloudflare 面板 → 右上 My Profile → API Tokens → Create Token → 自定义模板：Permissions = Account → Cloudflare Pages → Edit，Account Resources 勾选目标账号 → 生成后粘贴
CLOUDFLARE_ACCOUNT_ID取值见 A:\c\Darra\各环境最高授权.env 的 CLOUDFLARE_ACCOUNT_ID

token 与账号 ID 严禁写进仓库任何文件（workflow 只引用 ${{ secrets.* }}）。

五、自定义域名绑定（profine.darra.xyz）​

  1. CF Pages 项目 → Custom domains → Set up a custom domain → 输入 profine.darra.xyz → Continue。
  2. darra.xyz 的 DNS 已在 Cloudflare 托管（同账号），系统自动创建 CNAME profine → <项目>.pages.dev（Proxied）；若提示手动添加，按面板给的名称/内容照填即可。
  3. 等待状态变 Active（通常几分钟），证书（边缘证书）自动签发。

六、首次推送后验证​

  1. 推送 master（含本次 docs 变更 + workflow）→ GitHub Actions 页 deploy-docs 全绿（npm ci → build → deploy 三步）。
  2. CF Pages 项目 → Deployments：出现 production 部署成功记录（由 pages-action 创建）。
  3. 浏览器访问 https://profine.darra.xyz：首页正常，抽查 /api/csharp、/guide/quickstart 等页面。
  4. 后续 docs/** 任意改动 push 即自动部署；失败可在 Actions 页 workflow_dispatch 手动重跑。

七、本地构建验证（开发用）​

cd docs
npm install                # 首次
npm run build              # 构建到 docs/build/
npx docusaurus serve       # 本地预览产物 (默认 3000 端口)
  • docs/deploy-docs.ps1 -Deploy（scp 上传阿里云 118.178.181.207:/var/www/pnet-doc）为遗留方式，脚本保留仅作本地构建用途；官网生产部署一律走 GH Actions → CF Pages。
  • docs/build/、docs/node_modules/ 已被根 .gitignore 排除，不入库。