# Clover 排障手册

## 服务不可访问

```bash
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs --tail=100 nginx
curl -I http://127.0.0.1/
```

## 后端异常

```bash
curl http://127.0.0.1/health
docker compose -f docker-compose.prod.yml logs --tail=200 api
docker compose -f docker-compose.prod.yml logs --tail=200 worker
```

## SSE 没有实时进度

检查 nginx 是否关闭缓冲：

```bash
curl -N -H "Accept: text/event-stream" "http://127.0.0.1/api/v1/tasks/<task_id>/stream?ticket=<ticket>"
```

应能持续收到 named event。nginx 配置必须包含 `proxy_buffering off` 和 `X-Accel-Buffering: no`。

## 图片显示 404

```bash
docker compose -f docker-compose.prod.yml exec api ls -lah /app/uploads
docker compose -f docker-compose.prod.yml exec worker ls -lah /app/uploads
curl -I http://127.0.0.1/uploads/<path>
```

api 和 worker 必须共享同一个 `uploads` volume。

## 生成失败

常见原因：

- 客户未录入 API Key。
- provider key 余额不足或无权限。
- 上游中转站 429/503。
- 产品入镜但未上传产品图。

查看 worker 日志：

```bash
docker compose -f docker-compose.prod.yml logs --tail=200 worker
```