CLI a nasazování konfigurace

CLI vytváří, ověřuje, nasazuje, propaguje a vrací neměnné verze konfigurace ChattyBoxu. Nasazovací tokeny jsou omezené na jeden projekt a vybraná prostředí, takže stejný postup je vhodný pro místní vývoj i CI.

Vytvoření konfigurace

bunx @openstaticfish/chattybox-cli init

Tím se vytvoří soubor chattybox.config.json:

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

Pokud konfigurace patří do podadresáře, použijte vlastní cestu:

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

Místní ověření nebo ověření v CI

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

Ověření kontroluje schéma, povinný název asistenta, podporované typy zdrojů, adresy URL zdrojů HTTP, kladné limity stránek a barvy widgetu. Úspěšné ověření nic nenasazuje ani nemění vzdálený stav.

Vytvoření nasazovacího tokenu

Otevřete kartu projektu Settings, vyhledejte Config deployment tokens a vytvořte token pro prostředí, která může váš pracovní postup měnit. Ihned ho zkopírujte; ChattyBox ukládá pouze jeho hash a znovu ho nemůže zobrazit.

Nastavte token a URL API widgetu z karty projektu Embed:

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

Token nikdy necommitujte. Uložte ho do šifrovaného úložiště tajných údajů poskytovatele CI.

Po ověření pracovního postupu nasazování povolte ve stejné části nastavení Config-as-code lock. Zámek zakáže změny konfigurace a korpusu z dashboardu, takže běhové prostředí mohou měnit pouze nasazovací tokeny s příslušným rozsahem. Vytváření a odvolávání tokenů zůstane k dispozici, pokud je potřeba obměnit přihlašovací údaj CI.

Nasazení konfigurace

Nasazení vytvoří neměnnou verzi a propaguje ji do vybraného prostředí:

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

Propagace do vývojového a preview prostředí se zaznamenává ke kontrole. Propagace do produkce atomicky aplikuje prompt asistenta, záložní odpověď, nastavení widgetu, jazykové nastavení a zdroj webu na živý projekt. Produkční konfigurace musí obsahovat přesně jeden zdroj webu. Nasazení zařadí do fronty scraping navázaný na verzi, který se spustí po dokončení předchozích úloh. Poté nahradí předchozí korpus a znovu vygeneruje embeddingy. Aktuální runtime odmítá konfigurace s více zdroji.

V automatizaci použijte --json, abyste jako strukturovaný výstup získali verzi, prostředí, stav aplikace a ID úlohy scrapingu.

Stav, propagace a návrat

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

Návrat propaguje a znovu aplikuje starší neměnnou verzi; nikdy nepřepisuje historii nasazení. Konfiguraci obnoví okamžitě, zatímco případná potřebná aktualizace obsahu pokračuje asynchronně.

CI/CD workflow

Přidejte CHATTYBOX_DEPLOY_TOKEN jako šifrovaný tajný údaj s rozsahem na produkci u svého poskytovatele CI. Přidejte CHATTYBOX_API_URL jako tajný údaj nebo proměnnou s URL API widgetu z karty Embed projektu. Spouštějte validaci v pull requestech, ale nasazení do produkce omezte na chráněnou výchozí větev nebo schválené nasazovací prostředí.

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

Použijte produkční tajný údaj omezený na prostředí a vyžadujte schválení nasazení, pokud to váš repozitář podporuje. CLI zaznamenává běžné CI proměnné commitu a větve spolu s neměnnou verzí.

GitLab CI/CD

Obě hodnoty uložte v Settings → CI/CD → Variables. Token nasazení chraňte, zamaskujte a omezte jeho rozsah na prostředí 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 automaticky zpřístupňuje CHATTYBOX_DEPLOY_TOKEN a CHATTYBOX_API_URL úloze pod jejich názvy proměnných. Použijte chráněnou výchozí větev, aby chráněné proměnné nebyly dostupné nedůvěryhodným větvím.

Bitbucket Pipelines

Přidejte obě hodnoty jako proměnné nasazení v Repository settings → Pipelines → Deployments → Production. Označte token nasazení jako zabezpečený.

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

Nahraďte main, pokud má vaše výchozí větev jiný název. Bitbucket vkládá proměnné nasazení pouze do kroků přidružených k danému nasazovacímu prostředí.

Části konfigurace

Část	Účel
schemaVersion	Vybírá veřejný konfigurační kontrakt. V současnosti je podporována verze 1.
assistant	Pojmenovává asistenta a volitelně definuje jeho profil pokynů a systémový pokyn.
knowledge.sources	Deklaruje zdroje webových stránek a volitelné vzory pro zahrnutí či vyloučení.
runtime	Obsahuje výchozí hodnoty běhového prostředí, například locale.
widget	Popisuje volitelná nastavení vzhledu hostovaného widgetu.

Pomocná funkce pro typovanou konfiguraci

Při vytváření samostatných nástrojů TypeScript nad schématem nainstalujte konfigurační balíček:

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

Samotné CLI čte soubory JSON. defineConfig() je určené pro typované aplikační nebo sestavovací nástroje; neumožňuje CLI přímo načítat soubory TypeScript.

Pro funkční produkční integraci dnes použijte hostovaný widget nebo vytvořte vlastní rozhraní pomocí JavaScript SDK.