28 KiB
Thread 创建慢与回答结束后 History 等待:完整排查手册
日期:2026-10-22
适用范围:DeerFlow Gateway、LangGraph useStream、PostgreSQL 业务库与 PostgreSQL checkpointer。
1. 先说结论
当前代码证据表明:
-
POST /api/threads不查询runs表。它查询/写入threads_meta,然后同步写入一个空 checkpoint。 -
创建 run 时,持久化层主要执行
INSERT INTO runs (...);run 结束时主要执行UPDATE runs ... WHERE run_id = ?。run_id是主键,runs有 5 万行本身通常不足以造成 6 秒延迟。 -
回答流结束后出现
POST /api/threads/{thread_id}/history是前端 SDK 的正常行为。当前前端配置fetchStateHistory: { limit: 1 },SDK 会等待这个请求完成后才结束isLoading,因此会出现“回答文字已经显示完,但页面仍在等待中”。 -
/history实际查询checkpoints、checkpoint_blobs、checkpoint_writes,不是查询runs。 -
当前
/history只传thread_id,核心查询是:WHERE thread_id = $1 ORDER BY checkpoint_id DESC LIMIT 1checkpoints主键为(thread_id, checkpoint_ns, checkpoint_id)。当不限定checkpoint_ns时,主键不能直接提供跨 namespace 的checkpoint_id顺序,可能需要扫描该 thread 的候选行并做 top-N Sort。 -
当前进程只创建一个全局
AsyncPostgresSaver。该 saver 在取得连接池连接之前先获取实例级asyncio.Lock,所以 checkpoint 的aget/alist/aput/aput_writes在一个 Gateway 进程内实际是串行的。慢/history会延长持锁时间,并阻塞新 thread 的空 checkpoint 写入。
最符合当前现象的候选链路是:
回答正文已经通过 SSE 到达浏览器
-> 后端完成 run 收尾并发送 SSE end
-> 前端 SDK 同步请求 /history
-> /history 查询或反序列化 checkpoint,期间占用 saver 实例锁
-> SDK 的 isLoading 仍为 true,页面继续显示等待
-> 同期创建新 thread 时,checkpoint_create 等待同一把 saver 锁
-> POST /threads 偶发耗时数秒
这只是代码层面的高概率根因。最终必须使用同一次线上复现的 Server-Timing、Gateway 日志和 PostgreSQL 活动快照闭环确认。
2. 两类 PostgreSQL 数据不要混淆
系统存在两类持久化访问。即使它们使用同一个 PostgreSQL DSN,也有不同的连接池和代码路径。
| 类型 | 主要表 | 主要用途 |
|---|---|---|
| 应用 ORM 数据 | threads_meta、runs |
会话元数据、run 状态、统计字段 |
| LangGraph checkpointer | checkpoints、checkpoint_blobs、checkpoint_writes、checkpoint_migrations |
对话状态、消息、通道值、pending writes |
排查前先记录:
部署 commit:
前端构建版本:
Gateway worker 数:
database.backend:
database PostgreSQL 主机/库名(脱敏):
checkpointer 实际后端:
checkpointer PostgreSQL 主机/库名(脱敏):
langgraph-checkpoint-postgres 版本:
注意:
- 仅确认
database.backend=postgres不等于已经确认/history使用 PostgreSQL checkpointer。 - 当前运行时可能由统一
database.postgres_url提供业务 ORM 与 checkpointer,也可能使用兼容配置中的独立checkpointer段。 - 若 legacy 配置为
checkpointer.type=postgres但use_postgres=false,checkpointer 会回退 SQLite。 - 当前 live run 与 SSE bridge 是进程内状态,正常部署要求
GATEWAY_WORKERS=1。不要用盲目增加 worker 的方式绕过该问题。
3. 浏览器看到的完整请求时间线
sequenceDiagram
participant UI as 浏览器 / useStream
participant API as Gateway
participant APPDB as 业务 PostgreSQL
participant CP as Checkpointer PostgreSQL
UI->>API: POST /api/threads
API->>APPDB: SELECT/INSERT threads_meta
API->>CP: UPSERT 初始 checkpoint
API-->>UI: thread_id
UI->>API: POST /api/threads/{id}/runs/stream
API->>APPDB: INSERT runs
API-->>UI: SSE 正文/工具事件
API->>CP: 持续写 checkpoint/blob/write
API->>APPDB: UPDATE runs 终态
API-->>UI: SSE end
UI->>API: POST /api/threads/{id}/history limit=1
API->>CP: 最新 checkpoint + blob/write
API-->>UI: history
Note over UI: history 完成后 isLoading 才结束
3.1 创建新会话
前端 SDK 在没有 threadId 时,会先 await client.threads.create(...),成功后才发起 runs.stream(...)。因此 POST /api/threads 慢 6 秒,会直接表现为点击发送后 6 秒才开始回答流。
后端调用位置:
app/gateway/routers/threads.py:853-927- 前端使用点:
frontend-web/src/core/threads/hooks.ts:702-711 - SDK 等待 thread create:安装包
dist/react/stream.lgp.js:318-327
3.2 回答结束后的 History
当前前端配置:
fetchStateHistory: { limit: 1 }
SDK 在 SSE 成功结束后执行:
const lastHead = (await history.mutate(threadId))?.at(0);
之后才调用 onFinish 并结束当前 stream loading 状态。当前项目的 onFinish(state, runMeta) 还显式接收最终 state,所以 SDK 也需要拿到 history state。
相关位置:
frontend-web/src/core/threads/hooks.ts:711frontend-web/src/core/threads/hooks.ts:976-1038- SDK
dist/react/stream.lgp.js:379-388 - 页面最终暴露的 loading:
frontend-web/src/core/threads/hooks.ts:1920 - 普通控制/history 请求超时保护:
frontend-web/src/core/api/api-client.ts:96-101,当前为 30 秒
结论:最后看到 /history 并不表示模型还在生成;它可能只是 SDK 在做结束后的最终状态刷新。
4. 每个阶段实际执行什么 SQL
以下为当前代码和 langgraph-checkpoint-postgres==3.1.2 对应的等价 SQL。SQLAlchemy/psycopg 最终的占位符和列顺序可能略有差异,但访问表、过滤条件和索引需求一致。
4.1 POST /api/threads
调用链:
threads.create_thread
-> ThreadMetaRepository.get
-> ThreadMetaRepository.create(仅新 thread)
-> AsyncPostgresSaver.aput(empty_checkpoint)
第一步,幂等查询:
SELECT ...
FROM threads_meta
WHERE thread_id = $1;
threads_meta.thread_id 应为主键。
新 thread 写元数据:
INSERT INTO threads_meta (...)
VALUES (...);
同步写入初始 checkpoint:
INSERT INTO checkpoints (
thread_id,
checkpoint_ns,
checkpoint_id,
parent_checkpoint_id,
checkpoint,
metadata
)
VALUES ($1, '', $2, NULL, $3, $4)
ON CONFLICT (thread_id, checkpoint_ns, checkpoint_id)
DO UPDATE SET
checkpoint = EXCLUDED.checkpoint,
metadata = EXCLUDED.metadata;
初始 checkpoint 的 new_versions={},通常不会同时写 checkpoint_blobs。
该接口分阶段计时:
Server-Timing 字段 |
实际内容 |
|---|---|
metadata_lookup |
threads_meta 按 thread_id 查询 |
metadata_create |
新建 threads_meta 并提交事务 |
checkpoint_create |
等待 saver 锁、取得连接、写 checkpoint、提交/同步 pipeline |
handler_total |
进入 route handler 后的总时间 |
关键点:该接口的整条路径不读取或写入 runs。
4.2 POST /api/threads/{thread_id}/runs/stream
调用链:
thread_runs.stream_run
-> services.start_run
-> RunManager.create_or_reject
-> RunRepository.put
-> 创建后台 run_agent task
RunManager.create_or_reject 先在 Python 进程内的全局 manager lock 下扫描 _runs.values(),检查同 thread、同模型以及同用户模型并发。该步骤不是 SQL。
然后持久化 run:
INSERT INTO runs (
run_id,
thread_id,
assistant_id,
user_id,
status,
model_name,
multitask_strategy,
metadata_json,
kwargs_json,
error,
follow_up_to_run_id,
created_at,
updated_at,
...
)
VALUES (...);
随后会查询或更新 threads_meta,再启动后台 agent。Gateway 在慢路径输出:
[start-run-timing] thread=... total=...s enforce_access=...s run_create=...s thread_upsert=...s build_payload=...s
其中 run_create 包含:
- 进程内
_runs扫描; INSERT INTO runs;- 数据库 COMMIT。
4.3 graph 执行期间
LangGraph 会反复调用:
INSERT INTO checkpoint_blobs (...)
VALUES (...)
ON CONFLICT (thread_id, checkpoint_ns, channel, version)
DO NOTHING;
INSERT INTO checkpoints (...)
VALUES (...)
ON CONFLICT (thread_id, checkpoint_ns, checkpoint_id)
DO UPDATE SET checkpoint = EXCLUDED.checkpoint,
metadata = EXCLUDED.metadata;
INSERT INTO checkpoint_writes (...)
VALUES (...)
ON CONFLICT (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
DO UPDATE SET channel = EXCLUDED.channel,
type = EXCLUDED.type,
blob = EXCLUDED.blob;
因此 checkpoint 数据量一般会明显大于 runs 数量:一个 run 可以产生多个 checkpoint、blob 和 write。
4.4 回答正文结束到 SSE end
graph 流结束后,后端仍会执行终态检查与收尾:
-
第一次读取主 namespace 最新 checkpoint,用于确认 graph 已留下 terminal state:
SELECT ... FROM checkpoints WHERE thread_id = $1 AND checkpoint_ns = '' ORDER BY checkpoint_id DESC LIMIT 1; -
更新 run 状态:
UPDATE runs SET status = $2, updated_at = $3, error = COALESCE($4, error) WHERE run_id = $1; -
更新 run completion/token/message 统计,仍然是:
UPDATE runs SET ... WHERE run_id = $1; -
收尾阶段再次读取主 namespace 最新 checkpoint,用于同步标题和最终元数据。
-
更新
threads_meta状态/标题等信息。 -
最后发布 SSE
end。
两次 checkpoint 读取都会争用同一个 saver 实例锁。因此实际等待链可能是“正文已经生成 → terminal checkpoint 读取等锁 → completion 更新 → finalize checkpoint 读取再次等锁 → SSE end → 前端 /history 再次读 checkpoint”。
runs 的上述 UPDATE 按 run_id 主键定位。若该阶段慢,应该检查锁等待、连接池、事务提交和死元组,而不是仅凭总行数判断。
后端为终态收尾设置了 10 秒预算,相关日志包括:
RUN_COMPLETION_TIMEOUT run_id=... phase=terminal_checkpoint
RUN_COMPLETION_TIMEOUT run_id=... phase=terminal_status
RUN_COMPLETION_TIMEOUT run_id=... phase=metadata_cleanup
4.5 POST /api/threads/{thread_id}/history
路由当前构造的 config 只有 thread_id:
config = {"configurable": {"thread_id": thread_id}}
前端当前传 limit=1。saver 生成的核心 SQL 形态为:
SELECT
thread_id,
checkpoint,
checkpoint_ns,
checkpoint_id,
parent_checkpoint_id,
metadata,
(
SELECT array_agg(...)
FROM jsonb_each_text(checkpoint -> 'channel_versions')
JOIN checkpoint_blobs bl
ON bl.thread_id = checkpoints.thread_id
AND bl.checkpoint_ns = checkpoints.checkpoint_ns
AND bl.channel = jsonb_each_text.key
AND bl.version = jsonb_each_text.value
) AS channel_values,
(
SELECT array_agg(...)
FROM checkpoint_writes cw
WHERE cw.thread_id = checkpoints.thread_id
AND cw.checkpoint_ns = checkpoints.checkpoint_ns
AND cw.checkpoint_id = checkpoints.checkpoint_id
) AS pending_writes
FROM checkpoints
WHERE thread_id = $1
ORDER BY checkpoint_id DESC
LIMIT 1;
其中 blob/write 的相关子查询可以使用各自组合主键;最值得核对的是最外层 checkpoints 的跨 namespace 排序。
5. 为什么连接池最大 10 仍可能串行
当前 provider 创建:
AsyncConnectionPool(min_size=1, max_size=10)
-> 一个 AsyncPostgresSaver(pool)
-> 挂到 app.state,供所有 thread/run/history 共用
langgraph-checkpoint-postgres==3.1.2 的 _cursor() 关键实现是:
async with self.lock, get_connection(self.conn) as conn:
这意味着:
- saver 先拿实例锁,再去连接池 checkout;
- 同一个 saver 的所有 checkpoint 读写一次只能有一个进入
_cursor(); - 把
DEER_FLOW_PG_POOL_MAX从 10 调到更大,不能解除这个实例锁; - 等待 saver 锁的 coroutine 尚未进入 PostgreSQL,因此
pg_stat_activity可能只看到一个活动连接,看不到应用中其余等待者; alist()在 cursor context 内fetchall()后逐项yield,调用方处理 yielded tuple 时 generator 尚未退出,实例锁仍可能保持占用。
仓库已有 characterization test:
packages/harness/tests/test_thread_operation_timing.py:204-247
它验证了 pool 场景下第二个 saver cursor 会等待第一个 cursor 释放。
6. runs 5 万行到底会不会慢
6.1 数据库中的 5 万条 runs
正常创建/完成路径主要是:
INSERT INTO runs (...);
UPDATE runs SET ... WHERE run_id = $1;
run_id 是主键,5 万行对 PostgreSQL 很小。只要:
runs_pkey存在且有效;- 没有严重锁等待;
- 死元组和表/索引膨胀不严重;
- 数据库连接与存储 I/O 正常;
就不应仅因为 5 万行产生 6 秒延迟。
6.2 进程内 _runs 与数据库 runs 不是一回事
代码中存在一个独立问题:
RunManager.cleanup()能从_runs字典删除已结束记录;- 当前 worker finally 只调用
StreamBridge.cleanup(); - 全仓当前没有调用
run_manager.cleanup(...); - 因此同一个 Gateway 进程生命周期内完成的 run 会一直留在
_runs; - 每次
create_or_reject()会在 manager lock 内对_runs.values()做 1~3 次 O(N) 扫描。
数据库的 5 万条 runs 不会在启动时自动全部加载到 _runs。只有当当前进程自身长期运行并累计大量 run 时,这个问题才会放大。它是应该修复的增长性缺陷,但通常不是单独造成 6 秒的首要解释。
7. 一次完整的线上复现怎么采集
7.1 浏览器 Network
打开 DevTools → Network:
- 勾选
Preserve log。 - 过滤
threads。 - 从创建新对话开始完整复现一次。
- 记录以下请求:
| 阶段 | 请求 |
|---|---|
| 创建会话 | POST /api/threads |
| 问答流 | POST /api/threads/{thread_id}/runs/stream |
| 结束刷新 | POST /api/threads/{thread_id}/history |
记录:
thread_id:
run_id:
请求开始时间:
HTTP 状态:
Waiting/TTFB:
Content Download:
响应大小:
请求结束时间:
另外记录:
runs/stream最后一个可见正文 chunk 的时间;- SSE 真正结束时间;
/history开始和完成时间;- 页面退出“等待中”的时间;
POST /api/threads响应头中的Server-Timing。
导出 HAR 前删除 Authorization、Cookie、token 和业务正文。
7.2 POST /threads 的 Server-Timing
示例:
Server-Timing: metadata_lookup;dur=18.20, metadata_create;dur=25.10, checkpoint_create;dur=5880.30, handler_total;dur=5930.10
判断:
| 结果 | 优先结论 |
|---|---|
checkpoint_create 约等于总耗时 |
saver 锁等待、checkpointer 连接获取或 checkpoint PG 写入 |
metadata_lookup 慢 |
业务 PG 的 threads_meta 主键查询、连接池或锁 |
metadata_create 慢 |
业务 PG 插入/提交、索引维护或锁 |
所有 phase 很快但 handler_total 慢 |
phase 外逻辑或事件循环调度竞争 |
handler_total 很快但浏览器 TTFB 慢 |
鉴权、中间件、反向代理、进入 handler 前排队 |
没有 Server-Timing |
线上版本不包含该诊断,或请求没有进入预期 route |
checkpoint_create 包含 saver lock 和 pool 等待,不只是 SQL 执行时间。
7.3 Gateway 日志
本地脚本部署:
rg -n "GATEWAY_OPERATION_TIMING|start-run-timing|RUN_COMPLETION_TIMEOUT|completion metadata exceeded|Failed to finalize run|Checkpointer|pool timeout|OperationalError" .runtime/logs
容器部署:
docker logs --since 15m <gateway-container> 2>&1 \
| rg "GATEWAY_OPERATION_TIMING|start-run-timing|RUN_COMPLETION_TIMEOUT|completion metadata exceeded|Failed to finalize run|Checkpointer|pool timeout|OperationalError"
将同一个 thread_id、run_id 整理成时间线:
T0 POST /threads 开始
T1 thread_create 分阶段日志
T2 run 开始
T3 最后正文事件
T4 run 标记 success/error
T5 SSE end
T6 /history 开始
T7 /history 完成
T8 UI 退出等待
8. PostgreSQL 只读排查 SQL
以下查询默认当前连接就是目标数据库。若应用使用非 public schema,先确认实际 schema,再修改后续 SQL。<THREAD_ID> 和 <RUN_ID> 必须替换成真实值。
8.1 确认 schema、版本和现有索引
SELECT current_database(), current_schema(), current_schemas(true);
SELECT max(v) AS checkpoint_schema_version
FROM checkpoint_migrations;
SELECT
schemaname,
tablename,
indexname,
indexdef
FROM pg_indexes
WHERE tablename IN (
'runs',
'threads_meta',
'checkpoints',
'checkpoint_blobs',
'checkpoint_writes'
)
ORDER BY tablename, indexname;
langgraph-checkpoint-postgres 3.1.2 正常 setup 应包含三张 checkpoint 表的组合主键以及:
checkpoints_thread_id_idx
checkpoint_blobs_thread_id_idx
checkpoint_writes_thread_id_idx
不要因为模型代码声明了索引就假设生产库一定存在,最终以 pg_indexes/pg_index 为准。
确认索引是否 valid/ready:
SELECT
n.nspname AS schema_name,
t.relname AS table_name,
i.relname AS index_name,
x.indisvalid,
x.indisready,
pg_get_indexdef(i.oid) AS indexdef
FROM pg_class t
JOIN pg_namespace n ON n.oid = t.relnamespace
JOIN pg_index x ON x.indrelid = t.oid
JOIN pg_class i ON i.oid = x.indexrelid
WHERE t.relname IN (
'runs',
'threads_meta',
'checkpoints',
'checkpoint_blobs',
'checkpoint_writes'
)
ORDER BY t.relname, i.relname;
8.2 表规模、死元组和维护情况
SELECT
schemaname,
relname,
n_live_tup,
n_dead_tup,
round(
100.0 * n_dead_tup /
greatest(n_live_tup + n_dead_tup, 1),
2
) AS dead_pct,
last_vacuum,
last_autovacuum,
last_analyze,
last_autoanalyze
FROM pg_stat_user_tables
WHERE relname IN (
'runs',
'threads_meta',
'checkpoints',
'checkpoint_blobs',
'checkpoint_writes'
)
ORDER BY relname;
SELECT
schemaname,
relname,
pg_size_pretty(
pg_total_relation_size(
format('%I.%I', schemaname, relname)::regclass
)
) AS total_size
FROM pg_stat_user_tables
WHERE relname IN (
'runs',
'threads_meta',
'checkpoints',
'checkpoint_blobs',
'checkpoint_writes'
)
ORDER BY pg_total_relation_size(
format('%I.%I', schemaname, relname)::regclass
) DESC;
统计值是估算值,足以用于判断规模和维护异常;不必先执行昂贵的全表 count(*)。
8.3 故障 thread 的 checkpoint 分布
SELECT
checkpoint_ns,
count(*) AS checkpoint_rows,
min(checkpoint_id) AS oldest_checkpoint_id,
max(checkpoint_id) AS newest_checkpoint_id
FROM checkpoints
WHERE thread_id = '<THREAD_ID>'
GROUP BY checkpoint_ns
ORDER BY checkpoint_rows DESC;
如果单个 thread 有大量 checkpoint 或多个 namespace,当前 /history 的跨 namespace 排序更值得关注。
8.4 对比 History 与主 namespace 的执行计划
只对一个已知慢 thread 在低峰执行:
EXPLAIN (ANALYZE, BUFFERS, SETTINGS)
SELECT checkpoint_id, checkpoint_ns
FROM checkpoints
WHERE thread_id = '<THREAD_ID>'
ORDER BY checkpoint_id DESC
LIMIT 1;
对比限定主 namespace:
EXPLAIN (ANALYZE, BUFFERS, SETTINGS)
SELECT checkpoint_id, checkpoint_ns
FROM checkpoints
WHERE thread_id = '<THREAD_ID>'
AND checkpoint_ns = ''
ORDER BY checkpoint_id DESC
LIMIT 1;
重点看:
- 第一条是否出现
Sort/top-N heapsort; Rows Removed by Filter;- 实际扫描行数;
- shared buffer read/hit;
- 第二条是否使用
checkpoints_pkey的 backward index scan; - 两条的实际耗时差异。
EXPLAIN ANALYZE 会真实执行 SELECT。这里的 SELECT 是只读的,但仍应对一个明确 thread 在低峰执行,不要直接对完整大型历史查询做无界分析。
8.5 验证 runs 的关键查询
按 run id:
EXPLAIN (ANALYZE, BUFFERS)
SELECT run_id, status
FROM runs
WHERE run_id = '<RUN_ID>';
预期使用 runs_pkey。
按 thread 列表:
EXPLAIN (ANALYZE, BUFFERS)
SELECT run_id, status, created_at
FROM runs
WHERE thread_id = '<THREAD_ID>'
ORDER BY created_at DESC
LIMIT 100;
预期使用 (thread_id, created_at) 组合索引,例如 ORM 当前声明的 ix_runs_thread_created。如果生产库没有该索引,先核对部署 migration/自动补列逻辑,再决定是否补建;不要建立重复索引。
8.6 卡顿正在发生时查看 PostgreSQL 活动
SELECT
pid,
application_name,
usename,
state,
wait_event_type,
wait_event,
xact_start,
query_start,
now() - query_start AS query_age,
pg_blocking_pids(pid) AS blocking_pids,
left(query, 500) AS query
FROM pg_stat_activity
WHERE datname = current_database()
AND pid <> pg_backend_pid()
AND (state <> 'idle' OR wait_event IS NOT NULL)
ORDER BY query_start;
阻塞关系:
SELECT
blocked.pid AS blocked_pid,
now() - blocked.query_start AS blocked_for,
blocked.wait_event_type,
blocked.wait_event,
left(blocked.query, 300) AS blocked_query,
blocker.pid AS blocker_pid,
blocker.state AS blocker_state,
now() - blocker.xact_start AS blocker_xact_age,
left(blocker.query, 300) AS blocker_query
FROM pg_stat_activity AS blocked
JOIN LATERAL unnest(pg_blocking_pids(blocked.pid)) AS b(pid) ON true
JOIN pg_stat_activity AS blocker ON blocker.pid = b.pid
ORDER BY blocked.query_start;
注意:如果请求在 Python saver lock 上等待,它还没有 checkout PostgreSQL 连接,因此 PostgreSQL 里可能看不到对应 blocked session。
8.7 如果启用了 pg_stat_statements
先确认扩展:
SELECT extname, extversion
FROM pg_extension
WHERE extname = 'pg_stat_statements';
checkpoint 查询:
SELECT
calls,
round(mean_exec_time::numeric, 2) AS mean_ms,
round(max_exec_time::numeric, 2) AS max_ms,
rows,
shared_blks_hit,
shared_blks_read,
temp_blks_written,
left(query, 700) AS query
FROM pg_stat_statements
WHERE dbid = (
SELECT oid
FROM pg_database
WHERE datname = current_database()
)
AND query ILIKE '%checkpoints%'
ORDER BY max_exec_time DESC
LIMIT 30;
runs 查询:
SELECT
calls,
round(mean_exec_time::numeric, 2) AS mean_ms,
round(max_exec_time::numeric, 2) AS max_ms,
rows,
shared_blks_hit,
shared_blks_read,
temp_blks_written,
left(query, 700) AS query
FROM pg_stat_statements
WHERE dbid = (
SELECT oid
FROM pg_database
WHERE datname = current_database()
)
AND query ILIKE '%runs%'
ORDER BY max_exec_time DESC
LIMIT 30;
9. 证据如何判定
| 现场证据 | 结论/下一步 |
|---|---|
/threads 的 checkpoint_create 接近 6 秒 |
优先排查 saver 锁排队或 checkpoint PG 写入 |
checkpoint_create 很慢,但 pg_stat_activity 没有相应慢 SQL/锁 |
强烈支持请求仍在进程内 saver lock 上排队 |
| History EXPLAIN 出现大量候选扫描 + Sort | 为 (thread_id, checkpoint_id DESC) 建候选索引,或让接口限定 checkpoint_ns='' |
| History SQL 自身毫秒级,但接口仍数秒 | 重点查 saver lock wait、反序列化、消息序列化和事件循环阻塞 |
最后正文已到但 SSE 未结束,日志出现 terminal_checkpoint |
run 收尾在 checkpoint 读取处等待 |
日志出现 terminal_status |
runs 终态 UPDATE/COMMIT、业务 PG 连接或锁等待 |
日志出现 metadata_cleanup |
journal、completion、标题或 thread 元数据收尾超时 |
SSE 已结束,只有 /history pending |
SDK 结束后 history 刷新卡住,不是模型还在生成 |
/history 已 200,页面仍 loading |
再查前端构建版本、状态恢复和渲染逻辑 |
runs_pkey 命中,dead tuples 低,无 DB wait |
5 万 runs 不是该故障的主要原因 |
runs dead tuples 高、autovacuum 长期不工作 |
可能拖慢 UPDATE/COMMIT,但仍不能解释 /history 路径 |
PG 出现 wait_event_type='Lock' 和 blocking pid |
已确认数据库锁等待,先处理 blocker |
| PG 出现明显 I/O wait 或大量 shared reads | 检查存储、缓存命中、膨胀及查询计划 |
| checkpoint migration 或必要索引缺失/invalid | 修复 schema/setup,再评估应用层锁 |
10. 不建议直接做的操作
- 不要因为有 5 万条 runs 就直接删除 runs。
- 不要在生产直接执行
VACUUM FULL,它会对表获取强锁。 - 不要先增加大量重复索引;每个索引都会增加 checkpoint 写放大。
- 不要只增大
DEER_FLOW_PG_POOL_MAX;单 saver 的实例锁仍会串行。 - 不要通过增加 Gateway worker 临时绕过;当前 run registry 与 SSE bridge 是进程内状态。
- 不要在未确认 history namespace 语义前直接把所有查询改成
checkpoint_ns=''。 - 不要把 checkpoint 归档作为本次 6 秒问题的第一步;归档涉及停写、备份、恢复演练,并不能消除 saver 实例锁。
11. 单次事故记录模板
部署 commit:
前端构建版本:
Gateway worker:
database backend/host/db:
checkpointer backend/host/db:
发生时间:
thread_id:
run_id:
POST /threads:
- 浏览器总耗时:
- Server-Timing:
- HTTP 状态:
runs/stream:
- 开始时间:
- 最后正文时间:
- SSE end 时间:
- 是否收到 end:
history:
- 开始时间:
- TTFB:
- 完成/取消时间:
- HTTP 状态:
- 响应大小:
Gateway 日志:
- GATEWAY_OPERATION_TIMING:
- start-run-timing:
- RUN_COMPLETION_TIMEOUT:
- pool/DB 异常:
PostgreSQL:
- activity/wait_event:
- blocking_pids:
- checkpoint migration:
- 索引缺失/invalid:
- live/dead tuples:
- History EXPLAIN:
初步判定:
已经排除:
尚缺证据:
下一步:
12. 关键代码位置
| 位置 | 内容 |
|---|---|
offline-backend-20260512/backend/app/gateway/routers/threads.py:853-927 |
创建 thread、分阶段计时、同步写初始 checkpoint |
offline-backend-20260512/backend/app/gateway/routers/threads.py:1873-1944 |
History config、alist 和消息序列化 |
offline-backend-20260512/backend/app/gateway/operation_timing.py:14-60 |
Server-Timing 和 GATEWAY_OPERATION_TIMING |
offline-backend-20260512/backend/app/gateway/routers/thread_runs.py:98-133 |
run 创建与 SSE 路由 |
offline-backend-20260512/backend/app/gateway/services.py:1374-1976 |
start_run 和 [start-run-timing] |
offline-backend-20260512/backend/packages/harness/deerflow/persistence/run/sql.py:66-206 |
runs INSERT/UPDATE |
offline-backend-20260512/backend/packages/harness/deerflow/persistence/run/model.py:14-56 |
runs 主键和 ORM 索引声明 |
offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/manager.py:211-324 |
_runs 扫描与未被调用的 cleanup |
offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/worker.py:479-501 |
run 收尾后仅清理 stream bridge |
offline-backend-20260512/backend/packages/harness/deerflow/runtime/checkpointer/async_provider.py:93-123 |
PG pool 与单 saver |
.venv/Lib/site-packages/langgraph/checkpoint/postgres/base.py:43-150 |
checkpoint schema、索引和 SQL |
.venv/Lib/site-packages/langgraph/checkpoint/postgres/aio.py:119-179 |
alist 查询、fetchall 与持锁 yield |
.venv/Lib/site-packages/langgraph/checkpoint/postgres/aio.py:363-403 |
saver 实例锁先于 pool checkout |
frontend-web/src/core/threads/hooks.ts:702-711 |
fetchStateHistory: { limit: 1 } |
frontend-web/src/core/threads/hooks.ts:976-1038 |
onFinish 依赖最终 state |
frontend-web/src/core/api/api-client.ts:96-101 |
控制/history 请求 30 秒超时 |
13. 推荐排查顺序
按下面顺序执行,通常一次复现就能缩小范围:
- 浏览器保存
/threads、runs/stream、history时间线。 - 查看
/threads的Server-Timing。 - 用同一
thread_id/run_id对齐 Gateway 日志。 - 卡顿发生时立即保存
pg_stat_activity和 blocker 快照。 - 查询实际索引与表统计,不依赖代码声明猜测生产 schema。
- 对慢 thread 比较两条 History EXPLAIN。
- 只有证据显示查询计划问题时才加索引;只有 SQL 已很快而接口仍等待时,才优先改 saver/应用锁路径。