多部 Linux 主機透過網路檔案系統(NFS)共用 Codex 家目錄(預設為 ~/.codex)時,如果同時以預寫式日誌(WAL)模式開啟同一個 SQLite 資料庫,可能會造成資料庫損毀。若要使用 CLI 或透過 SSH 使用 Codex App 進行互動式工作,請先遷移共用家目錄。若要執行獨立的批次作業,請將各主機的 Codex 家目錄或 SQLite 目錄放在該主機的本機磁碟上。
為什麼在 NFS 上使用 SQLite 可能導致資料庫損毀
Codex App 和終端使用者介面都會使用 SQLite 索引來列出對話。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 資料庫保留在本機磁碟上。
遷移期間,請勿設定或變更 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 家目錄放在執行作業之主機的本機磁碟上,再執行 codex exec。如果工作階段檔案必須保留在 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` 後綴。請先請使用者提供原始錯誤訊息,再僅使用副本規劃復原步驟。請勿更動原始資料庫或其附屬檔案。"