Dokumentation
Laufzeitkonfiguration
Wählen Sie den Prozess, das Datenverzeichnis, den Anmeldeinformationstyp und die Integrationseinstellungen aus, die jede Laufzeit tatsächlich steuern.
Automatisch aus dem Englischen übersetzt. Englisches Original ansehen
Konfigurationseigentümer
Der Sidecar liest die Umgebungskonfiguration durch AppConfigService in apps/sidecar/src/config.ts. Eine Ebene liest diese Werte, wenn sie erstellt wird, und übergibt einen AppConfig-Wert an die Dienste, die ihn benötigen. Durch das Ändern einer übergeordneten Shell-Variable wird ein bereits ausgeführter Dienst nicht verändert.
Tauri stellt beim Starten des Kindes sein eigenes Starttoken und Anwendungsdaten-/Migrationspfade bereit. Die Browservorschau verwendet Vite-seitige Verbindungsvariablen. Mobile speichert eine gekoppelte Desktop-Verbindung und Geräteanmeldeinformationen. Die Dokumentationsseite verfügt über separate Worker-Bindungen und einen unabhängigen lokalen Studio-Prozess. Sie teilen keine universelle Konfigurationsdatei.
Konfigurieren Sie den Eigentümer des Verhaltens, das Sie ändern möchten. Wenn Sie beispielsweise die CLI-Migrations-URL festlegen, wird die native Desktop-Datenbank nicht umgeleitet, und durch die Konfiguration des Dokumentationsassistenten werden die Anmeldeinformationen des Desktop-KI-Anbieters nicht bereitgestellt.
Starten Sie einen isolierten Sidecar
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.tsDabei werden ein Einwegverzeichnis und ein Beispielentwicklungstoken verwendet. Wählen Sie einen geeigneten Token für Ihren eigenen Prozess. Der Server bindet Loopback an einen zugewiesenen Port; Lesen Sie diesen Port aus seinem Ready-Ereignis. Halten Sie stdin geöffnet, da das Schließen das Herunterfahren signalisiert. Der Befehl übergibt Einstellungen bewusst explizit und deaktiviert Buns automatisches Laden der Umgebungsdatei.
Für die normale native Schleife verwenden Sie bun run desktop:dev. Es bereitet die Sidecar-Binärdatei und Migrationen vor, bevor es Tauri startet, das Eigentümer der resultierenden Prozessverbindung ist. Starten Sie keinen zweiten manuellen Sidecar und gehen Sie davon aus, dass die native Webansicht daran angehängt wird.
Erforderliche Verbindungs- und Speichereinstellungen
| Einstellung | Standard | Verhalten |
|---|---|---|
CADCAMFUN_TOKEN | Erforderlich | Die Anmeldeinformationen des Anwendungsträgers für geschützte lokale API-Routen wurden geschwärzt. |
CADCAMFUN_DATA_DIR | Erforderlich | Stamm des vom Sidecar verwalteten lokalen Zustands. Die Datenbank ist cadcamfun.db darunter. |
CADCAMFUN_MIGRATIONS_DIR | Abwesend | Migrationsverzeichnis, das an die Datenbankschicht übergeben wird. Ohne sie werden beim Öffnen der Datenbank keine Anwendungstabellen erstellt oder aktualisiert. |
CADCAMFUN_APP_URL | Fehlt in der Konfiguration | Basis-URL, die für Kontoverknüpfungsintegrationen bereitgestellt wird. Über den Fallback entscheidet der jeweilige Dienst. |
CADCAMFUN_DEBUG_LINKS | FALSCH | Aktiviert Entwicklungsantwortfelder für Kontoverknüpfungen in Handlern, die diese unterstützen. |
Das Datenverzeichnis ist ein Speicherstammverzeichnis, keine HTTP-Bindadresse. Der Listener des Hauptservers ist festgelegt 127.0.0.1 mit einem vergänglichen Hafen. Companion Networking verwendet ein eigenes, explizit aktiviertes HTTPS-Gateway. Durch das Ändern einer URL-Einstellung wird der Loopback-Listener nicht öffentlich.
Halten Sie das konfigurierte Migrationsverzeichnis an der Binärdatei ausgerichtet. Der Start kann vor der Bereitschaft fehlschlagen, wenn eine Migration nicht geplant, gesichert oder angewendet werden kann. In der Datenbankreferenz wird das Transaktions- und Sicherungsverhalten erläutert. Eine fehlende Tabelle nach dem Auslassen von Migrationen ist eher ein Konfigurationsproblem als ein Beweis dafür, dass das Projekt gelöscht wurde.
Das Anwendungstoken wird als geschwärzter Wert gelesen und erscheint nie in Konfigurationsprotokollen. Jede Einstellung auf dieser Seite wird einmal eingelesen apps/sidecar/src/config.ts; ein geänderter Wert wird erst nach dem Neustart des Sidecars wirksam.
KI-Host und Konnektivität
| Einstellung | Standard | Verhalten |
|---|---|---|
CADCAMFUN_AI_HOST | nikcli | Wählen nikcli oder direct. Der direkte Host fügt die eingebettete persistente Tool-Schleife und den speziellen Scheduler nicht hinzu. |
CADCAMFUN_AI_OFFLINE | FALSCH | Deaktiviert das Laden des Netzwerkanbieterkatalogs und den Live-Websuchhandler. Es handelt sich nicht um eine lokale Modellimplementierung. |
CADCAMFUN_AI_MINIMAX_BASE_URL | Abwesend | Optionale Überschreibung des gekürzten Endpunkts für die eingebettete MiniMax-Konfiguration. |
Anbieterschlüssel werden von der Anmeldeinformations-API verwaltet und vom KI-Dienst unter gespeichert <dataDir>/ai/credentials.json. Sie werden nicht bereitgestellt, indem für jeden Anbieter eine undokumentierte Umgebungsvariable erfunden wird. Verwenden Sie die Anbieter-/Modellstatus-Endpunkte, um festzustellen, was konfiguriert ist und was KI-Leitfaden für unterstütztes Direct-Model-Routing.
Der Offline-Modus verwandelt einen Anruf eines Cloud-Anbieters nicht in eine Offline-Antwort. Ein konfiguriertes direktes oder eingebettetes Modell kann weiterhin seine Anbieterverbindung für die Inferenz erfordern. Das Local-First-Produkt behält lokale Projekte ohne Modellverbindung; Diese Speichereigenschaft unterscheidet sich von der Offline-KI-Inferenz.
Die Betreiberrichtlinie wird geladen von <dataDir>/ai/policy.json. Der eingebettete Host isoliert seine eigenen Arbeits-/Konfigurationsverzeichnisse unterhalb des KI-Speichers der Anwendung. Richtlinien, Anmeldeinformationen, Sitzungskontext und Anbieterkatalog-Cache haben unterschiedliche Zwecke. Durch das Kopieren einer Datei wird nicht die gesamte Laufzeit einer Konversation wiederhergestellt.
Konto- und Abrechnungsintegrationen
| Einstellung | Verwenden | Bei Abwesenheit |
|---|---|---|
STRIPE_SECRET_KEY | Ausgehende Stripe-API-Authentifizierung. | Bezahlter Checkout und die Integration des Abrechnungsportals sind nicht verfügbar. |
STRIPE_WEBHOOK_SECRET | Überprüfen Sie signierte Stripe-Webhook-Nutzlasten. | Der Webhook-Handler lehnt die Aufnahme ohne Überprüfungskonfiguration ab. |
STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, STRIPE_PRICE_ENTERPRISE | Preis-IDs für kostenpflichtige Pläne. Leere Werte werden ignoriert. | Eine fehlende Zuordnung kann keinen konfigurierten Checkout-Preis für diesen Plan identifizieren. |
CRON_SECRET | Zusätzliche gemeinsame Anmeldeinformationen für die Cron-Wartung. | Für diesen Wächter ist kein zusätzliches Cron-Geheimnis erforderlich. Die Zulassung als Antragsträger gilt weiterhin. |
ADMIN_EMAIL | Von der Konto-/Dienstrichtlinie verwendete Administratoridentität. | Das Profil der lokalen Installation behält das lokale Verwaltungsverhalten bei, das von seinen Diensten implementiert wird. |
Diese Einstellungen konfigurieren Integrationen; Sie stellen nicht fest, dass ein Remote-Konto, ein Remote-Preis, ein Abonnement oder eine Webhook-Zustellung vorhanden ist. Überprüfen Sie den tatsächlichen Fehler des Vorgangs und den Status des laufenden Dienstes. Schließen Sie nicht daraus, dass das Vorhandensein einer Tabelle bedeutet, dass die zugehörige gehostete Funktion vollständig konfiguriert ist.
Die AppConfig-Schnittstelle enthält auch Testinjektions-Hooks wie eine Ersatzmodellfabrik und eine Stripe-API-Basis. Es handelt sich nicht um Umgebungsvariablen, die von dieser Produktionskonfigurationsschicht gelesen werden. Halten Sie Test-Hooks aus Bereitstellungsanweisungen fern, es sei denn, der laufende Host macht sie explizit verfügbar.
Die Abrechnungstestroute beginnt am 14-Tag PRO versuch (TRIAL_DAYS in apps/sidecar/src/repos/billing-repo.ts, verwendet von http/billing.ts). Die verfügbaren Pläne sind FREE, BASIC, PRO, und ENTERPRISE; nur die drei kostenpflichtigen Pläne dauern eine STRIPE_PRICE_* einstellung.
Protokolle und Telemetrie
OTEL_EXPORTER_OTLP_ENDPOINT aktiviert die OTLP/HTTP-Trace-, Metrik- und Protokollexporteure des Sidecars. Ohne einen nicht leeren Endpunkt ist diese optionale Telemetrieebene deaktiviert. Der Exportercode erstellt die signalspezifischen Endpunkte; Konfigurieren Sie einen Kollektor, der diese Signale unterstützt.
Die normale Sidecar-Protokollierung ist vom Telemetrieexport getrennt. Stdout überträgt das von der Shell verwendete JSON-Bereitschafts-/Fehlerprotokoll, während Protokolle an stderr weitergeleitet werden. Behalten Sie bei der Startdiagnose den ersten relevanten Fehler und seinen Vorgangskontext bei, anstatt zu erwarten, dass das Anwendungsfenster alle Initialisierungsdetails enthält.
Schließen Sie keine Start-Tokens, Anbieterschlüssel, Sitzungs-Tokens oder vollständige Anmeldeinformationsdateien in Diagnosepakete ein. Quellpfade, Methode/Status, Endpunkt-IDs, nicht geheime Projekt-IDs und der fehlgeschlagene Datenbankvorgang bieten normalerweise einen sichereren und nützlicheren Ausgangspunkt.
Client-Konfiguration
Eine reine Browser-Desktop-Vorschau verwendet die gefälschte In-Memory-API, wenn VITE_SIDECAR_URL fehlt. Um es mit einem manuell gestarteten Sidecar zu verbinden, legen Sie diese URL fest und VITE_SIDECAR_TOKEN bevor Sie mit Vite beginnen. Der gepackte Tauri-Pfad erhält seine Verbindung stattdessen von der Shell.
VITE_SIDECAR_URL=http://127.0.0.1:READY_PORT \
VITE_SIDECAR_TOKEN=local-development-token \
bun run --filter @cadcamfun/desktop devErsetzen Sie den Port-Platzhalter. Vite-Einstellungen gehören zum Frontend-Entwicklungsprozess; Wenn Sie sie ändern, wird der Sidecar nicht neu gestartet oder neu konfiguriert. Der Browserzugriff unterliegt der Loopback-/Tauri CORS-Richtlinie des Sidecars und der normalen Trägerzulassung.
Beim mobilen Pairing werden die Desktop-Adresse, der Zertifikat-Fingerabdruck und das Geräte-Token über die mobile Anwendung gespeichert. Das Ändern des Starttokens des Desktops ist keine normale Methode zum Koppeln eines Telefons. Benutzen Sie die pairing-Vorgang und bei Bedarf einzelne Geräte widerrufen.
Auswahl des Datenbankpfads
| Verfahren | Auswahlregel |
|---|---|
| Nativer Desktop-Sidecar | Dann das von Tauri bereitgestellte Anwendungsdatenverzeichnis cadcamfun.db. |
| Manueller Sidecar | CADCAMFUN_DATA_DIR/cadcamfun.db. |
| CLI für die Datenbankmigration | DATABASE_URL, entfernen einer Initiale file:; ansonsten prozessbezogen ./data/cadcamfun.db. |
Wurzel db:migrate verpackung | Führt das DB-Paketskript aus, sodass die Standardeinstellung darin aufgelöst wird packages/db. |
| Dokumentationsstudio | CADCAMFUN_DB, dann DATABASE_URL, dann Repository-Root data/cadcamfun.db. Die Datei muss vorhanden sein. |
Eine leere Projektliste kann daher bedeuten, dass Sie eine andere gültige Datenbank geöffnet haben. Zeichnen Sie den Prozess und den absolut ausgewählten Pfad auf, bevor Sie Migrationen ändern oder Daten kopieren. Eine Kontositzung kann auch ändern, welche Ressourcen sichtbar sind, ohne die Datei zu ändern.
Übernehmen und überprüfen Sie eine Änderung
- Identifizieren Sie den Eigentümerprozess und den aktuellen Speicherpfad. Bewahren Sie benötigte Daten auf, bevor Sie den Speicher ändern oder migrieren.
- Stoppen Sie diesen Prozess sauber und aktualisieren Sie seine explizite Startkonfiguration oder native Einstellung.
- Starten Sie es erneut und warten Sie auf das tatsächliche Bereitschaftsergebnis. Lösen Sie die neue Verbindung auf, anstatt einen alten Port wiederzuverwenden.
- Überprüfen Sie einen öffentlichen Gesundheitsanruf und einen zugelassenen geschützten Anruf.
- Überprüfen Sie das spezifische Verhalten: Das beabsichtigte Projekt wird angezeigt, der Anbieterstatus ändert sich, das Gateway wird erreichbar oder der konfigurierte Telemetriekollektor empfängt das erwartete Signal.
Das Vorhandensein eines konfigurierten Werts ist nicht dasselbe wie eine funktionierende externe Integration. Lesen Sie das Serviceergebnis, nachdem Sie eine Änderung vorgenommen haben. Konfigurationswerte mit einem Standardwert sollten von optionalen Werten unterschieden werden, für die der empfangende Dienst über seinen Fallback entscheidet.
Konfigurationsdiagnose
Wenn die Initialisierung fehlschlägt, bevor sie bereit ist, überprüfen Sie die erforderlichen Einstellungen, die Migrationsverfügbarkeit, den Verzeichniszugriff und den Konstruktionsfehler der ersten Schicht. Wenn die Integrität erfolgreich ist, ein geschützter Aufruf jedoch fehlschlägt, überprüfen Sie den Tokentyp und den aktuellen Prozess. Wenn ein Anbieter ausfällt, während Projekte laufen, überprüfen Sie die KI-Konfiguration, anstatt die Datenbank zurückzusetzen.
Wenn Studio auf der gehosteten Site nicht verfügbar ist, gibt seine Produktions-API absichtlich 503 zurück; Starten Sie den lokalen Bun-Prozess für die ausgewählte vorhandene Datei. Wenn der Dokumentationsassistent nicht verfügbar ist, überprüfen Sie die Worker-Bindungen oder das konfigurierte Nikcli-Backend. Für keine der beiden Diagnosen ist ein Austausch der Desktop-Anmeldeinformationen erforderlich.
Quellennachweis: apps/sidecar/src/config.ts, layers.ts, main.ts, observability.ts, services/ai.ts, packages/db/src/migrate.ts, und packages/web/script/studio-server.ts.
Jede Sidecar-Einstellung in einer Tabelle
AppConfigService ist die einzige Stelle im Sidecar, die die Umgebung liest. Die Tabelle listet alle gelesenen Variablen in der Reihenfolge auf, in der sie gelesen werden. Optionale Werte, die leer sind oder Leerzeichen enthalten, werden an den entsprechenden Stellen als nicht vorhanden behandelt.
| Variable | Typ | Standard | Verwendet von |
|---|---|---|---|
CADCAMFUN_TOKEN | redigierte Zeichenfolge | erforderlich | Träger-Middleware für jede geschützte Route |
CADCAMFUN_DATA_DIR | zeichenfolge | erforderlich | Datenbank, KI-Speicher, Plugins, Begleiter, Uploads |
CADCAMFUN_MIGRATIONS_DIR | zeichenfolge | abwesend | Datenbankschicht; „Abwesend“ bedeutet, dass kein Schema erstellt wird |
CADCAMFUN_APP_URL | zeichenfolge | abwesend | Links in Konto-E-Mails (das Legacy NEXTAUTH_URL) |
CADCAMFUN_DEBUG_LINKS | boolescher Wert | false | Echo-Reset und magische Links in Antworten (nur Entwicklung) |
CADCAMFUN_AI_OFFLINE | boolescher Wert | false | Kein Anbieter-Katalog-Download und keine Live-Websuche |
CADCAMFUN_AI_HOST | nikcli | direct | nikcli | Stellvertretender Gastgeber; Jeder andere Wert schlägt beim Start fehl |
CADCAMFUN_AI_MINIMAX_BASE_URL | schnur, beschnitten | abwesend | MiniMax-Endpunkt für den eingebetteten Host |
STRIPE_WEBHOOK_SECRET | zeichenfolge | abwesend | Ohne sie werden Stripe-Webhooks abgelehnt |
STRIPE_SECRET_KEY | redigierte Zeichenfolge | abwesend | Ohne sie sind der kostenpflichtige Checkout und das Abrechnungsportal nicht verfügbar |
STRIPE_PRICE_BASIC, _PRO, _ENTERPRISE | schnur, beschnitten | abwesend | Preis-ID pro bezahltem Plan; Leerwerte werden ignoriert |
CRON_SECRET | zeichenfolge | abwesend | Geteiltes Geheimnis für /api/cron/*; ohne diese Angabe ist die Route für die lokale App geöffnet |
ADMIN_EMAIL | zeichenfolge | abwesend | E-Mail des Administrators; Standardmäßig verwaltet das lokale Profil seine eigene Installation |
OTEL_EXPORTER_OTLP_ENDPOINT | schnur, beschnitten | abwesend | OTLP/HTTP-Collector-Basis-URL; Ohne sie ist die Telemetrie ausgeschaltet |
Die gemeldete Anwendung version ist im Code festgelegt (6.0.0), nicht aus der Umgebung gelesen.
Ungültige Werte stoppen den Start
Eine fehlende erforderliche Variable oder ein Wert, der nicht analysiert werden kann (z. B CADCAMFUN_AI_HOST=local), schlägt die Konfigurationsebene fehl. Der Sidecar gibt dann anstelle der Ready-Zeile einen Fehler aus und der Desktop meldet den Startfehler.
Variablen, die außerhalb der Sidecar-Konfiguration gelesen werden
| Variable | Leser | Zweck |
|---|---|---|
DATABASE_URL | packages/db skript und Drizzle-Kit migrieren | Ziel für db:migrate / db:generate; ein führender file: wird abgestreift. Standard ./data/cadcamfun.db relativ zu packages/db. |
CADCAMFUN_DB, dann DATABASE_URL | Web Studio-Server (packages/web/script/studio-server.ts) | Datenbank wird das lokale Studio geöffnet; Standard data/cadcamfun.db im Repository-Stammverzeichnis. |
NIKCLI_LOCALE, NIKCLI_LANGUAGE, NIKCLI_REGION | Eingebetteter Assistent des Gastgebers | Überschreiben Sie die Sprache und Region des Assistenten. |
LC_ALL, LC_MESSAGES, LANG, LANGUAGE, TZ | Eingebetteter Assistent des Gastgebers | Systemstandort- und Zeitzonenerkennung, wenn keine Überschreibung festgelegt ist. |
Die Desktop-Shell übergibt genau drei Variablen an den Sidecar, den sie startet: CADCAMFUN_TOKEN (ein neuer zufälliger Token pro Start), CADCAMFUN_DATA_DIR (das Anwendungsdatenverzeichnis) und CADCAMFUN_MIGRATIONS_DIR (die gebündelten Migrationen). Alles andere muss in der Umgebung vorhanden sein, in der die Desktop-App selbst gestartet wurde.
Was befindet sich im Datenverzeichnis?
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 entriesVerzeichnisse werden bei der ersten Verwendung erstellt, sodass eine Neuinstallation nur diejenigen enthält, die von den Funktionen berührt wurden. Sichern Sie das gesamte Verzeichnis bei gestoppter Anwendung: Datenbank, Anmeldeinformationen, Authentifizierungsgeheimnis und Begleitschlüssel gehören zusammen. Gepaarte Begleitgeräte werden in der Schlüsselwerttabelle der Datenbank gespeichert, nicht in companion/.
Behandeln Sie das Verzeichnis als geheim
ai/credentials.json, auth-secret und der begleitende private Schlüssel sind Anmeldeinformationen. Übertragen Sie kein Entwicklungsdatenverzeichnis und hängen Sie es nicht an Fehlerberichte an.
Beispielkonfigurationen
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_...Niemals einstellen CADCAMFUN_DEBUG_LINKS außerhalb der Entwicklung: Es fügt Kontolinks in HTTP-Antworten ein.