Documentação
Configuração de tempo de execução
Escolha o processo, o diretório de dados, o tipo de credencial e as configurações de integração que realmente controlam cada tempo de execução.
Traduzido automaticamente do inglês. Ver o original em inglês
Proprietários de configuração
O sidecar lê a configuração do ambiente por meio de AppConfigService em apps/sidecar/src/config.ts. Uma camada lê esses valores quando é construída e passa um valor AppConfig para os serviços que precisam dele. Alterar uma variável de shell pai não altera um serviço já em execução.
Tauri fornece seu próprio token de inicialização e caminhos de dados/migração de aplicativo ao iniciar o filho. A visualização do navegador usa variáveis de conexão do lado do Vite. Mobile armazena uma conexão de desktop emparelhada e credenciais de dispositivo. O site de documentação possui ligações de Worker separadas e um processo Studio local independente. Eles não compartilham um arquivo de configuração universal.
Configure o proprietário do comportamento que você pretende alterar. Por exemplo, definir o URL de migração CLI não redireciona o banco de dados de desktop nativo e configurar o assistente de documentação não fornece as credenciais do provedor de IA de desktop.
Inicie um sidecar isolado
CADCAMFUN_TOKEN=local-development-token \
CADCAMFUN_DATA_DIR=/tmp/cadcamfun-config-example \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct \
CADCAMFUN_AI_OFFLINE=1 \
bun --no-env-file apps/sidecar/src/main.tsIsso usa um diretório descartável e um token de desenvolvimento de exemplo. Escolha um token apropriado para o seu próprio processo. O servidor vincula o loopback em uma porta atribuída; leia essa porta de seu evento pronto. Mantenha o stdin aberto porque fechá-lo sinaliza o desligamento. O comando passa deliberadamente as configurações explicitamente e desativa o carregamento automático de arquivos de ambiente do Bun.
Para o loop nativo normal, use bun run desktop:dev. Ele prepara o binário sidecar e as migrações antes de lançar o Tauri, que possui a conexão do processo resultante. Não inicie um segundo sidecar manual e presuma que o webview nativo será anexado a ele.
Configurações necessárias de conexão e armazenamento
| Contexto | Padrão | Comportamento |
|---|---|---|
CADCAMFUN_TOKEN | Obrigatório | Credencial de portador de aplicativo editada para rotas de API locais protegidas. |
CADCAMFUN_DATA_DIR | Obrigatório | Raiz do estado local gerenciado por sidecar. O banco de dados é cadcamfun.db abaixo dele. |
CADCAMFUN_MIGRATIONS_DIR | Ausente | Diretório de migração passado para a camada de banco de dados. Sem ele, a abertura do banco de dados não cria nem atualiza tabelas de aplicativos. |
CADCAMFUN_APP_URL | Ausente na configuração | URL base fornecido para integrações de links de contas. O serviço relevante decide seu substituto. |
CADCAMFUN_DEBUG_LINKS | Falso | Ativa campos de resposta de desenvolvimento para links de contas em manipuladores que os suportam. |
O diretório de dados é uma raiz de armazenamento, não um endereço de ligação HTTP. O ouvinte do servidor principal está fixo em 127.0.0.1 com uma porta efêmera. A rede complementar usa seu próprio gateway HTTPS explicitamente habilitado; alterar uma configuração de URL não torna o ouvinte de loopback público.
Mantenha o diretório de migração configurado alinhado com o binário. A inicialização pode falhar antes da prontidão quando uma migração não pode ser planejada, armazenada em backup ou aplicada. A referência do banco de dados explica o comportamento da transação e do backup; uma tabela ausente após a omissão das migrações é um problema de configuração, e não uma prova de que o projeto foi excluído.
O token do aplicativo é lido como um valor editado e nunca aparece nos logs de configuração. Cada configuração nesta página é lida uma vez, em apps/sidecar/src/config.ts; um valor alterado entra em vigor somente após a reinicialização do sidecar.
Host e conectividade de IA
| Contexto | Padrão | Comportamento |
|---|---|---|
CADCAMFUN_AI_HOST | nikcli | Selecione nikcli ou direct. O host direto não adiciona o loop de ferramentas persistente integrado e o agendador especializado. |
CADCAMFUN_AI_OFFLINE | Falso | Desativa o carregamento do catálogo do provedor de rede e o manipulador de pesquisa na Web ao vivo. Não é uma implementação de modelo local. |
CADCAMFUN_AI_MINIMAX_BASE_URL | Ausente | Substituição de endpoint aparado opcional para a configuração MiniMax incorporada. |
As chaves do provedor são gerenciadas pela API de credenciais e persistidas pelo serviço de IA em <dataDir>/ai/credentials.json. Eles não são fornecidos pela invenção de uma variável de ambiente não documentada para cada provedor. Use os pontos de extremidade de status do provedor/modelo para estabelecer o que está configurado e o Guia de IA para roteamento de modelo direto compatível.
O modo offline não transforma uma chamada do provedor de nuvem em uma resposta offline. Um modelo direto ou incorporado configurado ainda pode exigir a conexão do provedor para inferência. O produto local-first retém projetos locais sem uma conexão de modelo; essa propriedade de armazenamento é distinta da inferência de IA offline.
A política do operador é carregada de <dataDir>/ai/policy.json. O host incorporado isola seus próprios diretórios de trabalho/configuração abaixo do armazenamento de IA do aplicativo. Política, credenciais, contexto de sessão e cache de catálogo do provedor têm finalidades diferentes; copiar um arquivo não reconstrói todo o tempo de execução de uma conversa.
Integrações de conta e faturamento
| Contexto | Usar | Quando ausente |
|---|---|---|
STRIPE_SECRET_KEY | Autenticação API Stripe de saída. | A finalização da compra paga e a integração do portal de cobrança não estão disponíveis. |
STRIPE_WEBHOOK_SECRET | Verifique as cargas assinadas do webhook do Stripe. | O manipulador de webhook recusa a ingestão sem configuração de verificação. |
STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, STRIPE_PRICE_ENTERPRISE | IDs de preços para planos pagos. Valores em branco são ignorados. | Um mapeamento ausente não pode identificar um preço de checkout configurado para esse plano. |
CRON_SECRET | Credencial compartilhada adicional para manutenção do cron. | Nenhum segredo cron extra é exigido por esse guarda; a admissão ao portador do aplicativo ainda se aplica. |
ADMIN_EMAIL | Identidade do administrador usada pela política de conta/serviço. | O perfil da instalação local mantém o comportamento administrativo local implementado pelos seus serviços. |
Essas configurações configuram integrações; eles não estabelecem a existência de uma conta remota, preço, assinatura ou entrega de webhook. Verifique a falha real da operação e o status do serviço em execução. Não infira que a presença de uma tabela significa que o recurso hospedado relacionado está totalmente configurado.
A interface AppConfig também contém ganchos de injeção de teste, como uma fábrica de modelos de substituição e uma base de API Stripe. Elas não são variáveis de ambiente lidas por esta camada de configuração de produção. Mantenha os ganchos de teste fora das instruções de implantação, a menos que o host em execução os exponha explicitamente.
A rota de avaliação de faturamento começa em 14 dias PRO julgamento (TRIAL_DAYS em apps/sidecar/src/repos/billing-repo.ts, usado por http/billing.ts). Os planos disponíveis são FREE, BASIC, PRO, e ENTERPRISE; apenas os três planos pagos levam um STRIPE_PRICE_* contexto.
Registros e telemetria
OTEL_EXPORTER_OTLP_ENDPOINT ativa os exportadores de rastreamento, métrica e log OTLP/HTTP do sidecar. Sem um ponto final não em branco, esta camada de telemetria opcional é desativada. O código exportador constrói os pontos finais específicos do sinal; configure um coletor que suporte esses sinais.
O registro normal do sidecar é separado da exportação de telemetria. Stdout carrega o protocolo de prontidão/erro JSON consumido pelo shell, enquanto os logs são direcionados para stderr. Ao diagnosticar a inicialização, retenha o primeiro erro relevante e seu contexto de operação em vez de esperar que a janela do aplicativo contenha todos os detalhes da inicialização.
Não inclua tokens de inicialização, chaves de provedor, tokens de sessão ou arquivos de credenciais completos em pacotes de diagnóstico. Caminhos de origem, método/status, IDs de endpoint, IDs de projetos não secretos e a operação de banco de dados com falha geralmente fornecem um ponto de partida mais seguro e útil.
Configuração do cliente
Uma visualização da área de trabalho somente no navegador usa a API falsa na memória quando VITE_SIDECAR_URL está ausente. Para conectá-lo a um sidecar iniciado manualmente, defina esse URL e VITE_SIDECAR_TOKEN antes de iniciar o Vite. O caminho Tauri empacotado obtém sua conexão do shell.
VITE_SIDECAR_URL=http://127.0.0.1:READY_PORT \
VITE_SIDECAR_TOKEN=local-development-token \
bun run --filter @cadcamfun/desktop devSubstitua o espaço reservado da porta. As configurações do Vite pertencem ao processo de desenvolvimento de frontend; alterá-los não reinicia nem reconfigura o sidecar. O acesso ao navegador está sujeito à política de loopback/Tauri CORS do sidecar e à admissão normal do portador.
O emparelhamento móvel armazena seu endereço de desktop, impressão digital do certificado e token do dispositivo por meio do aplicativo móvel. Alterar o token de inicialização da área de trabalho não é uma maneira normal de emparelhar um telefone. Use o procedimento de emparelhamento e revogar dispositivos individuais quando necessário.
Seleção do caminho do banco de dados
| Processo | Regra de seleção |
|---|---|
| Sidecar de desktop nativo | Diretório de dados do aplicativo fornecido pelo Tauri, então cadcamfun.db. |
| Sidecar manual | CADCAMFUN_DATA_DIR/cadcamfun.db. |
| CLI de migração de banco de dados | DATABASE_URL, removendo uma inicial file:; caso contrário, relativo ao processo ./data/cadcamfun.db. |
Raiz db:migrate invólucro | Executa o script do pacote de banco de dados, para que o padrão seja resolvido dentro packages/db. |
| Estúdio de Documentação | CADCAMFUN_DB, então DATABASE_URL, então raiz do repositório data/cadcamfun.db. O arquivo deve existir. |
Uma lista de projetos vazia pode, portanto, significar que você abriu outro banco de dados válido. Registre o processo e o caminho absoluto selecionado antes de alterar migrações ou copiar dados. Uma sessão de conta também pode alterar quais recursos ficam visíveis sem alterar o arquivo.
Aplicar e verificar uma alteração
- Identifique o processo proprietário e o caminho de armazenamento atual. Preserve os dados necessários antes de alterar o armazenamento ou migrações.
- Pare esse processo de forma limpa e atualize sua configuração de inicialização explícita ou configuração nativa.
- Inicie novamente e aguarde o resultado real de prontidão. Resolva a nova conexão em vez de reutilizar uma porta antiga.
- Verifique uma chamada de saúde pública e uma chamada protegida admitida.
- Verifique o comportamento específico: o projeto pretendido aparece, o status do provedor muda, o gateway fica acessível ou o coletor de telemetria configurado recebe o sinal esperado.
A presença de um valor configurado não é o mesmo que uma integração externa funcional. Leia o resultado do serviço depois de fazer uma alteração. Os valores de configuração com padrão devem ser diferenciados dos valores opcionais para os quais o serviço receptor decide seu substituto.
Diagnóstico de configuração
Se a inicialização falhar antes de estar pronta, inspecione as configurações necessárias, a disponibilidade da migração, o acesso ao diretório e o erro de construção da primeira camada. Se a integridade for bem-sucedida, mas uma chamada protegida falhar, verifique o tipo de token e o processo atual. Se um provedor falhar enquanto os projetos funcionam, inspecione a configuração da IA em vez de redefinir o banco de dados.
Se o Studio não estiver disponível no site hospedado, sua API de produção retornará intencionalmente 503; inicie seu processo Bun local no arquivo existente selecionado. Se o assistente de documentação não estiver disponível, inspecione as ligações do Worker ou seu backend nikcli configurado. Nenhum dos diagnósticos exige a substituição das credenciais do desktop.
Evidência de origem: apps/sidecar/src/config.ts, layers.ts, main.ts, observability.ts, services/ai.ts, packages/db/src/migrate.ts, e packages/web/script/studio-server.ts.
Cada configuração de sidecar em uma tabela
AppConfigService é o único lugar no sidecar que lê o ambiente. A tabela lista todas as variáveis que lê, na ordem em que as lê. Valores opcionais vazios ou espaços em branco são tratados como ausentes quando indicados.
| Variável | Tipo | Padrão | Usado por |
|---|---|---|---|
CADCAMFUN_TOKEN | string editada | obrigatório | Middleware de portador para cada rota protegida |
CADCAMFUN_DATA_DIR | corda | obrigatório | Banco de dados, armazenamento de IA, plug-ins, complemento, uploads |
CADCAMFUN_MIGRATIONS_DIR | corda | ausente | Camada de banco de dados; ausente significa que nenhum esquema foi criado |
CADCAMFUN_APP_URL | corda | ausente | Links em e-mails de contas (o legado NEXTAUTH_URL) |
CADCAMFUN_DEBUG_LINKS | booleano | false | Redefinição de eco e links mágicos nas respostas (somente desenvolvimento) |
CADCAMFUN_AI_OFFLINE | booleano | false | Sem download de catálogo de provedores e sem pesquisa na web ao vivo |
CADCAMFUN_AI_HOST | nikcli | direct | nikcli | Anfitrião assistente; qualquer outro valor falha na inicialização |
CADCAMFUN_AI_MINIMAX_BASE_URL | corda, aparada | ausente | Endpoint MiniMax para o host incorporado |
STRIPE_WEBHOOK_SECRET | corda | ausente | Sem ele, os webhooks do Stripe são recusados |
STRIPE_SECRET_KEY | string editada | ausente | Sem ele, o checkout pago e o portal de cobrança ficam indisponíveis |
STRIPE_PRICE_BASIC, _PRO, _ENTERPRISE | corda, aparada | ausente | ID de preço por plano pago; valores em branco são ignorados |
CRON_SECRET | corda | ausente | Segredo compartilhado para /api/cron/*; sem ele a rota fica aberta para o aplicativo local |
ADMIN_EMAIL | corda | ausente | E-mail do administrador; por padrão o perfil local administra sua própria instalação |
OTEL_EXPORTER_OTLP_ENDPOINT | corda, aparada | ausente | URL base do coletor OTLP/HTTP; a telemetria está desligada sem ele |
O aplicativo relatado version é fixado no código (6.0.0), não lido do ambiente.
Valores inválidos interrompem a inicialização
Uma variável obrigatória ausente ou um valor que não pode ser analisado (por exemplo CADCAMFUN_AI_HOST=local), falha na camada de configuração. O sidecar então imprime um erro em vez de sua linha pronta e a área de trabalho relata a falha na inicialização.
Variáveis lidas fora da configuração do sidecar
| Variável | Leitor | Propósito |
|---|---|---|
DATABASE_URL | packages/db migrar script e drizzle-kit | Alvo para db:migrate / db:generate; um líder file: está despojado. Padrão ./data/cadcamfun.db em relação a packages/db. |
CADCAMFUN_DB, então DATABASE_URL | Servidor Web Studio (packages/web/script/studio-server.ts) | Banco de dados que o Studio local abre; padrão data/cadcamfun.db na raiz do repositório. |
NIKCLI_LOCALE, NIKCLI_LANGUAGE, NIKCLI_REGION | Host assistente incorporado | Substitua o idioma e a região do assistente. |
LC_ALL, LC_MESSAGES, LANG, LANGUAGE, TZ | Host assistente incorporado | Detecção de localidade e fuso horário do sistema quando nenhuma substituição está definida. |
O shell da área de trabalho passa exatamente três variáveis para o sidecar que ele inicia: CADCAMFUN_TOKEN (um novo token aleatório por lançamento), CADCAMFUN_DATA_DIR (o diretório de dados do aplicativo) e CADCAMFUN_MIGRATIONS_DIR (as migrações agrupadas). Qualquer outra coisa deve estar presente no ambiente com o qual o aplicativo de desktop foi iniciado.
O que reside no diretório de dados
cadcamfun.db SQLite database (+ -wal / -shm while running)
backups/ pre-migration snapshots, newest five kept
auth-secret signing secret for account session tokens (0600)
auth-revoked.json revoked session tokens
ai/
credentials.json provider API keys (owner-readable only)
policy.json operator policy for the assistant
skills/ user skills
session-owners/ which account owns which assistant session
nikcli/ isolated working and config dirs of the embedded host
plugins/ assistant plugins loaded at startup
plugins-registry/ installed marketplace plugin files
companion/ gateway TLS cert.pem and key.pem (0600)
storage/ file storage for library import/export, entity I/O and plugins
uploads/profiles/ profile pictures
downloads/ files served by /api/download
waitlist.json local waitlist entriesOs diretórios são criados na primeira utilização, portanto, uma nova instalação contém apenas aqueles que seus recursos tocaram. Faça backup de todo o diretório com o aplicativo parado: o banco de dados, as credenciais, o segredo de autenticação e as chaves complementares pertencem um ao outro. Os dispositivos complementares emparelhados são armazenados na tabela de valores-chave do banco de dados, e não em companion/.
Trate o diretório como secreto
ai/credentials.json, auth-secret e a chave privada complementar são credenciais. Não submeta um diretório de dados de desenvolvimento nem anexe-o a relatórios de bugs.
Configurações de exemplo
export CADCAMFUN_TOKEN=dev-$(openssl rand -hex 16)
export CADCAMFUN_DATA_DIR="$(mktemp -d)"
export CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle"
export CADCAMFUN_AI_HOST=direct
export CADCAMFUN_AI_OFFLINE=true
bun --no-env-file apps/sidecar/src/main.tsexport CADCAMFUN_APP_URL=http://localhost:4321
export CADCAMFUN_DEBUG_LINKS=true # reset/magic links appear in responsesexport OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318export STRIPE_SECRET_KEY=sk_test_...
export STRIPE_WEBHOOK_SECRET=whsec_...
export STRIPE_PRICE_PRO=price_...Nunca defina CADCAMFUN_DEBUG_LINKS desenvolvimento externo: coloca links de contas em respostas HTTP.