# 异步入库与失败恢复说明 ## 范围 DEMO-015 将单文件上传从 API 请求线程迁移到独立 Celery Worker,DEMO-016 在其上增加逐文件 隔离的批量接收和状态聚合。OceanBase 中的 `ingestion_jobs` 和 `ingestion_attempts` 是执行状态事实源;RabbitMQ 消息只携带 Job ID, 不携带文件内容、Provider 凭据或业务状态。 批次只聚合接收与 Job 状态,不改变每个文件的独立执行和重试边界。 ## 运行时配置 以下值必须通过环境变量或部署 Secret 注入,不得提交真实值: ```text RABBITMQ_URL=amqp://:@:5672/ INGESTION_MAX_ATTEMPTS=3 INGESTION_RETRY_BACKOFF_SECONDS=2 INGESTION_RETRY_BACKOFF_MAX_SECONDS=60 INGESTION_WORKER_LEASE_SECONDS=300 INGESTION_RECOVERY_INTERVAL_SECONDS=30 BATCH_MAX_FILES=20 BATCH_MAX_TOTAL_BYTES=209715200 ``` Worker 与 API 还需要相同的 OceanBase、BOS、Embedding、VectorStore 和 Index Profile 配置。 RabbitMQ 用户应只具备指定 vhost/queue 的最小权限。 ## 启动顺序 ```bash uv run alembic upgrade head make run-worker make run ``` `make run-worker` 在当前 Demo 中同时启动 Worker 和恢复调度器。恢复调度器周期扫描: - 尚未成功投递的 `queued` Job; - 已到重试时间的 `retrying` Job; - Worker 丢失后租约已过期的 `running` Job。 任务投递使用 late acknowledgement、worker-lost reject 和单任务 prefetch。重复消息会先锁定 Job 行;有效租约内不会创建第二个 Attempt。租约过期后,旧 Attempt 以安全错误关闭,再按重试 规则恢复。 ## 重试与清理 确定性的内容错误(无法解析、清洗后为空、无 Chunk、派生数据身份不一致)直接进入 `failed`。 其余运行时/Provider 错误按指数退避重试,默认最多三次总 Attempt。 第二次及后续 Attempt 创建前严格执行: ```text OceanBase Vector rows → ChunkIndexState → Chunk → parsed JSON object → reset Document processing state ``` 不可变源文件、Document、Job 和已结束 Attempt 始终保留。任一清理步骤失败时不创建新 Attempt, Job 直接以 `retry cleanup failed` 终止,禁止在未知脏状态继续执行。 ## API 状态 `POST /api/v1/documents` 成功返回 `202` 和 `job_id`。查询: ```text GET /api/v1/jobs/{job_id} ``` Job 状态为 `queued | running | retrying | succeeded | failed | cancelled`;阶段为 `parsing | cleaning | chunking | embedding | indexing`。公开错误只返回固定安全摘要,不保存或 返回 Broker/Provider 异常正文。活动 Job 的 Document 暂不允许删除,API 返回 `409`。 批量提交与查询: ```text POST /api/v1/ingestion-batches # multipart 字段 files,可重复 GET /api/v1/ingestion-batches/{batch_id} ``` 批次创建后逐文件返回 `accepted` 或 `rejected`;已接收文件继续通过上述 Job 状态异步推进。 批次聚合状态为 `processing | completed | partial_failure | failed`。请求文件数超过 `BATCH_MAX_FILES` 时整体返回 `413`;单文件或共享总字节预算超限只拒绝当前文件,不删除此前 已接收文件。默认总预算 200 MiB,且配置不得小于单文件 `MAX_UPLOAD_BYTES`。 ## 故障检查 1. Job 长期为 `queued`:检查 RabbitMQ 连通性、恢复调度器以及 `ingestion` queue; 2. Job 长期为 `running`:检查 Worker,租约到期后恢复调度器会重新投递; 3. Job 为 `retrying`:等待 `next_run_at`,客户端不应重新上传同一文件; 4. Job 为 `failed` 且错误为 `retry cleanup failed`:停止人工重试,先核对向量、关系数据与 BOS 派生对象的一致性; 5. 不得通过日志打印 `RABBITMQ_URL`、数据库 URL、BOS/模型凭据或原始 Provider 响应。