Documentation
Configuration d'exécution
Choisissez le processus, le répertoire de données, le type d'informations d'identification et les paramètres d'intégration qui contrôlent réellement chaque environnement d'exécution.
Traduit automatiquement de l'anglais. Voir l'original en anglais
Propriétaires de configuration
Le sidecar lit la configuration de l'environnement via AppConfigService dans apps/sidecar/src/config.ts. Une couche lit ces valeurs lors de sa construction et transmet une valeur AppConfig aux services qui en ont besoin. La modification d'une variable shell parent ne modifie pas un service déjà en cours d'exécution.
Tauri fournit son propre jeton de lancement et ses propres chemins de données/migration d'application lors du démarrage de l'enfant. L'aperçu du navigateur utilise les variables de connexion côté Vite. Mobile stocke une connexion de bureau couplée et les informations d'identification de l'appareil. Le site de documentation dispose de liaisons Worker distinctes et d'un processus Studio local indépendant. Ils ne partagent pas de fichier de configuration universel.
Configurez le propriétaire du comportement que vous souhaitez modifier. Par exemple, la définition de l'URL de migration CLI ne redirige pas la base de données de bureau native et la configuration de l'assistant de documentation ne fournit pas les informations d'identification du fournisseur d'IA de bureau.
Démarrer un sidecar isolé
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.tsCela utilise un répertoire jetable et un exemple de jeton de développement. Choisissez un jeton approprié pour votre propre processus. Le serveur lie le bouclage sur un port attribué ; lisez ce port à partir de son événement prêt. Gardez stdin ouvert car sa fermeture signale l'arrêt. La commande transmet délibérément les paramètres explicitement et désactive le chargement automatique du fichier d'environnement de Bun.
Pour la boucle native normale, utilisez bun run desktop:dev. Il prépare le binaire sidecar et les migrations avant de lancer Tauri, qui possède la connexion de processus résultante. Ne démarrez pas un deuxième sidecar manuel et supposez que la vue Web native s'y attachera.
Paramètres de connexion et de stockage requis
| Paramètre | Défaut | Comportement |
|---|---|---|
CADCAMFUN_TOKEN | Requis | Informations d'identification du porteur d'application expurgées pour les routes API locales protégées. |
CADCAMFUN_DATA_DIR | Requis | Racine de l’État local géré par sidecar. La base de données est cadcamfun.db en dessous. |
CADCAMFUN_MIGRATIONS_DIR | Absent | Répertoire de migration transmis à la couche base de données. Sans cela, l'ouverture de la base de données ne crée ni ne met à niveau les tables d'application. |
CADCAMFUN_APP_URL | Absent dans la configuration | URL de base fournie pour les intégrations de liens de compte. Le service concerné décide de son recours. |
CADCAMFUN_DEBUG_LINKS | FAUX | Active les champs de réponse de développement pour les liens de compte dans les gestionnaires qui les prennent en charge. |
Le répertoire de données est une racine de stockage et non une adresse de liaison HTTP. L'écouteur du serveur principal est fixé sur 127.0.0.1 avec un port éphémère. Le réseau compagnon utilise sa propre passerelle HTTPS explicitement activée ; la modification d'un paramètre d'URL ne rend pas l'écouteur de bouclage public.
Gardez le répertoire de migration configuré aligné avec le binaire. Le démarrage peut échouer avant d'être prêt lorsqu'une migration ne peut pas être planifiée, sauvegardée ou appliquée. La référence de la base de données explique le comportement des transactions et des sauvegardes ; une table manquante après l'omission des migrations est un problème de configuration plutôt qu'une preuve que le projet a été supprimé.
Le jeton d'application est lu comme une valeur rédigée et n'apparaît jamais dans les journaux de configuration. Chaque paramètre de cette page est lu une fois, en apps/sidecar/src/config.ts; une valeur modifiée ne prend effet qu’après le redémarrage du sidecar.
Hôte IA et connectivité
| Paramètre | Défaut | Comportement |
|---|---|---|
CADCAMFUN_AI_HOST | nikcli | Sélectionner nikcli ou direct. L'hôte direct n'ajoute pas la boucle d'outils persistante intégrée ni le planificateur spécialisé. |
CADCAMFUN_AI_OFFLINE | FAUX | Désactive le chargement du catalogue du fournisseur de réseau et le gestionnaire de recherche Web en direct. Il ne s’agit pas d’une implémentation de modèle local. |
CADCAMFUN_AI_MINIMAX_BASE_URL | Absent | Remplacement du point de terminaison réduit en option pour la configuration MiniMax intégrée. |
Les clés du fournisseur sont gérées par l'API d'informations d'identification et conservées par le service AI à l'adresse <dataDir>/ai/credentials.json. Ils ne sont pas fournis en inventant une variable d'environnement non documentée pour chaque fournisseur. Utilisez les points de terminaison d'état du fournisseur/modèle pour établir ce qui est configuré et le Guide de l'IA pour le routage de modèle direct pris en charge.
Le mode hors ligne ne transforme pas un appel du fournisseur cloud en réponse hors ligne. Un modèle direct ou intégré configuré peut toujours nécessiter sa connexion fournisseur pour l'inférence. Le produit local d'abord conserve les projets locaux sans connexion de modèle ; cette propriété de stockage est distincte de l’inférence de l’IA hors ligne.
La stratégie de l'opérateur est chargée à partir de <dataDir>/ai/policy.json. L'hôte intégré isole ses propres répertoires de travail/configuration sous le stockage AI de l'application. La stratégie, les informations d'identification, le contexte de session et le cache du catalogue de fournisseurs ont des objectifs différents ; la copie d'un fichier ne reconstruit pas l'intégralité de l'exécution d'une conversation.
Intégrations de compte et de facturation
| Paramètre | Utiliser | En cas d'absence |
|---|---|---|
STRIPE_SECRET_KEY | Authentification API Stripe sortante. | Le paiement payant et l'intégration du portail de facturation ne sont pas disponibles. |
STRIPE_WEBHOOK_SECRET | Vérifiez les charges utiles du webhook Stripe signées. | Le gestionnaire de webhook refuse l'ingestion sans vérification de la configuration. |
STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, STRIPE_PRICE_ENTERPRISE | ID de prix pour les forfaits payants. Les valeurs vides sont ignorées. | Un mappage manquant ne peut pas identifier un prix de paiement configuré pour ce plan. |
CRON_SECRET | Identifiant partagé supplémentaire pour la maintenance cron. | Aucun secret cron supplémentaire n'est requis par ce garde ; L’admission au porteur de la demande s’applique toujours. |
ADMIN_EMAIL | Identité de l'administrateur utilisée par la stratégie de compte/service. | Le profil de l'installation locale conserve le comportement administratif local mis en œuvre par ses services. |
Ces paramètres configurent les intégrations ; ils n'établissent pas qu'il existe un compte à distance, un prix, un abonnement ou une livraison webhook. Vérifiez l'échec réel de l'opération et l'état du service en cours d'exécution. N'en déduisez pas que la présence d'une table signifie que la fonctionnalité hébergée associée est entièrement configurée.
L'interface AppConfig contient également des hooks d'injection de test tels qu'une usine de modèles de remplacement et une base API Stripe. Ce ne sont pas des variables d'environnement lues par cette couche de configuration de production. Gardez les hooks de test en dehors des instructions de déploiement à moins que l'hôte en cours d'exécution ne les expose explicitement.
La période d'essai de facturation commence dans 14 jours PRO procès (TRIAL_DAYS dans apps/sidecar/src/repos/billing-repo.ts, utilisé par http/billing.ts). Les plans disponibles sont FREE, BASIC, PRO, et ENTERPRISE; seuls les trois forfaits payants prennent un STRIPE_PRICE_* paramètre.
Journaux et télémétrie
OTEL_EXPORTER_OTLP_ENDPOINT active les exportateurs de traces, de métriques et de journaux OTLP/HTTP du sidecar. Sans point de terminaison non vide, cette couche de télémétrie facultative est désactivée. Le code de l'exportateur crée les points de terminaison spécifiques au signal ; configurez un collecteur qui prend en charge ces signaux.
La journalisation sidecar normale est distincte de l’exportation de télémétrie. Stdout transporte le protocole de préparation/erreur JSON consommé par le shell, tandis que les journaux sont dirigés vers stderr. Lors du diagnostic du démarrage, conservez la première erreur pertinente et son contexte de fonctionnement plutôt que d'attendre que la fenêtre de l'application contienne tous les détails d'initialisation.
N'incluez pas de jetons de lancement, de clés de fournisseur, de jetons de session ou de fichiers d'informations d'identification complets dans les ensembles de diagnostics. Les chemins source, la méthode/le statut, les ID de point de terminaison, les ID de projet non secrets et l'échec de l'opération de base de données fournissent généralement un point de départ plus sûr et plus utile.
Configuration des clients
Un aperçu du bureau uniquement dans le navigateur utilise la fausse API en mémoire lorsque VITE_SIDECAR_URL est absent. Pour le connecter à un sidecar démarré manuellement, définissez cette URL et VITE_SIDECAR_TOKEN avant de démarrer Vite. Le chemin Tauri empaqueté obtient sa connexion à partir du shell à la place.
VITE_SIDECAR_URL=http://127.0.0.1:READY_PORT \
VITE_SIDECAR_TOKEN=local-development-token \
bun run --filter @cadcamfun/desktop devRemplacez l'espace réservé au port. Les paramètres Vite appartiennent au processus de développement frontend ; les modifier ne redémarre ni ne reconfigure le sidecar. L'accès au navigateur est soumis à la politique de bouclage/Tauri CORS du sidecar et à l'admission normale du support.
Le couplage mobile stocke son adresse de bureau, l'empreinte digitale du certificat et le jeton de l'appareil via l'application mobile. Changer le jeton de lancement du bureau n'est pas une manière normale de coupler un téléphone. Utilisez le procédure d'appariement et révoquer des appareils individuels si nécessaire.
Sélection du chemin de base de données
| Processus | Règle de sélection |
|---|---|
| Sidecar de bureau natif | Répertoire de données d'application fourni par Tauri, puis cadcamfun.db. |
| Sidecar manuel | CADCAMFUN_DATA_DIR/cadcamfun.db. |
| CLI de migration de base de données | DATABASE_URL, en supprimant une initiale file:; sinon relatif au processus ./data/cadcamfun.db. |
Racine db:migrate emballage | Exécute le script du package DB, de sorte que la valeur par défaut soit résolue dans packages/db. |
| Studio de documentation | CADCAMFUN_DB, alors DATABASE_URL, puis racine du référentiel data/cadcamfun.db. Le fichier doit exister. |
Une liste de projets vide peut donc signifier que vous avez ouvert une autre base de données valide. Enregistrez le processus et le chemin absolu sélectionné avant de modifier les migrations ou de copier des données. Une session de compte peut également modifier les ressources visibles sans modifier le fichier.
Appliquer et vérifier un changement
- Identifiez le processus propriétaire et le chemin de stockage actuel. Conservez les données nécessaires avant de modifier le stockage ou les migrations.
- Arrêtez ce processus proprement et mettez à jour sa configuration de lancement explicite ou ses paramètres natifs.
- Redémarrez-le et attendez son résultat réel de préparation. Résolvez la nouvelle connexion au lieu de réutiliser un ancien port.
- Vérifiez un appel de santé publique et un appel protégé admis.
- Vérifiez le comportement spécifique : le projet souhaité apparaît, le statut du fournisseur change, la passerelle devient accessible ou le collecteur de télémétrie configuré reçoit le signal attendu.
La présence d'une valeur configurée n'est pas la même chose qu'une intégration externe fonctionnelle. Lisez le résultat du service après avoir effectué une modification. Les valeurs de configuration avec une valeur par défaut doivent être distinguées des valeurs facultatives pour lesquelles le service récepteur décide de son repli.
Diagnostic de configuration
Si l'initialisation échoue avant d'être prête, inspectez les paramètres requis, la disponibilité de la migration, l'accès au répertoire et la première erreur de construction de couche. Si l’intégrité réussit mais qu’un appel protégé échoue, vérifiez le type de jeton et le processus en cours. Si un fournisseur échoue pendant le fonctionnement des projets, inspectez la configuration de l'IA plutôt que de réinitialiser la base de données.
Si Studio n'est pas disponible sur le site hébergé, son API de production renvoie intentionnellement 503 ; démarrer son processus Bun local sur le fichier existant sélectionné. Si l'assistant de documentation n'est pas disponible, inspectez les liaisons Worker ou son backend nikcli configuré. Aucun des deux diagnostics ne nécessite le remplacement des informations d’identification du bureau.
Preuve source : apps/sidecar/src/config.ts, layers.ts, main.ts, observability.ts, services/ai.ts, packages/db/src/migrate.ts, et packages/web/script/studio-server.ts.
Chaque paramètre sidecar dans une seule table
AppConfigService est le seul endroit dans le sidecar qui lit l'environnement. Le tableau répertorie toutes les variables qu'il lit, dans l'ordre dans lequel il les lit. Les valeurs facultatives vides ou blanches sont traitées comme absentes lorsqu'elles sont indiquées.
| Variable | Taper | Défaut | Utilisé par |
|---|---|---|---|
CADCAMFUN_TOKEN | chaîne rédigée | requis | Middleware de support pour chaque route protégée |
CADCAMFUN_DATA_DIR | chaîne | requis | Base de données, stockage IA, plugins, compagnon, téléchargements |
CADCAMFUN_MIGRATIONS_DIR | chaîne | absent | Couche de base de données ; absent signifie qu'aucun schéma n'est créé |
CADCAMFUN_APP_URL | chaîne | absent | Liens dans les e-mails du compte (l'héritage NEXTAUTH_URL) |
CADCAMFUN_DEBUG_LINKS | booléen | false | Réinitialisation de l'écho et liens magiques dans les réponses (développement uniquement) |
CADCAMFUN_AI_OFFLINE | booléen | false | Pas de téléchargement de catalogue de fournisseurs et pas de recherche Web en direct |
CADCAMFUN_AI_HOST | nikcli | direct | nikcli | Hôte adjoint ; toute autre valeur échoue au démarrage |
CADCAMFUN_AI_MINIMAX_BASE_URL | ficelle, coupée | absent | Point de terminaison MiniMax pour l'hôte intégré |
STRIPE_WEBHOOK_SECRET | chaîne | absent | Sans cela, les webhooks Stripe sont refusés |
STRIPE_SECRET_KEY | chaîne rédigée | absent | Sans cela, le paiement payant et le portail de facturation ne sont pas disponibles |
STRIPE_PRICE_BASIC, _PRO, _ENTERPRISE | ficelle, coupée | absent | Identifiant du prix par forfait payant ; les valeurs vides sont ignorées |
CRON_SECRET | chaîne | absent | Secret partagé pour /api/cron/*; sans cela, l'itinéraire est ouvert à l'application locale |
ADMIN_EMAIL | chaîne | absent | Courriel de l'administrateur ; par défaut le profil local administre sa propre installation |
OTEL_EXPORTER_OTLP_ENDPOINT | ficelle, coupée | absent | URL de base du collecteur OTLP/HTTP ; la télémétrie est désactivée sans elle |
La demande signalée version est corrigé dans le code (6.0.0), pas lu à partir de l'environnement.
Des valeurs invalides arrêtent le démarrage
Une variable obligatoire manquante ou une valeur qui n'est pas analysée (par exemple CADCAMFUN_AI_HOST=local), échoue à la couche de configuration. Le sidecar imprime ensuite une erreur au lieu de sa ligne prête et le bureau signale l'échec du démarrage.
Variables lues en dehors de la configuration sidecar
| Variable | Lecteur | But |
|---|---|---|
DATABASE_URL | packages/db migrer le script et le kit bruine | Cible pour db:migrate / db:generate; un leader file: est dépouillé. Défaut ./data/cadcamfun.db par rapport à packages/db. |
CADCAMFUN_DB, alors DATABASE_URL | Serveur Web Studio (packages/web/script/studio-server.ts) | Base de données que le Studio local ouvre ; défaut data/cadcamfun.db à la racine du référentiel. |
NIKCLI_LOCALE, NIKCLI_LANGUAGE, NIKCLI_REGION | Hôte assistant intégré | Remplacez la langue et la région de l'assistant. |
LC_ALL, LC_MESSAGES, LANG, LANGUAGE, TZ | Hôte assistant intégré | Détection des paramètres régionaux et du fuseau horaire du système lorsqu'aucun remplacement n'est défini. |
Le shell du bureau transmet exactement trois variables au sidecar qu'il lance : CADCAMFUN_TOKEN (un nouveau jeton aléatoire par lancement), CADCAMFUN_DATA_DIR (le répertoire des données de l'application) et CADCAMFUN_MIGRATIONS_DIR (les migrations groupées). Tout le reste doit être présent dans l'environnement avec lequel l'application de bureau elle-même a été démarrée.
Ce qui se trouve dans le répertoire de données
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 entriesLes répertoires sont créés lors de la première utilisation, donc une nouvelle installation ne contient que ceux que ses fonctionnalités ont touchés. Sauvegardez l'intégralité du répertoire avec l'application arrêtée : la base de données, les informations d'identification, le secret d'authentification et les clés compagnon vont ensemble. Les appareils compagnons couplés sont stockés dans la table clé-valeur de la base de données, et non dans companion/.
Traitez le répertoire comme secret
ai/credentials.json, auth-secret et la clé privée associée sont les informations d'identification. Ne validez pas un répertoire de données de développement et ne le joignez pas aux rapports de bogues.
Exemples de configuration
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_...Ne réglez jamais CADCAMFUN_DEBUG_LINKS en dehors du développement : il met les liens des comptes dans les réponses HTTP.