使用 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-db4. 恢復對話
如果命令報告 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."