故障排查

配置修改没有生效

.env 只在进程启动时读取。停止并重新启动后端；仅依赖 uvicorn --reload 不会重新加载配置。

配置向导没有出现

向导只在缺少关键配置时自动启用。可直接启动独立入口：

cd backend
uv run python -m xuwen.web_ui --language zh-CN

然后访问 http://127.0.0.1:8765/config/，使用该进程打印的会话 token（不是聊天 API key）。重启后需使用新打印的 token；独立入口支持 --language en|zh-CN。

Embedding 返回 400 或维度错误

确认 EMBEDDING_API_URL 是 OpenAI 兼容 /embeddings 接口，并核对 EMBEDDING_MODEL 与 EMBEDDING_DIM。更换模型或维度后需要重建旧向量表，见下一节。

基础地址保留供应商要求的 /v1 等路径，不重复填写 /embeddings。HTML 页面返回 200 不代表 API 已连通；/v1 返回 503 应查看上游 JSON 诊断，不能仅为了访问到网页就移除 /v1。

导入报 Spill has sent an error

完整报错类似 RuntimeError: lance error: LanceError(IO): Execution error: Spill has sent an error。 虽然带有 IO 字样，但它通常不是磁盘或内存问题，而是向量库表的维度与当前 EMBEDDING_DIM 不一致，例如首次启动时按默认维度建了表，之后在向导里换成了其它维度的 Embedding 模型。 降低并发或批量都无法解决。

后端在启动和导入时会自动把维度不一致的空表按新维度重建；表里已有数据时，导入会在调用 Embedding 之前直接提示维度不一致。处理方式：

• 想保留已有数据：改回原来的 Embedding 模型和 EMBEDDING_DIM。
• 换用新模型：停止后端，备份并删除 LANCE_DB_PATH（默认 .data/lancedb），再启动并重新导入。 不同模型的向量不能混用。

Docker 部署可以直接在容器内删除后重启（默认容器名为 afterglow-backend）：

下面的命令仅适用于 LANCE_DB_PATH 使用默认值 .data/lancedb，且该目录在容器内挂载为 /host-backend/.data/lancedb 的部署。使用自定义 LANCE_DB_PATH 时，请将删除命令中的路径替换为容器内实际的数据库目录。

docker exec afterglow-backend rm -rf /host-backend/.data/lancedb
docker restart afterglow-backend

Embedding 返回 429

降低 EMBEDDING_MAX_CONCURRENCY，并根据供应商限制设置 EMBEDDING_MAX_REQUESTS_PER_MINUTE。已成功入库的批次不会丢失，修正配置后重新执行导入即可。

ZoneInfoNotFoundError: No time zone found with key UTC

确保项目安装了 tzdata，并重新同步依赖：

cd backend
uv sync --extra dev

同时确认 APP_TIMEZONE 使用有效 IANA 时区，例如 Asia/Shanghai。

LanceDB 写入错误

先确认磁盘空间和 .data 目录权限。大批量写入仍失败时，可临时降低 EMBEDDING_BATCH_SIZE，然后重新执行导入。

联网搜索或 URL 读取没有内容

检查 WEB_ACCESS_ENABLED、WEB_FETCH_ENABLED、provider URL 与密钥。联网能力只在用户消息明确需要 实时公开信息时触发，不会对每轮对话自动搜索。

诊断命令

cd backend
uv run python -m xuwen.ingestion.cli stats --language zh-CN
curl http://127.0.0.1:8000/healthz
curl -H "Accept-Language: zh-CN" -H "Authorization: Bearer <XUWEN_API_KEY>" \
  http://127.0.0.1:8000/readyz

需要提交 Issue 时，请提供脱敏后的错误日志、版本、系统、Python 版本和最小复现步骤。不要上传真实聊天文件、 .env 或 API key。