wal模式通过写前日志实现读写并发，避免sqlite全局锁；需配套设置synchronous=normal、cache_size=10000、busy_timeout=5000，并确保checkpoint机制运行。
为什么 WAL 模式能缓解宝塔面板的 SQLite 锁竞争
宝塔面板的 default.db 在高并发访问（如同时打开多个站点配置页、批量操作插件、频繁调用 API）时，容易触发 SQLite 的“database is locked”错误。这是因为默认的 DELETE 日志模式下，任意写操作都会对整个数据库加独占锁，读操作必须排队等待——哪怕只是查一条配置项，也得等上一个 UPDATE config 完成。WAL（Write-Ahead Logging）模式把写操作先记入日志文件（default.db-wal），读操作可直接从主数据库文件读取旧快照，实现真正的读写并发。
如何安全启用 WAL 模式（不重启面板也能生效）
WAL 模式是运行时 PRAGMA 设置，修改后立即生效，但需确保所有连接都使用相同模式，否则会回退到默认行为。操作前必须备份：
cp /www/server/panel/data/default.db /www/server/panel/data/default.db.bak_$(date +%s)- 确认 sqlite3 已安装：
sqlite3 --version，未安装则按系统执行：yum install sqlite3 -y或apt install sqlite3 -y - 进入目录并启用 WAL：
cd /www/server/panel/data && sqlite3 default.db "PRAGMA journal_mode = WAL;" - 验证是否成功：
sqlite3 default.db "PRAGMA journal_mode;"，返回值必须是wal，不是delete或空
注意：WAL 模式启用后，会生成 default.db-wal 和 default.db-shm 两个辅助文件，它们必须与 default.db 在同一目录且有相同权限，否则面板后续写入会失败。
WAL 模式下必须同步调整的三个关键 PRAGMA 参数
只开 WAL 不调参数，可能反而加剧卡顿。尤其在低配服务器（1–2 核 + 2GB 内存）上，以下三项必须配套设置：
-
synchronous = NORMAL：WAL 模式下设为NORMAL可避免每次写都强制刷盘，显著提升写吞吐；设为FULL（默认）会抵消 WAL 大部分优势 -
cache_size = 10000：增大内存缓存页数（单位：页，默认 2KB/页），减少磁盘 I/O；低于 5000 时高并发下易频繁换页 -
busy_timeout = 5000：将锁等待超时从默认的 0ms 提升至 5000ms，给 WAL 后台检查点留出时间，避免瞬间报错
建议用 Python 脚本一次性执行（防止漏项）：python3 -c "import sqlite3; c=sqlite3.connect('/www/server/panel/data/default.db'); c.execute('PRAGMA journal_mode=WAL'); c.execute('PRAGMA synchronous=NORMAL'); c.execute('PRAGMA cache_size=10000'); c.execute('PRAGMA busy_timeout=5000'); c.commit(); c.close()"
WAL 模式启用后仍出现 locked 错误？检查这三点
WAL 不是银弹，以下情况会导致它失效或退化：
- 面板进程未完全关闭就改 PRAGMA：执行
bt restart是必须的，否则旧连接仍用 DELETE 模式持有锁 -
default.db-wal文件被误删或权限异常：检查ls -l /www/server/panel/data/default.db*，三个文件 uid/gid 必须一致，且非 root 用户不可写（否则面板服务无法更新） - 长时间未触发 checkpoint：WAL 文件会持续增长，最终阻塞写入。宝塔自身不主动做 checkpoint，需依赖系统定期执行
sqlite3 default.db "PRAGMA wal_checkpoint(TRUNCATE);"，建议加到每日计划任务中
最常被忽略的是 checkpoint —— WAL 文件一旦超过 100MB，面板操作就会明显变慢，但错误日志里不会直接提示，只会表现为随机 database is locked 或页面加载超时。
