Files
deerflow-code/docs/线程创建与History等待慢-排查手册.md
T

28 KiB
Raw Blame History

Thread 创建慢与回答结束后 History 等待:完整排查手册

日期:2026-10-22 适用范围:DeerFlow Gateway、LangGraph useStream、PostgreSQL 业务库与 PostgreSQL checkpointer。

1. 先说结论

当前代码证据表明:

  1. POST /api/threads 不查询 runs 表。它查询/写入 threads_meta,然后同步写入一个空 checkpoint。

  2. 创建 run 时,持久化层主要执行 INSERT INTO runs (...);run 结束时主要执行 UPDATE runs ... WHERE run_id = ?。run_id 是主键,runs 有 5 万行本身通常不足以造成 6 秒延迟。

  3. 回答流结束后出现 POST /api/threads/{thread_id}/history 是前端 SDK 的正常行为。当前前端配置 fetchStateHistory: { limit: 1 },SDK 会等待这个请求完成后才结束 isLoading,因此会出现“回答文字已经显示完,但页面仍在等待中”。

  4. /history 实际查询 checkpoints、checkpoint_blobs、checkpoint_writes,不是查询 runs。

  5. 当前 /history 只传 thread_id,核心查询是:

    WHERE thread_id = $1
    ORDER BY checkpoint_id DESC
    LIMIT 1
    

    checkpoints 主键为 (thread_id, checkpoint_ns, checkpoint_id)。当不限定 checkpoint_ns 时,主键不能直接提供跨 namespace 的 checkpoint_id 顺序,可能需要扫描该 thread 的候选行并做 top-N Sort。

  6. 当前进程只创建一个全局 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:711
  • frontend-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 流结束后,后端仍会执行终态检查与收尾:

  1. 第一次读取主 namespace 最新 checkpoint,用于确认 graph 已留下 terminal state:

    SELECT ...
    FROM checkpoints
    WHERE thread_id = $1
      AND checkpoint_ns = ''
    ORDER BY checkpoint_id DESC
    LIMIT 1;
    
  2. 更新 run 状态:

    UPDATE runs
    SET status = $2,
        updated_at = $3,
        error = COALESCE($4, error)
    WHERE run_id = $1;
    
  3. 更新 run completion/token/message 统计,仍然是:

    UPDATE runs
    SET ...
    WHERE run_id = $1;
    
  4. 收尾阶段再次读取主 namespace 最新 checkpoint,用于同步标题和最终元数据。

  5. 更新 threads_meta 状态/标题等信息。

  6. 最后发布 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:

  1. 勾选 Preserve log。
  2. 过滤 threads。
  3. 从创建新对话开始完整复现一次。
  4. 记录以下请求:
阶段 请求
创建会话 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. 推荐排查顺序

按下面顺序执行,通常一次复现就能缩小范围:

  1. 浏览器保存 /threads、runs/stream、history 时间线。
  2. 查看 /threads 的 Server-Timing。
  3. 用同一 thread_id/run_id 对齐 Gateway 日志。
  4. 卡顿发生时立即保存 pg_stat_activity 和 blocker 快照。
  5. 查询实际索引与表统计,不依赖代码声明猜测生产 schema。
  6. 对慢 thread 比较两条 History EXPLAIN。
  7. 只有证据显示查询计划问题时才加索引;只有 SQL 已很快而接口仍等待时,才优先改 saver/应用锁路径。