CLI und Konfigurationsbereitstellung

Die CLI erstellt, validiert und stellt unveränderliche ChattyBox-Konfigurationsversionen bereit, befördert sie und führt Rollbacks durch. Deployment-Tokens sind auf ein Projekt und ausgewählte Umgebungen beschränkt, sodass sich derselbe Workflow für die lokale Entwicklung und CI eignet.

Konfiguration erstellen

bunx @openstaticfish/chattybox-cli init

Dadurch wird chattybox.config.json erstellt:

{
  "schemaVersion": "1",
  "assistant": {
    "name": "Support"
  },
  "knowledge": {
    "sources": [
      {
        "type": "website",
        "url": "https://example.com"
      }
    ]
  },
  "widget": {
    "enabled": true
  }
}

Verwenden Sie einen benutzerdefinierten Pfad, wenn die Konfiguration in ein Unterverzeichnis gehört:

bunx @openstaticfish/chattybox-cli init config/chattybox.config.json

Lokal oder in CI validieren

bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json

Die Validierung prüft das Schema, den erforderlichen Namen des Assistenten, unterstützte Quelltypen, HTTP-Quell-URLs, positive Seitenlimits und Widget-Farben. Eine erfolgreiche Validierung führt keine Bereitstellung durch und ändert keinen entfernten Zustand.

Deployment-Token erstellen

Öffnen Sie im Projekt den Tab Settings, suchen Sie Config deployment tokens und erstellen Sie ein Token für die Umgebungen, die Ihr Workflow ändern darf. Kopieren Sie es sofort; ChattyBox speichert nur dessen Hash und kann es nicht erneut anzeigen.

Setzen Sie das Token und die Widget-API-URL aus dem Tab Embed des Projekts:

export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'

Committen Sie das Token niemals. Speichern Sie es im verschlüsselten Secret-Speicher Ihres CI-Anbieters.

Nachdem Sie den Deployment-Workflow überprüft haben, aktivieren Sie Config-as-code lock im selben Einstellungsbereich. Die Sperre deaktiviert Konfigurations- und Korpusänderungen über das Dashboard, sodass nur entsprechend begrenzte Deployment-Tokens die Laufzeit ändern können. Das Erstellen und Widerrufen von Tokens bleibt möglich, falls ein CI-Zugangsschlüssel rotiert werden muss.

Konfiguration bereitstellen

Das Deployment erstellt eine unveränderliche Version und befördert sie in die ausgewählte Umgebung:

bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production

Promotionen nach development und preview werden zur Prüfung protokolliert. Promotionen nach production wenden den Assistant-Prompt, die Fallback-Antwort, Widget-Einstellungen, Locale und Website-Quelle atomar auf das Live-Projekt an. Die Produktionskonfiguration muss genau eine Website-Quelle enthalten. Ein Deployment stellt einen an die Version gebundenen Scraping-Job in die Warteschlange, der nach Abschluss früherer Jobs ausgeführt wird. Anschließend ersetzt es das bisherige Korpus und generiert die Embeddings neu. Die aktuelle Laufzeit lehnt Konfigurationen mit mehreren Quellen ab.

Verwenden Sie --json in der Automatisierung, um Version, Umgebung, Anwendungsstatus und Scraping-Job-ID als strukturierte Ausgabe zu erhalten.

Status, Promotion und Rollback

bunx @openstaticfish/chattybox-cli status --environment production

bunx @openstaticfish/chattybox-cli promote \
  --version '<config-version-id>' \
  --environment production

bunx @openstaticfish/chattybox-cli rollback \
  --version '<known-good-config-version-id>' \
  --environment production

Ein Rollback befördert eine ältere unveränderliche Version und wendet sie erneut an; die Deployment-Historie wird dabei nie umgeschrieben. Die Konfiguration wird sofort wiederhergestellt, während eine erforderliche Inhaltsaktualisierung asynchron fortgesetzt wird.

CI/CD-Workflows

