当多台 Linux 主机通过网络文件系统(NFS)共享 Codex 主目录(默认为 ~/.codex)时,如果它们同时以预写日志(WAL)模式打开同一个 SQLite 数据库,就可能损坏该数据库。如果要使用 CLI 或通过 SSH 连接的 Codex App 开展交互式工作,请先迁移共享主目录。如果要运行独立的批处理作业,请将每台主机的 Codex 主目录或 SQLite 目录放在各自的本地磁盘上。
为什么在 NFS 上使用 SQLite 可能会损坏数据库
Codex App 和终端界面使用 SQLite 索引列出对话。这些数据库还存储目标和记忆处理状态。在本地磁盘上,Codex 通常使用 WAL 模式。不同主机上的进程无法共享 WAL 所需的内存。
当 Codex 在 Linux 上检测到 NFS 时,它会以回滚日志模式(DELETE)创建数据库。该模式使用文件锁。在另一台主机上打开现有的 WAL 数据库之前,请先迁移这些数据库。
Codex 还会将对话事件保存在 rollout-*.jsonl 文件中。每个文件在同一时间只有一个进程写入,因此这些文件可以直接存放在 NFS 上。迁移 SQLite 时,这些文件会保留在原处。
迁移现有的 NFS 主目录
1. 检查共享主目录
在每台主机(包括所有 SSH 后端主机)上运行 codex --version。使用包含 codex migrate-nfs-db 命令的版本,例如 Codex CLI 0.166.0。确认使用此共享主目录的所有主机都使用同一个 SQLite 目录。请存储管理员验证,当一台主机持有文件锁时,另一台主机无法获得与之冲突的锁。如果该挂载点无法保证这一点,请将 SQLite 数据库保留在本地磁盘上。
迁移期间,请勿设置或更改 SQLite 主目录或日志目录。
2. 在每台主机上停止 Codex
结束正在进行的对话轮次,关闭应用和 CLI,并停止使用此主目录的远程应用服务器、后台守护进程和计划任务。在迁移完成之前,所有主机都应保持此状态。并发写入可能会损坏数据库,导致对目标或记忆的更改丢失。
会话记录保存在单独的文件中,仅凭这些文件无法恢复全部数据库状态。
在守护进程模式下,CLI 会连接到后台服务器,该服务器在会话结束后仍会继续运行。其 Unix 套接字仅在启动该服务器的主机上可用。当多台主机通过 NFS 共享 Codex 主目录时,建议在运行 CLI 时禁用守护进程。在每台运行了守护进程的主机上,使用 codex app-server daemon stop 将其停止。
为防止 CLI 再次启动守护进程,请将 daemon_auto_start 设为 false。此设置应位于 [features] 下,写入共享的 config.toml 文件。
[features]
daemon_auto_start = false
如果只想对单次 CLI 会话禁用守护进程,请传入 --no-daemon。即使守护进程已经在运行,使用此标志也会绕过它。
3. 执行迁移
对于每个共享的 Codex 主目录,只在一台 Linux 主机上执行迁移。使用主目录所有者的账户及其平时使用的配置。在迁移完成之前,请让其他主机上的 Codex 保持停止状态。
codex migrate-nfs-db
4. 继续对话
如果命令输出 Skipped logs database,请检查日志数据库的位置。如果它位于本地磁盘上,无需进一步操作。如果它位于 NFS 上,请先确认它使用 DELETE 日志模式,或将其移至本地磁盘,然后再在另一台主机上重新打开 Codex。
迁移成功后,以同一用户身份在另一台主机上打开同一个项目。在应用中继续一段您熟悉的对话,或运行 codex --no-daemon resume。确认您能看到上次对话的最后一轮,并且可以继续对话。
将诊断日志移至本地磁盘
此步骤可选,建议在迁移后执行。 诊断日志有助于排查错误和启动缓慢的问题。将诊断日志写入本地磁盘可以减少 NFS 流量。
在每台主机上创建一个用户私有且可写的日志目录。将 log_dir 写入用户的 config.toml,其值为该用户日志目录的绝对路径。例如,Alice 可以使用以下设置。
log_dir = "/var/local/codex/alice/logs"
新日志将写入该目录,旧日志保留在原处。
如果 sqlite_home 由管理员统一配置,即使设置了 log_dir,SQLite 日志数据库也会保存在规定的目录中。请参阅托管配置。
在多台主机上强制使用指定的日志模式
首先,在每台使用受影响主目录的主机上停止所有客户端。设置名称中包含 unsafe,是因为在另一台主机写入数据库时转换该数据库可能会导致数据库损坏。
停止所有客户端后,更新这些主机的托管配置,在 /etc/codex/requirements.toml 中添加以下设置。
unsafe_enforce_sqlite_journal_mode = true
此设置适用于已配置主机上的所有用户。用户下次打开 Codex 后,每当 Codex 为写入而打开 NFS 上现有的 WAL 数据库时,都会自动迁移该数据库。对于每个共享主目录,先等待一台主机完成迁移,再让其他主机重新连接。如果迁移失败,请让其他客户端保持停止状态,并按照恢复步骤操作。
运行独立的批处理作业
如果无人值守的作业不需要您的交互式会话历史记录,请运行 codex exec,并使用执行作业的主机本地磁盘上的 Codex 主目录。如果会话文件需要保留在 NFS 上,请为每个作业将 CODEX_SQLITE_HOME 设为各自私有的本地目录,以免多个工作进程争用同一个数据库。
- 保留对话记录。 为每个作业分配一个私有且可持久保存的
CODEX_HOME来存储会话记录,并在执行作业的主机上分配一个私有的本地CODEX_SQLITE_HOME来存储数据库。工作进程使用的索引与您的交互式会话索引相互独立。如果需要在工作进程退出后检查作业,请将会话记录保存在$CODEX_HOME/sessions/下。 - 仅保留结果。 将作业主目录放在本地磁盘上,并运行
codex exec --ephemeral。此命令会跳过保存可恢复会话的步骤。使用-o将最终回复写入可持久保存的文件,或使用--json将事件流式传输到作业运行器。
对于需要保留会话记录的作业,请让调度程序创建这两个目录,并为作业主目录准备身份验证信息和配置。将示例路径替换为该作业的持久化 Codex 主目录和执行主机上的本地 SQLite 目录。通过托管配置或其他配置设置的 sqlite_home 优先于 CODEX_SQLITE_HOME。
CODEX_HOME="/mnt/nfs/codex/jobs/job-1234" \
CODEX_SQLITE_HOME="/var/local/codex/jobs/job-1234" \
codex exec "概述这个代码仓库的构建步骤。"
常见问题
如何判断错误是否与 NFS 有关?
如果迁移时出现 cannot open source database exclusively 这样的错误,说明 Codex 无法锁定数据库。即使数据库位于本地磁盘上,其他客户端也可能导致此错误。在 Linux 上,将受影响数据库的路径作为参数,运行 findmnt -T "$DB_PATH"。如果输出显示 nfs 或 nfs4,请检查每台主机上是否有正在写入数据库的进程,并请存储管理员验证该挂载点的跨主机文件锁是否生效。停止仍在运行的客户端后再重试。
查看迁移输出时应注意什么?
对于每个数据库,Codex 会输出 Migrated database: 和 WAL backup:,或输出 Already in DELETE mode:。如果您依赖组权限或扩展访问规则,请在迁移完成后、重新打开客户端之前验证这些权限或规则。
如果之前已设置 log_dir,该命令会跳过日志数据库。在多台主机之间共享该数据库之前,请确认它使用 DELETE 模式,或将其保留在本地磁盘上。
如果看到 No databases found.,请检查主目录所有者实际使用的 SQLite 目录。如果本地暂存空间不足,请在当前主机上选择一个空间充足的本地目录,并通过 --staging-dir 传入其绝对路径。
迁移失败后如何恢复?
让其他客户端保持停止状态。保存完整的错误原文、数据库路径以及命令输出的备份路径。部分数据库可能已经完成迁移。请将原始数据库及其附属文件一起保留在对应的备份目录中。解决文件锁或空间不足的问题后,在同一台主机上重新运行 codex migrate-nfs-db。如果出现完整性错误或缺少用于替换原数据库的文件,请先在副本上处理问题,再执行任何还原操作。会话记录文件可以帮助重建对话历史。要恢复仅存储在 SQLite 中的状态(包括目标),必须使用完整无损的数据库。
在启动单独的 CLI 会话之前,请确认托管存储设置不会将写入操作重定向到受影响的主目录。然后,使用本地磁盘上的临时目录启动 Codex。使用新主目录时可能需要登录。
recovery_home=$(mktemp -d /tmp/codex-nfs-recovery.XXXXXXXX) &&
CODEX_HOME="$recovery_home" CODEX_SQLITE_HOME="$recovery_home" \
codex --no-daemon --sandbox read-only \
"帮我恢复受 Codex NFS 迁移失败影响的数据库。运行 `$ codex doctor` 查看受损数据库的信息。每个数据库的备份路径应为原数据库文件路径加上 `_wal_migration_backup` 后缀。请用户提供迁移失败时的错误原文。制定一份仅使用副本的恢复计划,不要改动原始文件。"