SQLite WAL 导致 Codex 卡死？高效排查与修复指南

TL;DR

在上一次优化中，我们通过“预建缓存 + PowerShell 原生读取”将对话记录的加载时间从6秒压缩到88毫秒，效果显著。然而两周后，Codex桌面应用突然彻底卡死——点击任意历史对话即进入假死状态，不是响应慢，而是完全无响应。

此次故障的根因有两个，且更为隐蔽：

0. SQLite WAL日志膨胀：state_5.sqlite的WAL文件从0增长到4MB（数据库本身仅300KB），每次读取需扫描870页未合并日志；
1. 日志数据库失控：logs_2.sqlite膨胀至70MB，其中52%为TRACE级别日志。

解决方案是一套组合策略：一键启动器（启动即执行清理）+ Windows定时任务（每3小时自动维护）+ 增强版rh命令。

问题重现

上篇文章发布后，rh命令一直稳定运行——88毫秒内返回结果，毫无延迟，我甚至几乎忘记了桌面应用侧边栏那个“加载中…”的提示。

直到某天，Codex桌面应用突然完全卡死。注意，不是变慢——点击任何历史对话都会导致应用进入假死状态，任务管理器直接显示“无响应”。

关键线索：终端中的rh仍然在毫秒级正常输出。这说明数据本身并未损坏，问题出在应用层面的交互逻辑。

排查：三个SQLite文件的真相

Codex数据目录~/.codex中包含三个SQLite数据库文件：

state_5.sqlite 300KB ← 对话元数据（线程、标题、模型）
logs_2.sqlite 70MB ← 运行日志
goals_1.sqlite 24KB ← 目标任务

单独看这些大小似乎正常，直到我注意到同名的.sqlite-wal文件：

state_5.sqlite 300KB ← 数据库本体
state_5.sqlite-wal 4.1MB ← WAL日志！！！
state_5.sqlite-shm 32KB
logs_2.sqlite 70MB
logs_2.sqlite-wal 4.2MB ← 又一个4MB的WAL

WAL文件体积是数据库本体的13倍。这才是真正的元凶。

WAL是什么？为何会膨胀到这种程度？

SQLite默认采用WAL（Write-Ahead Log）模式。简而言之：写操作不会直接修改数据库文件，而是先写入WAL日志；读操作需要同时查询数据库和WAL，合并最新结果；当WAL积累到一定阈值时，才会触发checkpoint将日志合并回主数据库。

正常情况下，这一过程对用户完全透明。但Codex桌面应用在运行期间持续高频写入（记录日志、更新状态），而checkpoint频率跟不上写入速度，导致WAL像滚雪球一样越滚越大。

正常WAL：▏ 几KB，随时合并
Codex的WAL：████████████████ 4MB，870页待合并

每次切换对话，应用读取state_5.sqlite时，SQLite需要在870页WAL中逐页查找最新数据。870次磁盘IO，每次耗时数百毫秒——UI线程直接被阻塞，导致界面卡死。这才是问题的根本原因。

解决方案

1. 手动checkpoint：将WAL合并回数据库

import sqlite3
conn = sqlite3.connect("state_5.sqlite")
conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
conn.close()

效果立竿见影：

state_5.sqlite-wal: 4,140KB → 0KB
logs_2.sqlite-wal: 4,273KB → 0KB

但这只是临时缓解。Codex继续运行数小时后，WAL又会重新膨胀。

2. 日志数据库清理

logs_2.sqlite为什么高达70MB？分析日志级别分布即可看出端倪：

TRACE: 17,578条 (52.1%) ← 全是HTTP连接、文件监控、SSE流的冗余日志
INFO: 7,508条
DEBUG: 7,328条
WARN: 1,302条
ERROR: 33条

超过一半是TRACE日志，每次HTTP请求、每个文件变动都会记录一条。删除TRACE和DEBUG级别的日志后：

logs_2.sqlite: 70MB → ~15MB

3. 一键启动器：彻底告别手动操作

每次都手动执行checkpoint效率太低。我编写了启动器codex_launcher.ps1，每次双击它就会自动执行以下步骤：

0. 检查Codex是否已在运行
1. 对三个数据库执行WAL checkpoint
2. 当日志超过30MB时自动清理TRACE/DEBUG
3. 清理临时文件
4. 启动Codex桌面应用

将其放在桌面作为快捷方式，从此每次启动都能保持清爽状态。

4. Windows定时任务：无人值守自动维护

一个绕不开的问题：Codex运行期间数据库被锁定，无法进行清理。因此设置了一个Windows定时任务，每3小时自动执行一次——如果Codex恰好关闭，则立即清理；如果正在运行，则跳过，等待下一次触发。

schtasks /Create /TN "Codex DB Auto Cleanup" /SC DAILY /RI 180 /DU 24:00 /IT /F `
/TR "powershell -WindowStyle Hidden -File codex_cleanup.ps1"

5. 增强版rh：搜索 + 详情

原有的rh仅支持列表和查看详情。增强版新增了关键词搜索功能：

rh # 列表（88ms）
rh 赛博朋克 # 搜索标题含"赛博朋克"的对话
rh 019e6a94 # 查看指定对话详情
rh --rebuild # 强制刷新缓存

此外，现在rh可以被cmd和PowerShell同时识别，并已复制到PATH目录中。

完整文件清单

经验总结

这次排查让我对SQLite WAL有了更深刻的理解：

Codex的问题在于将大量TRACE日志和状态更新写入WAL，却不及时执行checkpoint。应用开发者应当降低日志级别，或定期主动触发checkpoint。

对于用户而言，上篇文章解决的是“慢”，这篇解决的是“死”。两者结合才是一个完整的优化方案：

终端浏览（快）← rh → 88ms → 上篇
应用不卡（稳）← cleanup + launcher → 本篇
自动维护（省心）← 定时任务 → 本篇

如果你也遇到过“以为修好了结果又崩了”的情况，不要急于否定之前的方案——先检查SQLite的WAL文件和日志数据库，这个坑比Python冷启动更深，也更隐蔽。

来源：互联网