#故障排查

当应用实际表现和 Quick Start 里说的预期不一致时，就看这一页。

#连接问题

#“Connection refused” 或 “Cannot connect to database”

典型原因： 缺少 .env，或者 DATABASE_URL 仍指向 localhost，但 Docker Compose 期望的是服务名。

修复：

# 在 Docker 里使用 postgres 服务名
DATABASE_URL=postgresql+psycopg://eval752:password@postgres:5432/eval752

docker compose down
docker compose up -d

#“ENCRYPTION_KEY not set”

典型原因： 后端启动时没有拿到非空的加密密钥。

修复：

openssl rand -hex 32

# 把生成值写入 .env，然后重启
docker compose restart backend

#Provider 问题

#“Provider smoke test failed”

可先按失败类型缩小范围：

• 401 或 403：key 错了、org/project 错了，或额度不足
• 404：base URL 错了，或者 endpoint root 错了
• timeout / network error：provider 主机不可达
• 改过旧工作区后出现 500：加密 secrets 可能和当前 ENCRYPTION_KEY 不匹配

修复：

1. 去厂商后台确认 provider key 是否正确。
2. 对照厂商文档检查 base URL。
3. 如果应用跑在 Docker 里，而模型服务跑在宿主机上，请使用 host.docker.internal，不要用 localhost。
4. 在发起完整 run 前，再跑一次 smoke test。

#“改了 ENCRYPTION_KEY 之后 smoke test 返回 500”

典型原因： 你的数据库 volume 里还保存着用旧 key 加密的 provider secrets。

对一次性本地工作区最快的修复方式：

docker compose down -v
docker compose up -d

如果你必须保留旧 provider 记录，就恢复旧的 ENCRYPTION_KEY，而不是直接清掉 volume。

#Dataset 问题

#“Dataset import failed”

典型原因：

• Hugging Face dataset 路径写错
• 私有数据集但没有 token
• 预览或导入超时

修复：

1. 从 Hugging Face Datasets 直接复制准确路径。
2. 如果是私有数据集，补上 HF token。
3. 先从 test[:30] 这类小切片开始，更快验证映射是否正确。

#Run 问题

#“Run stuck in Pending”

典型原因： worker 挂了，或者连不上 Redis / PostgreSQL。

修复：

docker compose ps celery-worker
docker compose logs -f celery-worker
docker compose restart celery-worker

如果 run 仍然卡在 pending，也顺手检查 backend 和 redis 的日志。

完整的首次运行路径见 Quick Start。