如何把 n8n-workflows 的 GitHub Pages 静态站点构建脚本跑通?
如何把 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
这个脚本做的事,按源码顺序是:
- 从
database/workflows.db读取全部工作流(limit=10000)和统计信息; - 为每条工作流生成
searchable_text(名称、描述、文件名、集成、标签的拼接小写串)和分类。分类优先取context/search_categories.json中已有的分配;该文件不存在时打印Warning: search_categories.json not found, using integration-based categorization并回退到按集成归属分类,不影响运行; - 向
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);此时先确认前一步的索引脚本是否在仓库根目录成功跑完,再按提示补齐缺失文件。
结果验证
判断整条链路跑通,看三点:
docs/api/metadata.json的内容变为带last_updated、version: "2.0.1"、deployment_type: "github_pages"的新时间戳——这是脚本真实执行过的直接证据;- 校验环节打印
All required files present for GitHub Pages deployment,没有❌ Missing行; - 把
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+ 准备即可,两条来源的差异以实际运行报错为准。