proofdb/scriptdoc/reindex_opensearch.md

OpenSearch 重建索引脚本

脚本路径

scripts/reindex_opensearch.php

脚本作用

根据 PostgreSQL 中已经完成向量化的 chunk，重新构建 OpenSearch 中的 proofdb_chunks 索引内容，并刷新每条 chunk 的派生搜索字段。

脚本会做这些事：

1. 确保 OpenSearch 索引存在。
2. 把已向量化 chunk 的 search_index_status 重置为待索引。
3. 按 archive 批量重新投递索引任务。
4. 调用现有 OpenSearch indexing handler 批量写入 chunk 文档。
5. 输出重建统计结果。

运行前提

• PostgreSQL 可连接。
• OpenSearch 可连接。
• 目标 chunk 的 embedding_status 已经是 embedded。
• 项目依赖已安装完成。
• 从项目根目录执行命令。

如果本地 OpenSearch 使用 HTTPS 且证书是自签名：

OPENSEARCH_SSL_VERIFY=false php scripts/reindex_opensearch.php

运行命令

全量重建：

php scripts/reindex_opensearch.php

只重建一个 archive：

php scripts/reindex_opensearch.php --archive_uid=01KQHVREB6XPYF604RVZAP9NNY

成功输出示例

OpenSearch reindex completed.
Index: proofdb_chunks
Archive filter: (all embedded archives)
Reset chunks: 14
Indexed archives: 1
Indexed chunk rows now marked indexed: 14
Archives: 01KQHVREB6XPYF604RVZAP9NNY

适用场景

• proofdb_chunks 被误删后恢复。
• 数据库里 search_index_status=3，但 OpenSearch 中没有对应文档。
• 索引 mapping 重建后，需要把已经 embedding 完成的数据重新灌回 OpenSearch。
• archive 的 summary、title、tags 等搜索元数据有更新后，需要刷新到 OpenSearch。

重要限制

这个脚本只处理已经向量化完成的 chunk。

它不会：

• 重新生成 embedding。
• 修复 embedding 失败的数据。
• 修复 PostgreSQL 中缺失的 archive 或 chunk。

推荐用法

如果 OpenSearch 整个索引丢了，通常按下面顺序执行：

php scripts/setup_opensearch.php
php scripts/reindex_opensearch.php

如果数据库 schema 也有变动，则先补数据库：

php scripts/setup_database.php
php scripts/setup_opensearch.php
php scripts/reindex_opensearch.php