企业官网建设流程全解析

n8n-workflows 的工作流数据库怎么重建索引让搜索生效？--reindex 与 /api/reindex 的用法

【免费下载链接】n8n-workflowsall of the workflows of n8n i could find (also from the site itself)项目地址: https://gitcode.com/GitHub_Trending/n8nworkflo/n8n-workflows

n8n-workflows 仓库自带一个 SQLite 工作流搜索引擎：仓库里的 4000 多个 workflow JSON 文件被解析成元数据写入workflows表，并同步到 FTS5 全文索引表workflows_fts，/api/workflows?q=...的搜索就走这个索引。当工作流文件更新、数据库库结构（schema）变化、或者你想强制重算所有文件时，就需要重建索引，否则搜索命中的还是旧数据。本文介绍两条文档给出的重建路径：启动期用python run.py --reindex，服务运行中用POST /api/reindex，以及各自的验证方式。

先理解索引和搜索的关系

• 索引库是database/workflows.db（SQLite），由 run.py 在启动时创建；表结构定义在 workflow_db.py。
• workflow_db.py 中建了 FTS5 虚表workflows_fts，外部内容指向workflows表，并通过三个触发器（workflows_ai/workflows_ad/workflows_au）在workflows表插入、删除、更新时自动同步 FTS 数据。索引过程用INSERT OR REPLACE写入workflows表，所以重建索引后 FTS 索引会随之更新。
• 带查询词的搜索走 FTS：workflow_db.py 中只要q非空就用workflows_fts MATCH ?并按 rank 排序。
• 非强制模式下，index_all_workflows会比较文件内容哈希，只重算哈希变化的文件（workflow_db.py）；force_reindex=True则强制重算所有workflows/*.json文件。

也就是说：日常增量更新可以靠启动时的自动索引，需要“全部重来”时才用本文的两个强制入口。

准备条件

• 按 README.md，本地安装要求 Python 3.9+、pip 和约 100MB 磁盘空间；DEPLOYMENT.md 的“Python Direct Deployment”一节写的是 Python 3.11+，两处文档要求不一致，建议按较高的 3.11 准备环境。
• 安装依赖（run.py 启动前会检查sqlite3、uvicorn、fastapi是否可导入，缺失时提示用下面这条命令安装并退出）：

pip install -r requirements.txt

• 工作流 JSON 位于仓库的workflows/目录，索引器通过rglob("*.json")扫描该目录（workflow_db.py），所以执行时要保证这个目录存在，否则会打印 “Warning: Workflows directory 'workflows' not found.” 并返回processed: 0。

主路径：python run.py --reindex

run.py 的--reindex参数说明就是 “Force database reindexing”，它会以force_reindex=True调用索引，并在索引完成后继续启动服务器（默认127.0.0.1:8000）：

python run.py --reindex

执行后的正常输出顺序（run.py）：

1. 依赖检查通过后，打印📚 Indexing workflows...；
2. 索引完成后打印✅ Indexed {processed} workflows和📊 Database contains {total} workflows；
3. workflow_db.py 还会打印一条汇总：✅ Indexing complete: {processed} processed, {skipped} skipped, {errors} errors。errors > 0表示有文件解析失败，失败文件名会以Error processing {file_path}: ...逐条打印，可据此定位坏文件。

几个必须知道的边界：

• CI 环境会自动跳过索引：run.py检测到环境变量CI为true/1/yes时等同于--skip-index，此时即使带--reindex也不会索引，只打印数据库现有数量（run.py）。在 CI 里重建索引需要先把CI设为其他值。
• 首次克隆不需要手动 --reindex：setup_database发现stats["total"] == 0（空库）时会自动执行一次强制索引（run.py），--reindex主要用于“库已有数据但需要强制重算”的情况。
• 如果只想重新索引、不启动服务器，workflow_db.py 自带 CLI：python workflow_db.py --index --force（--force对应 “Force reindex all files”）。注意它的默认库路径与run.py不同：workflow_db.py 中WorkflowDatabase()未传参时读环境变量WORKFLOW_DB_PATH，未设置时落在仓库根目录的workflows.db，而run.py固定写database/workflows.db。用这个 CLI 时请通过WORKFLOW_DB_PATH=database/workflows.db指向同一个库文件，否则你会在一个空库上做索引。

替代路径：POST /api/reindex（服务已在运行时）

服务跑起来后（包括 Docker、gunicorn 等直接加载api_server:app的部署，这些方式不会执行run.py的索引逻辑），用 API 触发后台重建。DEPLOYMENT.md 的 “Database Optimization” 一节给出的命令是：

curl -X POST http://localhost:8000/api/reindex

但按当前代码，这条裸调用会失败，因为端点已加认证（SECURITY.md 记录该修复于 2025 年 11 月，版本 2.0.1；DEPLOYMENT.md 的示例未更新 token 参数）。实际用法以 api_server.py 为准：

1. 先设置 ADMIN_TOKEN 环境变量。服务端启动前导出一个随机 token（SECURITY.md）：

export ADMIN_TOKEN="your-secure-random-token"

如果没设置该环境变量，端点直接返回 503，detail为 “Reindexing endpoint is disabled. Set ADMIN_TOKEN environment variable to enable.”。

2. 携带admin_token查询参数触发重建。下面是force=true的完整示例；admin_token替换为你自己导出的值，force可省略（默认False，即按文件哈希只重算变化的文件）：

curl -X POST "http://localhost:8000/api/reindex?admin_token=<你的ADMIN_TOKEN>&force=true"

3. 判断触发是否成功。该接口是后台任务模式：请求成功时立即返回 200 和{"message": "Reindexing started in background", "requested_by": "<客户端IP>"}（api_server.py），并不等索引完成。索引真正结束要在应用日志里找这两行之一：

• 成功：Reindexing completed successfully (requested by <客户端IP>)
• 失败：Error during reindexing: <异常信息>

可能遇到的错误码（均来自 api_server.py 和 SECURITY.md）：

结果验证

通过 API 验证（服务运行时）：

# 健康检查兼统计，DEPLOYMENT.md 的 Health Checks 一节即用此命令 curl http://localhost:8000/api/stats # 用搜索接口确认 FTS 能命中，例如查 telegram 相关工作流 curl "http://localhost:8000/api/workflows?q=telegram"

/api/stats返回total、active、triggers等统计（workflow_db.py），total应与索引输出的processed数量级一致（本仓库工作流数量级为 4000+）。/api/workflows?q=...带查询词时走 FTS 并返回按 rank 排序的结果（api_server.py、workflow_db.py）。注意 README.md 的 API 表里写的是/api/search，而api_server.py中实际路由是/api/workflows，两处不一致，以代码里的/api/workflows为准。

纯 CLI 验证（不启动服务器）：

# 先确保 WORKFLOW_DB_PATH 指向 run.py 使用的库文件 WORKFLOW_DB_PATH=database/workflows.db python workflow_db.py --stats WORKFLOW_DB_PATH=database/workflows.db python workflow_db.py --search telegram

--stats打印 Total workflows / Active / Total nodes 等；--search打印 “Found {total} workflows:” 及前 10 条名称（workflow_db.py）。

另外，scripts/generate_search_index.py 依赖数据库已建好：数据库缺失时它直接提示Run 'python run.py --reindex' first to create the database，所以生成context/*.json等搜索上下文文件之前，也要先完成一次索引。

常见问题与限制

• schema 变化后的重建：DEPLOYMENT.md 的 “Database Migration” 给出的流程是：先备份cp database/workflows.db database/workflows.db.backup，再执行python run.py --reindex用新 schema 强制重建。重建前备份是文档推荐的固定动作。
• 数据库锁：遇到 locked 错误时，DEPLOYMENT.md 的排查命令是ls -la database/检查权限，必要时chmod 664 database/workflows.db。
• 强制重建的代价：force模式会重算workflows/下全部 JSON 文件，本仓库有 4000+ 文件，执行时间明显长于增量索引；能增量就不要强刷。
• Docker 部署：镜像内数据库放在容器/app/database（宿主机挂载$(pwd)/database，见 DEPLOYMENT.md），在容器外不方便直接跑run.py --reindex时，使用带ADMIN_TOKEN的/api/reindex是文档给出的方式；环境变量表中的DATABASE_PATH默认值也是database/workflows.db（DEPLOYMENT.md）。
• gunicorn 直接启动：gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 api_server:app（DEPLOYMENT.md）不会执行run.py的初始化索引逻辑，api_server.py导入时只建库结构不灌数据，库为空时用/api/reindex（带 token）触发首次/重建索引。

两条路径最终都落到同一个index_all_workflows：--reindex是启动前的同步强制重建，/api/reindex是运行中的后台强制（或增量）重建。完成后用/api/stats的total和/api/workflows?q=...的 FTS 命中来确认搜索已生效；如果带查询词搜索没有排序结果或errors计数不为 0，就回到索引输出日志里按文件名排查。

【免费下载链接】n8n-workflowsall of the workflows of n8n i could find (also from the site itself)项目地址: https://gitcode.com/GitHub_Trending/n8nworkflo/n8n-workflows