如何把 n8n-workflows 的 GitHub Pages 静态站点构建脚本跑通?

原创2026-09-09 17:50:531,615 阅读
文章标签:后端工作流自动化前端开发者工具

如何把 n8n-workflows 的 GitHub Pages 静态站点构建脚本跑通?

n8n-workflows 仓库在 docs/ 目录下放了一个可浏览、可搜索的静态站点,通过 GitHub Pages 对外发布。站点里的静态数据(搜索索引、统计、分类与集成列表)不是手写的,而是由 scripts/ 下的 Python 脚本生成的:先建 SQLite 工作流数据库,再由 generate_search_index.py 产出 docs/api/ 下的 JSON,最后用 update_github_pages.py 完成 Pages 配置并校验部署文件是否齐全。本文把这条链路在本地完整跑一遍。

前提:本地已有 Python 3.9+(README.md 的 Prerequisites 还要求 pip 和 100MB 磁盘空间),所有命令都在仓库根目录执行。

准备环境并生成工作流数据库

scripts/generate_search_index.py 和 scripts/update_readme_stats.py 都从仓库根目录的 workflow_db.py 导入 WorkflowDatabase,并读取 database/workflows.db。这个数据库文件需要先生成:

pip install -r requirements.txt
python run.py --reindex

requirements.txt 注释说明核心依赖兼容 Python 3.9–3.12。如果 database/workflows.db 不存在就跳过这一步直接跑索引脚本,脚本会打印 Database not found: database/workflows.db,提示 Run 'python run.py --reindex' first to create the database,然后以退出码 1 结束——这是脚本自带的第一道检查点,看到它就说明先执行 --reindex。

生成静态搜索索引

python scripts/generate_search_index.py

这个脚本做的事,按源码顺序是:

  1. 从 database/workflows.db 读取全部工作流(limit=10000)和统计信息;
  2. 为每条工作流生成 searchable_text(名称、描述、文件名、集成、标签的拼接小写串)和分类。分类优先取 context/search_categories.json 中已有的分配;该文件不存在时打印 Warning: search_categories.json not found, using integration-based categorization 并回退到按集成归属分类,不影响运行;
  3. 向 docs/api/ 写入四个文件:
    • search-index.json:完整索引,version 为 "1.0",包含 stats、categories、integrations、workflows 四部分;
    • stats.json:仅统计部分,便于快速加载;
    • categories.json:分类列表;
    • integrations.json:按出现次数排序的前 50 个集成。

运行成功的输出形如(具体数值以你本地数据库为准):

Search index generated successfully:
   4343 workflows indexed
   20 categories
   50 popular integrations
   Files saved to: docs/api
Static search index ready for GitHub Pages!

验证方式:确认 docs/api/ 下出现了上述四个 JSON,且 search-index.json 中每条 workflow 带有 name、filename、category、download_url 等字段。

跑 update_github_pages.py 完成配置与校验

python scripts/update_github_pages.py

先说副作用:scripts/update_github_pages.py 没有命令行筛选参数,每次运行会完整执行四步并写入 docs/ 下的多个文件:

  • 更新 docs/index.html 页脚中 Last updated: Month Year 文本为当前月/年,并向 <head> 插入一个 <meta name="last-updated" ...> 标签(已存在时不重复插入);
  • 重写 docs/api/metadata.json(内容为 version: "2.0.1"、deployment_type: "github_pages" 及当前时间戳),若 docs/api/stats.json 存在则刷新其中的 last_updated 字段;
  • 重新生成 docs/_config.yml(theme: null、baseurl: "/n8n-workflows"、url: "https://zie619.github.io",并排除 workflows/、scripts/、src/、k8s/、helm/ 等目录)、docs/.nojekyll 和 docs/404.html;
  • 把 docs/index.html 以及 docs/js/app.js、docs/js/search.js 中的绝对路径引用(href="/css/、src="/js/、fetch("/api/ 等)替换为相对路径,保证站点在 /n8n-workflows 子路径下能正常加载资源。

最后一步是结构校验,检查这 8 个必需文件是否存在:

docs/index.html
docs/css/styles.css
docs/js/app.js
docs/js/search.js
docs/api/search-index.json
docs/api/stats.json
docs/api/categories.json
docs/api/integrations.json

每个文件打印一行 ✅ Found: ... 或 ❌ Missing: ...。全部存在时输出:

✅ All required files present for GitHub Pages deployment
✨ GitHub Pages setup complete!

此时脚本还会打印站点地址 https://zie619.github.io/n8n-workflows/,并提示 push 到 GitHub 后可能需要几分钟页面才更新。如果校验发现缺失文件,脚本会给出重新生成的提示命令(python workflow_db.py --index --force、python create_categories.py、python scripts/generate_search_index.py);此时先确认前一步的索引脚本是否在仓库根目录成功跑完,再按提示补齐缺失文件。

结果验证

判断整条链路跑通,看三点:

  1. docs/api/metadata.json 的内容变为带 last_updated、version: "2.0.1"、deployment_type: "github_pages" 的新时间戳——这是脚本真实执行过的直接证据;
  2. 校验环节打印 All required files present for GitHub Pages deployment,没有 ❌ Missing 行;
  3. 把 docs/ 目录的变化提交并推送到仓库后,访问 https://zie619.github.io/n8n-workflows/ 能看到站点。

可选分支:同步 README 统计数字

如果还需要把 README.md 里写死的工作流数量、集成数等数字刷新为数据库最新值,可以运行:

python scripts/update_readme_stats.py

副作用是改写 README.md 本体:脚本用正则匹配文中的数字段落并替换,成功后打印各项当前统计值与 README.md successfully updated with latest statistics!。它依赖同一个 database/workflows.db,但不产出任何 docs/ 下的站点文件,与静态站构建相互独立,不需要时跳过即可。

已知限制

  • 两个主脚本都没有过滤参数,update_github_pages.py 每次都会完整执行时间戳、配置、URL 修正和校验四个步骤,无法只跑其中某一步。
  • 校验环节只判断文件是否存在,不判断内容是否最新:只改了 workflows/ 数据而不重跑 generate_search_index.py 时,docs/api/ 里仍是旧内容,站点也不会变。
  • Python 版本要求在不同文档中不完全一致:README.md 与 requirements.txt 按 3.9+ / 3.9–3.12 描述,DEPLOYMENT.md 的 “Python Direct Deployment” 一节写的是 3.11+。跑本文这条构建链路时按 README 的 3.9+ 准备即可,两条来源的差异以实际运行报错为准。
登录后查看全文
n8n-workflows