迁移再索引报告

本指南介绍如何在 Cloudflare Workers Vectorize 环境下，安全地清空并重新索引数据库，确保所有内容具备正确的语言、URL 和标题元数据。

步骤概览¶

分析当前向量存储配置
系统采用 Cloudflare Workers + Vectorize，配置见 wrangler.toml，索引名为 website-rag。
清空机制：在 worker.ts 中实现了 /admin/clear-all 端点（158-200 行）。
准备数据库清空与重建脚本
使用 scripts/full-reindex.ts 脚本可批量删除所有向量并重建索引。
清空操作会移除 ingest_state.json，强制全量重建。
配置与验证 fast-ingest.ts
scripts/fast-ingest.ts 已正确处理所有元数据，包括语言、URL 和标题。

语言检测示例：

const language: 'en' | 'zh' = cleanPath.startsWith('en/') ? 'en' : 'zh';

URL 生成规则：
- 中文博客：/blog/{slug}/
- 英文博客：/en/blog/{slug}/
- 中文静态页：去除 zh/ 前缀
- 英文静态页：保留 en/ 前缀

标题提取示例：

const title = (fm.data && (fm.data.title || fm.data.Title)) || '';

元数据结构：

{
  id: generateShortId(baseUrl, sourcePath, chunkIndex),
  vector: finalVector,
  text: text.length > 500 ? text.substring(0, 500) + '...' : text,
  title: title.length > 100 ? title.substring(0, 100) : title,
  source: sourcePath,
  url: baseUrl,
  language: language
}

元数据验证
运行 scripts/verify-metadata.ts 检查所有文件的元数据结构。

示例输出：

📄 File: en/about/_index.md
   Title: About
   URL: https://jimmysong.io/en/about
   Language: en
   Chunks: 2

📄 File: zh/about/_index.md
   Title: 关于
   URL: https://jimmysong.io/about
   Language: zh
   Chunks: 2

验证点包括：文件数量、语言检测、URL 生成、标题提取、源路径追踪。
执行重建与验证流程
全量重建：scripts/full-reindex.ts
快速增量：scripts/fast-ingest.ts
元数据验证：scripts/verify-metadata.ts
小批量测试：scripts/mini-test-ingest.ts

注意事项与限制¶

API 配额不足时（如 Qwen 免费额度耗尽），可先完成结构验证，待额度恢复后再执行实际索引。
遇到 AllocationQuota.FreeTierOnly 或 limit_requests 错误时，建议先进行本地验证。

操作命令示例¶

# 全量清空并重建数据库
PROVIDER=qwen ADMIN_TOKEN=你的管理密钥 \
WORKER_URL=https://website-rag-worker.jimmysong.io \
QWEN_API_KEY=你的Qwen密钥 \
npx tsx scripts/full-reindex.ts

# 快速增量索引（upsert模式）
npx tsx scripts/fast-ingest.ts

架构流程图¶

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Content Dir   │───▶│  fast-ingest.ts  │───▶│ Cloudflare      │
│   335 files     │    │                  │    │ Vectorize       │
│   - zh/blog/*   │    │ ✅ Language      │    │ Index           │
│   - en/blog/*   │    │ ✅ URL Gen       │    │                 │
│   - */about/*   │    │ ✅ Title         │    │ website-rag     │
│   - */contact/* │    │ ✅ Source        │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

验证要点¶

✅ 语言元数据：正确识别 zh 和 en
✅ URL 元数据：按语言生成正确路径
✅ 标题元数据：从 frontmatter 提取
✅ 源路径元数据：保持文件追踪
✅ 向量兼容性：EMBED_DIM=1024
✅ 上传流程：管理端点与认证机制已就绪

总结¶

只需按照上述步骤，结合脚本和命令，即可安全完成数据库的重新索引。所有元数据结构已验证，API 配额恢复后即可执行重建，确保内容检索的准确性和完整性。