从写代码,到创作下一幕

探索 字节跳动 - 火山方舟 的 AI 编程与视频创作活动。

Agent Plan & Coding Plan

一站体验多款热门模型,为 AI 编程与智能体开发提供更多选择。新用户可联系(微信: goo_lvyouyou)免费体验 9.9 agent plan。

Seedance 2.5

让创意,跃然成片。探索 30 秒视频、多模态参考与局部编辑,把脑海中的画面变成下一支作品。

中文

使用 NFS 主目录运行 Codex

配置共享的 Codex 主目录,以便在多台 Linux 主机之间开展交互式工作。

当多台 Linux 主机通过网络文件系统(NFS)共享一个 Codex 主目录(默认为 ~/.codex)时,如果它们同时以预写日志(WAL)模式打开 SQLite 数据库,就可能损坏数据库。对于在 CLI 或通过 SSH 使用的 Codex App中开展的交互式工作,请迁移共享主目录。对于独立批处理作业,请将每台主机的 Codex 主目录或 SQLite 目录保存在本地磁盘上。

NFS 为何会导致 SQLite 出现问题

Codex App 和终端 UI 使用 SQLite 索引列出对话。这些数据库还存储目标和记忆处理状态。在本地磁盘上,Codex 通常使用 WAL 模式。不同主机上的进程无法共享 WAL 所需的内存。

当 Codex 检测到 Linux NFS 时,会以回滚日志模式(DELETE)创建数据库,改用文件锁。在从另一台主机打开现有 WAL 数据库之前,请先迁移这些数据库。

Codex 还会将对话事件保存在 rollout-*.jsonl 文件中。这些文件本就可以存放在 NFS 上,因为每份会话记录在同一时间只有一个进程写入。迁移 SQLite 时,这些文件会保留在原处。

迁移现有 NFS 主目录

1. 检查共享主目录

在每台主机上运行 codex --version,包括所有 SSH 后端。请使用包含 codex migrate-nfs-db 的构建版本,例如 Codex CLI 0.166.0。确认使用此共享主目录的所有主机都使用同一个 SQLite 目录。请存储管理员验证:一台主机持有的文件锁是否会阻止另一台主机获取与之冲突的锁。如果该挂载无法做到这一点,请将 SQLite 保存在本地。

2. 停止每台主机上的 Codex

在守护进程模式下,CLI 会连接到一个在会话之间持续运行的后台服务器。它的 Unix 套接字仅在启动它的主机上有效。当多台主机通过 NFS 共享 Codex 主目录时,我们建议运行 CLI 时不使用守护进程。在每台运行守护进程的主机上,使用 codex app-server daemon stop 将其停止。

要防止 CLI 再次启动它,请在共享的 config.toml 中,将 [features] 下的 daemon_auto_start 设置为 false。

[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 流量。

在每台主机上创建一个私有且可写的日志目录。在用户的 config.toml 中,将 log_dir 设置为该用户所用目录的绝对路径。例如,Alice 可以使用以下设置。

log_dir = "/var/local/codex/alice/logs"

新日志会写入该目录。旧日志保留在原处。

在整个主机集群中强制使用日志模式

首先,停止所有使用受影响主目录的主机上的全部客户端。此设置名为 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 "Summarize this repository's build steps."

常见问题

如何判断错误是否与 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 \
    "Help me recover a failed Codex NFS migration, run `$ codex doctor` to get the information about corrupted databases. Backup paths for databases should be in the original database with `_wal_migration_backup` in the end of the file. Ask user for the original error. Plan a recovery using copies and leave the originals untouched."