CLI i wdrażanie konfiguracji

CLI tworzy, weryfikuje i wdraża niezmienne wersje konfiguracji ChattyBox, a także je promuje i przywraca. Tokeny wdrażania są przypisane do jednego projektu i wybranych środowisk, dzięki czemu ten sam proces sprawdza się w lokalnym środowisku programistycznym i w CI.

Tworzenie konfiguracji

bunx @openstaticfish/chattybox-cli init

To polecenie tworzy plik chattybox.config.json:

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

Użyj niestandardowej ścieżki, gdy konfiguracja ma znajdować się w podkatalogu:

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

Weryfikacja lokalna lub w CI

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

Weryfikacja sprawdza schemat, wymaganą nazwę asystenta, obsługiwane typy źródeł, adresy URL HTTP źródeł, dodatnie limity stron i kolory widżetu. Pomyślna weryfikacja nie wdraża ani nie modyfikuje stanu zdalnego.

Tworzenie tokenu wdrażania

Otwórz kartę Settings projektu, znajdź Config deployment tokens i utwórz token dla środowisk, które może zmieniać Twój proces. Skopiuj go od razu — ChattyBox przechowuje tylko jego skrót i nie może wyświetlić go ponownie.

Ustaw token i adres URL API widżetu z karty Embed projektu:

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

Nigdy nie zatwierdzaj tokenu w repozytorium. Przechowuj go w zaszyfrowanym magazynie sekretów dostawcy CI.

Po zweryfikowaniu procesu wdrażania włącz Config-as-code lock w tej samej sekcji ustawień. Blokada wyłącza zmiany konfiguracji i korpusu z poziomu panelu, więc środowisko wykonawcze mogą zmieniać tylko tokeny wdrażania z odpowiednim zakresem. Tworzenie i unieważnianie tokenów pozostaje dostępne, jeśli dane uwierzytelniające CI wymagają rotacji.

Wdrażanie konfiguracji

Wdrożenie tworzy niezmienną wersję i promuje ją do wybranego środowiska:

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

Promocje do development i preview są rejestrowane do wglądu. Promocje do production atomowo stosują w aktywnym projekcie prompt asystenta, odpowiedź awaryjną, ustawienia widżetu, ustawienia regionalne i źródło witryny. Konfiguracja produkcyjna musi zawierać dokładnie jedno źródło witryny. Wdrożenie umieszcza w kolejce skanowanie powiązane z wersją, które zostanie uruchomione po zakończeniu wcześniejszych zadań. Następnie zastępuje poprzedni korpus i ponownie generuje embeddingi. Obecne środowisko wykonawcze odrzuca konfiguracje z wieloma źródłami.

Użyj --json w automatyzacji, aby otrzymać wersję, środowisko, status aplikacji i identyfikator zadania skanowania w postaci danych strukturalnych.

Status, promocja i 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

Rollback promuje i ponownie stosuje starszą niezmienną wersję; nigdy nie przepisuje historii wdrożeń. Konfiguracja zostaje przywrócona natychmiast, a wszelkie wymagane odświeżenie treści jest kontynuowane asynchronicznie.

GitHub Actions

- name: Deploy ChattyBox configuration
  env:
    CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
    CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
  run: bunx @openstaticfish/chattybox-cli deploy --environment production --json

Użyj sekretu produkcyjnego przypisanego do środowiska i wymagaj zatwierdzenia wdrożenia, jeśli Twoje repozytorium to obsługuje. CLI zapisuje typowe zmienne CI dotyczące commita i gałęzi razem z niezmienną wersją.

Sekcje konfiguracji

Sekcja	Przeznaczenie
schemaVersion	Wybiera publiczny kontrakt konfiguracji. Obecnie obsługiwana jest wersja 1.
assistant	Określa nazwę asystenta oraz opcjonalnie jego profil promptu i prompt systemowy.
knowledge.sources	Deklaruje źródła internetowe oraz opcjonalne wzorce uwzględniania i wykluczania.
runtime	Zawiera domyślne ustawienia środowiska wykonawczego, takie jak locale.
widget	Opisuje opcjonalne ustawienia wyglądu hostowanego widżetu.

Typowany pomocnik konfiguracji

Zainstaluj pakiet konfiguracyjny, jeśli tworzysz osobne narzędzia TypeScript korzystające ze schematu:

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 },
});

Samo CLI odczytuje pliki JSON. defineConfig() jest przeznaczone dla typowanych aplikacji lub narzędzi kompilacji; nie umożliwia CLI bezpośredniego wczytywania plików TypeScript.

Aby już dziś uzyskać działającą integrację produkcyjną, użyj hostowanego widżetu lub zbuduj własny interfejs za pomocą SDK JavaScript.