Execute o Codex com um diretório pessoal em NFS
Configure um diretório pessoal partilhado do Codex para trabalho interativo em vários hosts Linux.
Quando hosts Linux partilham um diretório pessoal do Codex (~/.codex por predefinição) através de Network File System (NFS), podem corromper uma base de dados SQLite se a abrirem simultaneamente no modo write-ahead log (WAL). Para trabalho interativo na CLI ou na aplicação Codex através de SSH, migre o diretório pessoal partilhado. Para tarefas em lote independentes, mantenha o diretório pessoal do Codex ou o diretório SQLite de cada host no disco local.
Porque pode o NFS causar problemas no SQLite
A aplicação Codex e a interface de terminal utilizam um índice SQLite para listar conversas. As bases de dados também armazenam objetivos e o estado de processamento da memória. No disco local, o Codex utiliza normalmente o modo WAL. Os processos em hosts diferentes não conseguem partilhar a memória de que o WAL precisa.
Quando o Codex deteta NFS em Linux, cria bases de dados no modo rollback-journal (DELETE), que utiliza bloqueios de ficheiros. Migre as bases de dados WAL existentes antes de as abrir noutro host.
O Codex também guarda eventos de conversa em ficheiros rollout-*.jsonl. Estes já podem residir em NFS porque cada registo de execução é escrito por um único processo de cada vez. A migração do SQLite mantém esses ficheiros no mesmo local.
Migre um diretório pessoal existente em NFS
1. Verifique o diretório pessoal partilhado
Execute codex --version em cada host, incluindo qualquer backend SSH. Utilize uma compilação que inclua codex migrate-nfs-db, como o Codex CLI 0.166.0. Confirme que todos os hosts que utilizam este diretório pessoal partilhado utilizam o mesmo diretório SQLite. Peça ao administrador de armazenamento para verificar se um bloqueio de ficheiro mantido num host impede um bloqueio incompatível no outro. Mantenha o SQLite no disco local se o ponto de montagem não permitir este comportamento.
2. Pare o Codex em todos os hosts
No modo daemon, a CLI liga-se a um servidor em segundo plano que continua em execução entre sessões. O seu socket Unix funciona apenas no host que o iniciou. Recomendamos executar a CLI sem o daemon quando os hosts partilham um diretório pessoal do Codex através de NFS. Pare o daemon em cada host onde está em execução com codex app-server daemon stop.
Para impedir que a CLI o volte a iniciar, defina daemon_auto_start como false em [features] no seu config.toml partilhado.
[features]
daemon_auto_start = falsePara uma única sessão da CLI, passe --no-daemon. Esta opção também ignora um daemon que já esteja em execução.
3. Execute a migração
Execute a migração num único host Linux por diretório pessoal partilhado do Codex. Utilize a conta do proprietário do diretório pessoal e a configuração habitual. Mantenha o Codex parado nos outros hosts até a migração terminar.
codex migrate-nfs-db4. Retome uma conversa
Se o comando indicar Skipped logs database, verifique a sua localização. Uma base de dados de registos no disco local não exige mais nenhuma ação. Se estiver em NFS, confirme que utiliza o modo de journal DELETE ou mova-a para o disco local antes de voltar a abrir o Codex noutro host.
Após a migração ser concluída com êxito, abra o mesmo projeto noutro host como o mesmo utilizador. Retome uma conversa conhecida na aplicação ou execute codex --no-daemon resume. Verifique se o último turno está presente e se consegue continuar a conversa.
Mova os registos de diagnóstico para o disco local
Opcional, recomendado após a migração. Os registos de diagnóstico ajudam a investigar erros e arranques lentos. Gravá-los localmente reduz o tráfego em NFS.
Crie um diretório de registos privado e com permissões de escrita em cada host. Defina log_dir no config.toml do utilizador como o caminho absoluto para esse utilizador. Por exemplo, a Alice poderia utilizar esta definição.
log_dir = "/var/local/codex/alice/logs"Os novos registos são guardados nesse diretório. Os registos anteriores permanecem no mesmo local.
Imponha o modo de journal em toda uma frota
Primeiro, pare todos os clientes em cada host que utiliza um diretório pessoal afetado. A definição tem o nome unsafe porque converter uma base de dados enquanto outro host escreve nela pode corrompê-la.
Com os clientes parados, adicione esta definição à configuração gerida dos hosts em /etc/codex/requirements.toml.
unsafe_enforce_sqlite_journal_mode = trueA definição aplica-se a todos os utilizadores nos hosts configurados. Da próxima vez que um utilizador abrir o Codex, este migra automaticamente as bases de dados WAL existentes ao abri-las para escrita em NFS. Para cada diretório pessoal partilhado, deixe a migração terminar num host antes de voltar a ligar os outros hosts. Se a migração falhar, mantenha os outros clientes parados e siga os passos de recuperação.
Execute tarefas em lote independentes
Se uma tarefa não supervisionada não precisar do histórico das suas sessões interativas, execute codex exec com um diretório pessoal do Codex no disco local do executor. Se os ficheiros de sessão tiverem de permanecer em NFS, defina CODEX_SQLITE_HOME como um diretório local privado para cada tarefa, para que os executores não disputem a mesma base de dados.
- Mantenha um registo da conversa. Atribua a cada tarefa um
CODEX_HOMEprivado e persistente para o seu registo de execução e umCODEX_SQLITE_HOMEprivado e local ao host para a sua base de dados. O índice do executor é separado do seu índice interativo. Mantenha o registo de execução em$CODEX_HOME/sessions/se precisar de inspecionar a tarefa após o executor terminar. - Mantenha apenas o resultado. Coloque o diretório pessoal da tarefa no disco local e execute
codex exec --ephemeral. Isto evita guardar uma sessão que possa ser retomada. Utilize-opara escrever a resposta final num ficheiro persistente ou--jsonpara transmitir eventos ao seu executor de tarefas.
Para uma tarefa que precisa de um registo de execução, configure o agendador para criar ambos os diretórios e fornecer autenticação e configuração para o diretório pessoal da tarefa. Substitua os caminhos de exemplo pelo diretório pessoal persistente do Codex desta tarefa e pelo diretório SQLite local ao executor. Uma definição gerida ou configurada de sqlite_home tem precedência sobre 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."Perguntas frequentes
Como posso saber se um erro está relacionado com NFS?
Um erro de migração como cannot open source database exclusively significa que o Codex não conseguiu bloquear a base de dados. Outro cliente também pode causar este problema no disco local. Em Linux, execute findmnt -T "$DB_PATH" com o caminho da base de dados afetada. Se indicar nfs ou nfs4, procure processos de escrita em todos os hosts e peça ao administrador de armazenamento para verificar os bloqueios entre hosts nesse ponto de montagem. Pare os clientes restantes antes de voltar a tentar.
O que devo procurar na saída da migração?
Para cada base de dados, o Codex apresenta Migrated database: e WAL backup:, ou Already in DELETE mode:. Se depender de permissões de grupo ou de regras de acesso alargadas, verifique-as após a migração e antes de voltar a abrir os clientes.
Se log_dir já estiver definido, o comando ignora a base de dados de registos. Antes de partilhar essa base de dados entre hosts, certifique-se de que utiliza DELETE ou mantenha-a no disco local.
Se vir No databases found., verifique o diretório SQLite efetivo do utilizador proprietário do diretório pessoal. Se o espaço local para preparação for insuficiente, escolha um diretório local ao host com espaço suficiente e passe o respetivo caminho absoluto com --staging-dir.
Como recupero após uma migração falhada?
Mantenha os outros clientes parados. Guarde o erro exato, o caminho da base de dados e o caminho da cópia de segurança apresentado. Algumas bases de dados podem já ter sido migradas. Mantenha a base de dados original e os respetivos ficheiros auxiliares juntos no diretório de cópia de segurança. Depois de resolver um erro de bloqueio ou de espaço, volte a executar codex migrate-nfs-db no mesmo host. No caso de um erro de integridade ou de uma substituição em falta, trabalhe a partir de cópias antes de restaurar qualquer elemento. Os registos de execução das sessões podem ajudar a reconstruir o histórico de conversas. Recuperar o estado que existe apenas no SQLite, incluindo objetivos, exige uma base de dados intacta.
Antes de iniciar uma sessão separada da CLI, confirme que as definições de armazenamento geridas não irão redirecionar as escritas para o diretório pessoal afetado. Em seguida, inicie o Codex utilizando um diretório temporário no disco local. O novo diretório pessoal poderá exigir o início de sessão.
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."