Fügen Sie CHATTYBOX_DEPLOY_TOKEN als verschlüsseltes, auf die Produktion beschränktes Secret bei Ihrem CI-Anbieter hinzu. Fügen Sie CHATTYBOX_API_URL als Secret oder Variable hinzu und verwenden Sie die Widget-API-URL aus dem Embed-Tab des Projekts. Führen Sie die Validierung für Pull Requests aus, beschränken Sie Produktionsdeployments jedoch auf Ihren geschützten Standardbranch oder eine genehmigte Deployment-Umgebung.

GitHub Actions

name: Deploy ChattyBox configuration

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bunx @openstaticfish/chattybox-cli validate

  deploy:
    if: github.event_name == 'push'
    needs: validate
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - name: Validate and deploy
        env:
          CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
          CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
        run: |
          bunx @openstaticfish/chattybox-cli validate
          bunx @openstaticfish/chattybox-cli deploy --environment production --json

Verwenden Sie ein auf die Produktionsumgebung begrenztes Secret und verlangen Sie eine Deployment-Genehmigung, wenn Ihr Repository dies unterstützt. Die CLI zeichnet gängige CI-Commit- und Branch-Variablen zusammen mit der unveränderlichen Version auf.

GitLab CI/CD

Speichern Sie beide Werte unter Settings → CI/CD → Variables. Schützen und maskieren Sie das Deployment-Token und beschränken Sie es auf die Umgebung production.

.gitlab-ci.yml

image: oven/bun:1

validate_chattybox:
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - bunx @openstaticfish/chattybox-cli validate

deploy_chattybox:
  stage: deploy
  environment: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - bunx @openstaticfish/chattybox-cli validate
    - bunx @openstaticfish/chattybox-cli deploy --environment production --json

GitLab stellt CHATTYBOX_DEPLOY_TOKEN und CHATTYBOX_API_URL dem Job automatisch unter ihren Variablennamen zur Verfügung. Verwenden Sie einen geschützten Standardbranch, damit geschützte Variablen nicht für nicht vertrauenswürdige Branches verfügbar sind.

Bitbucket Pipelines

Fügen Sie beide Werte als Deployment-Variablen unter Repository settings → Pipelines → Deployments → Production hinzu. Markieren Sie das Deployment-Token als geschützt.

bitbucket-pipelines.yml

image: oven/bun:1

pipelines:
  pull-requests:
    '**':
      - step:
          name: Validate ChattyBox configuration
          script:
            - bunx @openstaticfish/chattybox-cli validate
  branches:
    main:
      - step:
          name: Deploy ChattyBox configuration
          deployment: Production
          script:
            - bunx @openstaticfish/chattybox-cli validate
            - bunx @openstaticfish/chattybox-cli deploy --environment production --json

Ersetzen Sie main, wenn Ihr Standardbranch anders heißt. Bitbucket fügt Deployment-Variablen nur Schritten hinzu, die dieser Deployment-Umgebung zugeordnet sind.

Konfigurationsabschnitte

Abschnitt	Zweck
schemaVersion	Wählt den öffentlichen Konfigurationsvertrag aus. Derzeit wird Version 1 unterstützt.
assistant	Benennt den Assistenten und definiert optional sein Prompt-Profil und seinen System-Prompt.
knowledge.sources	Deklariert Website-Quellen und optionale Ein- und Ausschlussmuster.
runtime	Enthält Laufzeitvorgaben wie die Locale.
widget	Beschreibt optionale Darstellungseinstellungen für das gehostete Widget.

Typisierter Konfigurationshelfer

Installieren Sie das Konfigurationspaket, wenn Sie separate TypeScript-Werkzeuge rund um das Schema entwickeln:

bun add -d @openstaticfish/chattybox-config

import { defineConfig } from '@openstaticfish/chattybox-config';

const config = defineConfig({
  schemaVersion: '1',
  assistant: { name: 'Support' },
  knowledge: {
    sources: [{ type: 'website', url: 'https://docs.example.com' }],
  },
  widget: { enabled: true },
});

Die CLI selbst liest JSON-Dateien. defineConfig() ist für typisierte Anwendungen oder Build-Werkzeuge vorgesehen; TypeScript-Dateien werden dadurch nicht direkt von der CLI geladen.

Für eine heute einsatzbereite Produktionsintegration verwenden Sie das gehostete Widget oder erstellen Sie mit dem JavaScript-SDK eine eigene Benutzeroberfläche.