常见问题（FAQ）与故障排查

本文解答 IndexFlow 的常见运维问题、错误代码和故障排查步骤。

技术 SEO 与质量门

Q1：为什么 IndexFlow 将 301/302 重定向标记为门失败（HTTP 301 / HTTP 302）？

答案：IndexFlow 的探测器有意使用不跟随 HTTP 策略（redirect::Policy::none()）。提交给搜索引擎的 sitemap 只能包含返回 200 OK 的规范最终 URL。

Q2：为什么我的 URL 失败并显示“Canonical URL mismatch”？

答案：IndexFlow 将页面 URL 与声明的 <link rel="canonical" href="..."> 比较。不同域名、协议、路径或大小写，canonical 为空或指向非规范参数变体时会失败。尾部斜杠、默认端口、fragment 和查询参数顺序等无关差异会自动容忍。

Q3：为什么出现“decompression bomb: inflated size exceeds 52428800 bytes”？

答案：Google sitemap 协议规定单文档解压上限为 50 MiB。IndexFlow 通过 MAX_UNCOMPRESSED_BYTES = 50 * 1024 * 1024 强制执行该限制，超出时请拆分 sitemap。

搜索引擎集成与配额

Q4：IndexFlow 如何处理 Google Search Console 429 配额耗尽？

答案：Google 每个项目每天限制 2,000 次 URL Inspection。收到 HTTP 429 时，GscInspectWorker 立即触发熔断并停止检查。应使用 Sync Google Impressions（POST /api/v1/pipeline/gsc-inspect/sync）批量标记已索引 URL，不消耗 Inspection 配额。

Q5：Google Indexing API 每日配额何时重置？

答案：API 每天允许 200 个 URL 通知。IndexFlow 使用滚动 24 小时窗口，并在达到限制时设置 sites.google_quota_paused_until，窗口释放容量后自动恢复。

Q6：为什么 Bing 检查时返回 UNKNOWN？

答案：Bing Webmaster Tools 限制为 1.5 QPS。遇到 ThrottleHost、ErrorCode: 5 或 HTTP 429 时，IndexFlow 保持 bing_index_status = 'UNKNOWN'，休眠 2 秒，并保留队列以便下次自动重试。

Q7：如何绕过 Cloudflare Bot Fight Mode 或 403 Forbidden？

答案：在 /settings 添加秘密 token，在 Cloudflare Dashboard 的 Security -> WAF -> Custom Rules 创建 User Agent contains 规则，并选择跳过 WAF Managed Rules、Bot Fight Mode 和 Rate Limiting。

系统与数据库操作

Q8：如何重置遗忘的管理员密码？

答案：管理员账户以 bcrypt 哈希保存在 SQLite 中，可使用 sqlite3 CLI 直接更新，或删除数据库记录以重新触发 /setup 向导：

# Generate a new bcrypt hash (example password: "NewPassword123!")
# Or update the admin user to a known hash:
sqlite3 /var/lib/indexflow/indexflow.db \
  "UPDATE admin_users SET password_hash = '\$2b\$12\$e8O9yqL1jNqZ7qZ1e6dF0eXm8w8B9g0F.4qL5u8v7w6x5y4z3a2b1' WHERE username = 'admin';"

Q9：SQLite 出现“database is locked”时怎么办？

答案：IndexFlow 自动启用 WAL 和 busy_timeout = 5000ms。仍遇到锁时，确认没有外部进程持有写事务，并确认数据库位于本地 NVMe/SSD，而非 NFS/CIFS 网络文件系统。